使用 Claude Code 的规格驱动开发：实操教程

什么是规格驱动开发？

规格驱动开发基于按序衔接的三份文档：一份说明要改什么，一份将步骤具体化的计划，以及依照该计划编写的代码；每两份文档之间都有一次人工复审。

规格驱动开发中，一个功能要通过的三个复审关口。

所谓规格（spec），是在写任何代码之前，用通俗语言写就的一份短文档，说明这次改动应该实现什么。比如一个功能“允许用户导出其数据”。该功能的规格会明确那些原本需要智能体去猜的答案。它会列出：

• 支持的文件格式
• 交付方式
• 半途导出时的行为
• 有意排除在外的功能范围

下面是 Claude Code 为我一个基于 Telegram 的自律应用里 workout-shape-verification 变更写的规格开头实录。此变更用心率曲线随时间的形态检查，替换了脆弱的心率阈值法：

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

接下来是计划文档。它把上述规格拆解为可逐一执行的编号任务，每个任务都指明文件、改动、顺序与测试。规格回答“是什么”，计划回答“分几步、每一步做什么”。 

代码最后产出，且严格按计划逐项完成。

三份文档，每两份之间一次人工复审。先审规格，再出计划；先审计划，再写代码；写完代码，合并前再审一次。

规格驱动开发与计划模式有何不同

您也许用过Claude Code 内置的计划模式（按 Shift+Tab 两次进入），会好奇两者差别。计划模式会在一次对话回合内产出一个计划。该计划仅存在于记忆中，没有落地的规格文件，也没有阶段间的复审步骤。

规格驱动开发会将规格和计划都持久化为磁盘文件。每份文件在进入下一阶段前都要经过人审，并且这些产物可跨会话保存。计划模式把开发的两个阶段压缩成一次对话回合。这在小任务上可行，但一旦代码库变大、开始服务真实用户，就会失灵。

为什么“凭感觉写码”会触顶

Vibe-coding 适用于原型、单文件和一次性脚本。面对需要对用户负责的真实应用与大型既有代码库，它就会吃力。一个可参考的分界线大约在 4 个文件：任何改动涉及到这么多文件，就需要一份规格；任何有明确目标状态的重构，或“到底要做什么才算对？”是难点的任务，也都需要规格。

失败的原因很清楚。像“给我的应用加上照片分享”这样含糊的提示，会迫使模型去猜数以千计未表述的需求。

就拿其中一个需求：通知偏好。产品经理默认按渠道开关；后端实现成总开关；前端假设走 OS 级集成。三句话的四种合理解读，做出四个不同的产品。

规格驱动开发中的每个复审步骤，都会在问题变昂贵之前，捕捉到不同类别的错误。规格评审能拦住范围蔓延和“治标不治本”的错误定位；计划评审能拦住半拉子实现和与现有模式冲突的做法；代码评审能拦住那些看起来没问题、却在第一条失败测试上就崩溃的计划。

投入是真实的，而且是慢慢见效。规格阶段要在任何代码运行前花上几个小时写文档，前几次做起来会比 vibe-coding 慢。就我自己而言，差不多到第四或第五个功能时才开始打平。到了那会儿，规格已经能抓住那些我本来会发布、并在一周后返工的设计错误。

接下来的三节将演示三种在 Claude Code 内运行该工作流的开源方案，按其约束强度从轻到重排序。

Superpowers

Superpowers 是三者中最轻量的。我日常用它，也是本文会最详细讲的。

Superpowers 是什么？

Superpowers 是 Jesse Vincent 开发的 Claude Code 插件（obra/superpowers，MIT 许可），在 GitHub 上大约有 194k 颗星。 

它附带一组技能（skills）。Claude 技能，在 Claude Code 中，是一份可按需加载、用于执行特定工作流的命名指令文件。Superpowers 提供的技能，会把 Claude Code 约束在规格驱动的循环里，避免它直接跳到写代码。

Superpowers 项目页（GitHub）。

如何安装 Superpowers

通过 Claude Code 官方插件市场安装：

/plugin install superpowers@claude-plugins-official

一个 SessionStart 钩子会自动加载 using-superpowers 技能，所以从您开始打字那一刻起，工作流就已生效。(Claude code hooks 是在特定生命周期事件触发的脚本。) 无需针对每个项目单独接线配置。

Superpowers 的工作流

此后，有四个技能管理您的日常工作：

子代理是由父实例派遣的、在独立上下文窗口中专注办事的另一个 Claude Code 实例。上表中的评审代理以子代理方式运行，意味着它们在没有父实例先入之见的情况下“冷读”代码。

如何使用 Superpowers

您只需用日常语言描述诉求即可调用这四个技能。比如说“我们来讨论一个新功能”，就会触发 brainstorming 技能并自动开启规格对话。其他技能也以同样方式触发。

四个 Superpowers 技能依次进行，两处人工复审点介于 brainstorming 和 writing-plans 之间。

下面的演练继续使用上文规格摘录中的 workout-shape-verification 功能。

阶段 1：从头脑风暴到规格

我打开 Claude Code，输入：

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

brainstorming 技能开始接管，并会追问大约十个问题，其中包括：

• 什么样的“形态”才算正确
• 要合并哪些数据流
• 对那些形态正确却未过旧阈值的会话如何处理
• 此变更是否也适用于跑步和骑行

此处有两个人工复审点。其一是设计评审——我确认自己给出的答案确实符合预期。其二是规格评审——我阅读 Claude 写就的文件，并在任何计划工作开始前予以批准。

阶段 2：从规格到计划

我运行 writing-plans 技能。它读取已批准的规格，并生成一份含四部分的计划文件：

• “完成”定义
• 文件映射（涉及到的文件）
• 用户旅程（沿演示路径）
• 编号任务清单（复选框式子步骤） 

我审阅该计划，对顺序不当或颗粒度过粗的任务提出修改意见，然后批准。

阶段 3：从计划到代码

我运行 subagent-driven-development。从这一步起，循环便可自动运行。对计划中的每个任务，该技能会：

1. 先写一个失败测试
2. 再写通过该测试的实现
3. 随后重构
4. 派发一个“冷读”差异的代码评审子代理

若评审指出问题，循环会先修复再进入下一个任务。此阶段内没有人工复审点；这个阶段真正依赖的是之前的两次复审。

阶段 4：全量差异评审

计划完成后，我运行 requesting-code-review。一个全新的子代理会根据规格与计划审阅整个 diff，并提交评审意见。我据此调整后再合并。

当计划中的某个任务暴露出与规格冲突时，循环会停下来询问。我可以编辑规格（或交给 Claude 编辑），并重新生成受影响的任务。另一种做法是在任务本身做一次性更正。Superpowers 不会悄悄绕开规格错误。

磁盘上的真实规格与计划

下面是在编辑器中打开的 workout-shape-verification 功能的规格：

brainstorming 技能写入后，规格文件在磁盘上的样子。

页眉带有 Created、Status 和 Supersedes 字段，这是 brainstorming 技能的默认输出。接着是 Problem 段落。它不包含代码。截图之外的内容还包括拟议方案、变更应触及与不应触及的约束等章节。

与之配套的计划以 User Journey 开篇：

writing-plans 技能依据已批准的规格生成的计划文件。

该旅程以五步为一组走通演示路径，每一步都标明具体命令、文件与参数。随后出现的编号任务，会把每一步转化为 subagent-driven-development 技能可依次执行的复选框式子步骤。

两份文档的配对关系如下：

规格与计划并排。规格回答“改什么、为何改”，计划回答“分几步做”。

对于更大的规格与计划，我会额外加一步：红队检视。在签字前，我会让一名或多名 Opus 子代理“冷读”规格，从不同角度寻找漏洞。这是个人习惯，不是 Superpowers 的功能，但它帮我抓到了足够多的错误假设，所以我一直保留。

何时不应选择 Superpowers

Superpowers 适合在单一仓库上的个人作业。当整个代码库能装进一个 Claude Code 会话、而且您确实会认真读 2 页规格时，它效果最佳。更详细的比较见下文如何在三者间做选择。简言之：Superpowers 不擅长跨多仓库的功能，以及需要明确角色分工的工作。

有位开发者在对该插件的公开吐槽中，指出了第四种失败模式：“哪怕是最小的任务也要半天，Claude 不停拉起子代理、写完全用不着的计划。改个 CSS 现在都要很久。”

解决方法是：微小改动时跳过 Superpowers。只有触发 brainstorming 时技能才会激活。一行 CSS 的编辑完全可以在 Claude Code 中进行，而不触发规格循环。真正的失败模式，是把该工作流滥用于不需要规格的工作。

GitHub Spec Kit

当规格需要在单次 Claude Code 会话之外长期存在时，选 Spec Kit。当需要让从不打开 Claude Code 的人阅读规格时，也应选它。

GitHub spec-kit 是什么？

Spec Kit 是一个 GitHub 项目（github/spec-kit，MIT 许可），由 GitHub 亲自维护，拥有 100k+ 星标。它附带一个 CLI，以及一个能在各大 AI 编码代理上以同样方式运行的工作流。Claude Code、Cursor、Aider、Cline 与 Roo Code 均受支持。正是这种与代理无关的设计，让规格得以在 Claude Code 之外生存。

Spec Kit 项目页（GitHub）。

如何安装 GitHub spec-kit

目前尚无官方 PyPI 包，因此使用 uv 从 Git 标签安装 CLI：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

将 vX.Y.Z 替换为当前发行标签。软件包名为 specify-cli，注册的命令是 specify。

GitHub spec-kit 的工作流

该工作流通过九个斜杠命令运行，这些命令会被 CLI 安装到您的代理的斜杠命令列表中。六个是循环的核心命令，三个是覆盖核心循环之外场景的可选命令。

命令组与动词之间的分隔符是点而非冒号：写 /speckit.specify，不要写 /speckit:specify。 

九个 Spec Kit 斜杠命令：六个核心命令在主流水线上，三个可选命令悬挂其下。

这些命令产出的仍是您在 Superpowers 部分见到的规格与计划，同样会写入磁盘并由 Git 跟踪。不同在于可移植性：Spec Kit 的产物面向任何 AI 编码代理，而非仅限 Claude Code，且工作流面向通过 GitHub Pull Request 进行的干系人评审，而不是某一工具循环的副产品。

何时使用 GitHub spec-kit

在个人项目中，您大概率不需要 Spec Kit。以下情况优先考虑：

• 项目发展到多人协作
• 您的规格需要供从不打开 Claude Code 的人审阅
• 部分工作要用非 Claude Code 的代理来跑
• 您希望使用一种不依赖某一工具、且数月后仍清晰可读的规格格式

BMAD 方法

Spec Kit 管理的是产物，BMAD 管理的是人。它将从规格到代码的工作流拆分为四个阶段，每个阶段由一个具名角色代理负责。

什么是 BMAD？

BMAD-METHOD（bmad-code-org/BMAD-METHOD，MIT 许可，约 47k 星）目前为 v6。按项目文档，其首字母缩写展开为“Breakthrough Method for Agile AI-Driven Development（面向敏捷 AI 驱动开发的突破性方法）”。它运行在 Claude Code 等代理之上，以模块生态形式安装。默认安装提供一个核心模块，包含 6 个角色代理、4 个工作阶段，以及 34 个以上的命名工作流。

BMAD-METHOD 项目页（GitHub）。

如何安装 BMAD

用 Node 安装 BMAD：

npx bmad-method install

六个角色代理是提示词人格，用户可在代理宿主中通过名字激活。在 Claude Code 中，这意味着输入 BMAD 安装的激活命令。请查看 README 以获取确切语法（不同版本会有调整）。 

BMAD 的协作代理与产物

激活后，代理会采用该角色的指令、语气与输出，直到您切换人格。六个角色分别是：

• 分析师 Mary
• 技术写作者 Paige
• 产品经理 John
• UX 设计师 Sally
• 架构师 Winston
• 开发者 Amelia

v6 中缺少您或许会期待的两个角色：没有 Scrum Master 代理，也没有独立的 QA 代理。Sprint 规划与故事准备由开发者代理承担，QA 测试生成是开发者触发的一个工作流。

产物集合比单一规格更厚重，包含：

• 产品简报
• PRD（产品需求文档）
• UX 规格
• 架构文档
• 按用户故事拆分的史诗（功能上线后用户可完成的动作）

PRD 与架构文档共同承担了 Superpowers 规格的角色。两者拆分后分别由两个角色代理产出，并采用更正式的格式。整个产物集覆盖完整的软件开发生命周期，每个功能都从上一层继承上下文。

BMAD 的工作流

v6 工作流分四个阶段。

四个 BMAD 阶段与各自的角色代理。Quick Flow 轨道为小型工作跳过前三阶段。

阶段 1：分析（可选）。Mary（分析师）与 Paige（技术写作者）进行调研，并产出产品简报。若您已清楚要做什么，可跳过该阶段。

阶段 2：规划（必选）。John（产品经理）撰写 PRD。若功能涉及界面，Sally（UX 设计师）补充 UX 规格。

阶段 3：方案设计，由 Winston 主导。架构师先起草架构，随后 John 将需求拆分为史诗与用户故事。把故事放在架构之后是 v6 的选择，让故事以真实实现边界来定尺寸。Winston 接着进行“实施就绪”检查，给出 PASS、CONCERNS 或 FAIL 的判定。

阶段 4：实施，由 Amelia（开发者）逐个故事推进：创建故事、构建实现并做代码评审。完成一个完整史诗后，她会触发覆盖全史诗的 QA 测试生成工作流。Claude Code 在此阶段以 Amelia 的身份进行实际编码。

对于小而明确的工作，BMAD 提供“Quick Flow”轨道，直接激活 Amelia，跳过前三阶段。激活命令见 BMAD 的 README（具体语法会随版本变化）。Quick Flow 不产出 PRD 与架构文档，只写一个简短的用户故事和满足它的代码——这正是“改个按钮用不着这么大阵仗”的答案。

当实施中发现规格有误，BMAD 会回到 Winston 的第三阶段判定。若为 FAIL，回退到第二阶段重写 PRD；若为 CONCERNS，则带着 Winston 标注的风险继续该故事。这样的分流能在小的不一致上继续推进、在大的问题上果断止步。

复杂度何时值得

BMAD 在有真实用户、长期运行的项目上见效；也契合多开发者团队，便于人员之间移交。阶段与角色的分离，只有在节省的时间多于其带来的开销时才划算。

对一人副项目而言，它不太合适。独自开发时，把工作拆成四个阶段、六个代理，大多是额外负担；团队里没有第二个人，角色分离的意义也不大。

如何在三种框架间做选择

三个规则决定选择：

• 若规格需要被从不打开 Claude Code 的人阅读，或需作为长期产物存于 Git，请用 Spec Kit。
• 若多人按不同角色协作，或有真正的 PM 类干系人参与，请用 BMAD。
• 其他情况，用 Superpowers。

关于您项目的三个问题，对应四种框架选择。

决策树上还有第四个选项：将 Spec Kit 与 Superpowers 组合。用 Spec Kit 负责规格阶段，让产物进入 Git 以便跨团队评审。然后在一行配置中将 Superpowers 的 subagent-driven-development 技能指向 Spec Kit 的计划文件。这样既能获得 Spec Kit 的耐久规格，又能保留 Superpowers 的紧凑实施循环。

结语

规格驱动开发由三份按序文档构成。规格说明要构建什么，计划说明分几步做，代码遵循计划实现。每两份之间都有人类复审。

按上面的决策树选择一个框架；对大多数读者而言，结果多半是 Superpowers。安装它，然后选一个您本来会“凭感觉写码”的功能，最好是涉及 3 到 5 个文件的改动。从头脑风暴、规格、计划到执行，完整跑一遍。一次真实的实践，比任何说明都更能学会这套流程。

如果您想先复习 Claude Code 基础，DataCamp 提供 一篇实用的 Claude Code 教程、一份 覆盖计划模式、CLAUDE.md 与 TDD 的最佳实践指南，以及一篇 针对计划模式本身的深度解析。