Claude Code 加 OpenSpec 让 AI 编程从临场发挥进化到工程化交付

「让 AI 写一段代码」很简单，「让 AI 交付一份能上线的需求」很难。本文用一份真实项目的实战流程，讲清楚 Claude Code 加 OpenSpec 怎么把 AI 编程从临场发挥推到工程化交付，并明确什么时候是刚需、什么时候是过度工程。

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

• 为什么 AI 编程到真实业务就开始翻车
• OpenSpec 三件套（proposal / design / tasks）各自的角色
• Claude Code 怎么和 OpenSpec 协同：规范层、流程层、执行层
• 从一句话需求到 archive 的完整 13 步实战
• 任务分流：轻 / 中 / 大什么时候走 SDD，什么时候直接做
• 三件套常见反模式与失败逃生路径
• 一份可直接复制的 CLAUDE.md 配置片段

# 痛点与解决方案

「让 AI 写一段代码」和「让 AI 交付一个能上线的功能」之间，差的不是模型能力，是工程化。我们都遇到过这些场景：

• 需求理解偏差：一句话「加个登录」，AI 实现完发现接口契约、UI 风格、错误码全和现有系统对不齐，返工三轮
• 决策记录缺失：为什么用 JWT 不用 Session？两周后再翻代码完全想不起来理由
• 工程纪律失守：测试没写、类型没过、构建没跑就声称「完成」，CI 一跑红一片
• 多人协作冲突：两个工程师各让 AI 帮自己加同一个模块，两套方案在 review 时打架

问题不在 AI，在我们没给它一份能跟着走的蓝图。OpenSpec 就是解决这个问题的：它把「一句话需求」拆解成 proposal.md + design.md + tasks.md 三份结构化文档，让 AI 和人都按同一份规范执行。配合 Claude Code 的 Agent runtime，整个流程就跑通了。

# 一、为什么要 Spec 先行

Spec-Driven Development（SDD，规范驱动开发）不是新概念，传统 PRD / RFC 都是它的形态。但传统文档的问题是重、慢、写完就锁死。AI 时代需要新的 SDD 范式：

OpenSpec 的核心思想是轻、可迭代、谁实施谁也参与写规范。这和「先评审三个月再开工」的传统 SDD 是两套哲学。

# 二、OpenSpec 三件套各自的角色

每份变更落在 openspec/changes/<change-id>/ 下，标配三个文件加一个 specs/ 目录：

openspec/
├── specs/                    # 当前系统的事实来源（项目规范）
└── changes/
    └── <change-id>/
        ├── proposal.md       # 为什么要做：背景、目标、成功标准
        ├── design.md         # 怎么做：架构决策、接口设计、数据流
        ├── tasks.md          # 实施清单：可执行的具体任务
        └── specs/            # 本次变更涉及的 capability 规范
            └── <capability>/
                └── spec.md

三个文件的边界要划清楚，否则会写串：

• proposal.md —— 「为什么做」。说清楚痛点、目标、不做会怎样、成功标准。不写实现细节
• design.md —— 「怎么做」。架构选型、接口契约、数据流、依赖关系、关键决策的取舍理由。不写任务清单
• tasks.md —— 「做什么」。可执行的产品 / 规范层任务，用户视角的可验证成果项。不写文件级实现步骤

注意 tasks.md 不是 plan。它说「做什么」，不说「怎么做」。如果你要文件级的实施步骤，那是 superpowers 的 writing-plans 该干的事。

# 三、Claude Code 怎么和 OpenSpec 协同

OpenSpec 只产规范，不写代码。Claude Code 是 Agent runtime，能跑代码、跑工具、跑测试。两者协同的关键是职责分层：

• 规范层（OpenSpec）：产出 proposal / design / tasks，不写代码
• 流程层（superpowers）：plan / brainstorm / debug / TDD / verify / review
• 执行层（gstack）：浏览器 / QA / ship / deploy / canary / 护栏

类比一下：OpenSpec 是蓝图，superpowers 是大脑，gstack 是手脚。

三者通过文件和命令传递信息，不靠隐式状态：

• OpenSpec 把 tasks.md 交给 superpowers 的 executing-plans
• superpowers 把执行结果交给 gstack 验证
• gstack 把验证结果反馈给 superpowers 决定下一步
• 出现契约错误时回到 OpenSpec 修订 design.md