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

# 四、典型工作流：从一句话到 archive

下面是一个真实项目里跑过的完整流程。需求是「给面试题站点加一个收藏夹功能」，影响数据库、API、UI、SEO，属于典型中型任务。

# 第 1 步 propose 阶段

/opsx:propose 给面试题站点加收藏夹功能，登录用户可以收藏题目，能在个人中心查看

Claude Code 会拉起 OpenSpec 流程，引导你回答几个关键问题：

• 这个功能解决什么问题？（proposal）
• 目标用户是谁？典型使用路径？
• 不做会怎样？什么是「失败」？
• 哪些已有 capability 受影响？

产出 openspec/changes/add-favorites/proposal.md。

# 第 2 步 design 阶段

/opsx:continue

进入设计环节。Claude Code 会和你一起讨论：

• 数据存哪里？（Prisma 加 Favorite 表 vs 复用 User.meta JSON 字段）
• API 怎么设计？（REST /api/favorites vs Server Action）
• UI 入口在哪？（题目页面右上角按钮 / 个人中心 Tab）
• 鉴权怎么做？（已有 NextAuth session）
• SEO 怎么处理？（收藏页要不要进 sitemap）

每个决策都写进 design.md，并标明取舍理由。这一步省略掉，三个月后你就忘了为什么不用 JSON 字段了。

# 第 3 步 tasks 阶段

/opsx:continue

把 design 落到可执行任务：

## Tasks

- [ ] T1: 扩展 Prisma schema，加 Favorite 模型与 User 关联
- [ ] T2: 实现 Server Action：addFavorite / removeFavorite / listFavorites
- [ ] T3: 题目页面加收藏按钮（shadcn Button + 收藏状态）
- [ ] T4: 个人中心新增 Tab：我的收藏
- [ ] T5: 收藏页支持分页 + 取消收藏
- [ ] T6: 更新 sitemap 排除个人收藏页（非公开内容）
- [ ] T7: 加 e2e 测试覆盖收藏 → 取消 → 列表

每条都是「可验证的成果」，不写「修改 src/xxx/yyy.tsx」这种实现细节。

# 第 4 步 brainstorm 收敛（可选）

如果 design.md 里有大决策没确定，调用 superpowers 的 brainstorming skill 探索 2-3 个方案，挑一个写回 design.md。不要在 design 之后再 brainstorm，那是返工信号。

# 第 5 步 writing-plans

# 调用 superpowers writing-plans skill

把 tasks.md 翻译成文件级、命令级的实施计划，落到 openspec/changes/add-favorites/plan.md（注：OpenSpec 项目下覆盖 superpowers 默认 docs/superpowers/plans/ 路径）。

# 第 6 步 创建 worktree

# 调用 using-git-worktrees skill

把工作分支隔离到独立 worktree，避免主分支被脏掉。

# 第 7 步 executing-plans + TDD

# 调用 executing-plans skill

按 plan 执行，每个任务先写测试、再写实现。重要的是：每个 subtask 完成立即跑 yarn tsc、yarn lint，不要攒到最后。

# 第 8 步 跑 verification

yarn tsc && yarn lint && yarn build:feinterview-poetries-top

并真实输出全部日志。superpowers 的 verification-before-completion 会拦截「无证据声明完成」。

# 第 9 步 跑 /browse 或 /qa

UI 改动用 /browse 抽查关键路由（/blog、/docs、个人中心收藏 Tab），并切换移动端 UA。截图存档。

# 第 10 步 requesting-code-review

# 调用 superpowers requesting-code-review skill

开独立通道做 code review。不要在同一上下文里合并 verification 和 review，会互相污染判断。

# 第 11 步 ship

/ship

走 commit + push + PR，附验证证据和截图。这一步必须用户明确确认，不能 AI 自决。

# 第 12 步 land-and-deploy

/land-and-deploy

CI 通过后合并 + 部署。腾讯云 Docker 链路本地跑 yarn deploy:local:feinterview-poetries-top。

# 第 13 步 archive

/opsx:archive

变更归档到 openspec/changes/archive/2026-05-18-add-favorites/，主 specs/favorites/spec.md 同步更新。这一步是 SDD 闭环的关键：今天的变更变成下一次的事实来源。

# 五、什么时候走 SDD，什么时候直接做

不是所有任务都值得走 13 步。判定标准只有一条：变更是否影响对外可观察行为、接口契约、数据形状或公共 API？

具体例子：