Spec Coding on Tyritic

OpenSpec的概念与基本使用

Sun, 28 Jun 2026 10:00:00 +0800

🧠 Vibe Coding 的痛点和 Spec-Driven Development 的优势

现在用 Cursor、Claude Code 这类 AI 编码助手已经是日常了。大家应该都有一个共同感受：AI 确实能写代码，但要让它持续、稳定地写出你想要的东西，没那么容易。理想状态下，我们希望自己的角色能逐步转变——从纯粹的“代码执行者”，更多地转向“指挥者”和“把关人”：AI 负责具体的代码产出，人负责架构决策、逻辑审批和质量把关。听起来很美好，对吧？但现实往往很骨感。如果在实际操作中缺乏规范，这种协作很容易退化成一种非常随意的状态，也就是现在常说的 “Vibe coding”（凭感觉编程）——脚踩西瓜皮，想到哪写到哪。人边想边写，AI 边猜边生成。这种缺乏约束的开发方式，很快就会暴露出几个致命痛点：

痛点	具体表现	后果
上下文丢失	聊天记录太长，AI 开始"失忆"	反复解释同一件事，心智负担重
AI 自由发挥	没有明确约束，AI 按自己的喜好补全	代码风格混乱，逻辑容易跑偏
需求偏移	边聊边做，缺乏锚点，做着做着就变形了	频繁返工、疯狂 debug
无法追溯	只有最终代码，不知道当初为什么这么设计	维护和交接都很困难

（Spec-Driven Development，规范驱动开发）的核心思想很简单：先写规范，再写代码，用规范约束 AI 的行为边界。

更具体地说，两者的差异可以总结为下面这张表：

维度	传统 AI 编程 (Vibe Coding)	OpenSpec (SDD)
核心驱动	基于对话和感觉	基于结构化规范文档
上下文管理	依赖聊天记录，易丢失	单一真相源 (Single Source of Truth)
可追溯性	难以审计变更原因	完整的提案与决策日志
执行精度	AI 自由发挥空间大	严格按任务清单 (Tasks) 执行

用一个比喻来说：传统的 AI 编程像是"口头协议"——你说一句，AI 做一句，做完就忘；而 SDD 像是"签合同"——先把需求、设计、任务清单白纸黑字写下来，AI 严格按合同执行，执行完还要归档备查。

🏗️ OpenSpec 的核心定位与设计哲学

📖 OpenSpec是什么

OpenSpec 是由 Fission-AI 开源的一套 Spec-Driven Development 框架 + CLI 工具。它形态非常轻量，它通过一套结构化的文件组织方式和指令系统，让 AI 编程助手（如 Codex、CodeBuddy、Claude）能够在明确的"合同"约束下工作。

一组本地 Markdown 文档（openspec/specs/ 与 openspec/changes/）。
一组斜杠命令（/opsx:propose、/opsx:apply、/opsx:archive）。
一个 npm 包：@fission-ai/openspec。

和 Spec Kit 相比，OpenSpec 没有"Constitution 强制条款"那一层；和 Kiro 相比，OpenSpec 不绑定特定 IDE。一句话——它只做"把变更规格化"这一件事，并把这件事做到极致轻量。

🎯 核心口号：Align before code

OpenSpec 的官方口号是 “Align before code”（在写代码之前先对齐）。它强调的是：

需求是合约，不是注释。
规范是 AI 的上下文，不是给人看的文档。
变更必须可追溯、可审计、可回放。

整个工具的设计都围绕这一句话展开——所有功能都为了把"模糊意图"压缩成"AI 能直接消费的契约"。

⚖️ 与其他 SDD 工具的对比

维度	OpenSpec	GitHub Spec Kit	AWS Kiro
形态	本地 CLI + Markdown	Python CLI + Markdown	IDE 内置（基于 Code OSS）
工作流	propose → apply → archive	specify → plan → tasks → implement	requirements → design → tasks
产物	proposal / design / specs / tasks	spec / plan / tasks / constitution	requirements / design / tasks
强项	增量变更、归档	完整宪法、跨工具兼容	IDE 原生、EARS 格式、Agent Hooks
弱项	无项目级强制条款	流程相对重	绑死 IDE、生态封闭
适合	增量功能、长期维护	团队级、企业级	多人协作、复杂项目

一句话选型：想轻、想快、想要变更可追溯，用 OpenSpec；想严肃、想统一、想给 AI 立宪法，用 Spec Kit；想 IDE 全家桶、用 Kiro。

🛠️ OpenSpec 的安装和使用

环境要求:OpenSpec 基于 Node.js 开发，安装前请确保你的环境满足：Node.js：版本 >= 20.19

# 1. 全局安装最新版
npm install -g @fission-ai/openspec@latest

# 2. 验证安装
openspec --version

# 3. 进入你的项目目录，初始化 OpenSpec
cd /path/to/your/python/project
openspec init

# 4. 在交互式菜单中选择你使用的编辑器

🧩 OpenSpec 工作目录

🗂️ 整体结构

这是理解 OpenSpec 的关键部分。用下面这张图来展示整体架构：

执行 openspec init 后，会在项目根目录创建 openspec/ 文件夹，这是整个框架的"大本营"：

openspec/
├── config.yaml          ← 🌐 全局配置（影响所有新变更，归档不动它）
├── specs/               ← 📚 主规范库（真相源，已归档的功能规范）
└── changes/             ← 🔥 活跃变更区
    ├── my-feature/      ← 当前正在开发的变更
    │   ├── .openspec.yaml   ← 变更元数据（schema + 创建日期）
    │   ├── proposal.md      ← 为什么做（背景/目标）
    │   ├── design.md        ← 怎么做（技术方案）
    │   ├── tasks.md         ← 任务清单（To-Do）
    │   └── specs/           ← 增量规范（Delta Specs）
    └── archive/         ← 📦 归档区
        └── 2026-04-07-my-feature/  ← 归档后的变更（整个目录原封不动搬过来）

用一张表把这三个区域的分工与状态总结一下：

区域	路径	作用	状态
真相源	`specs/`	存放已归档、稳定的功能规范	🟢 稳定
活跃变更区	`changes/xxx/`	正在开发的功能提案	🟠 活跃
归档区	`changes/archive/`	已完成变更的历史记录	⚪ 历史

这一设计借鉴了传统软件工程里的"主干 + 变更集“思想：

specs/ 是已经定稿的规范库，是 AI 读"系统当前是什么"的入口。
changes/ 是正在进行的"草稿区”，每一个子目录代表一个待合并的变更。

新功能先在 changes/ 里起草，完工后通过 /opsx:archive 合并到 specs/，整个生命周期都有完整的文件留痕。

🧾 核心工件

在 OpenSpec 工作流的语境中，Artifact（工件）是指在一个变更（Change）推进过程中，按步骤依次创建的结构化文档或文件。

每个变更包含四个核心工件，我把它们比作"合同的四个章节"：四个文件各司其职：

工件	文件	回答的问题	谁来读
提案	`proposal.md`	为什么要做？影响哪些模块？	人 + AI
设计	`design.md`	用什么技术方案？关键决策是什么？	人 + AI
规范	`specs/*.md`	具体怎么做	AI 实现时对齐
任务	`tasks.md`	具体要做哪些事？	AI 实施时逐项打勾

一个常见的反模式是把 proposal.md 写得很长、spec.md 写得很短。事实上 spec.md 才是 AI 实现时的"事实来源"——它写得越具体，AI 跑偏的概率越低。

➕ 变更的"delta"思想

specs/ 下的子目录是按"能力（capability）“组织的，例如 auth/spec.md、billing/spec.md。一次新变更只会产生"差异（delta）"——只描述**新增（ADDED）、修改（MODIFIED）、删除（REMOVED）**的能力，不重写整个文件。

openspec/changes/add-oauth-login/
└── specs/
    └── auth/
        └── spec.md   # 只描述 ADDED Requirements: OAuth 登录相关

归档时 OpenSpec 会自动把这些 delta 合并到 openspec/specs/auth/spec.md，形成活文档。这样既保留了变更历史，又让 specs/ 始终是当前系统的真实写照。

🔄 核心工作流：Propose → Apply → Archive

⌨️ 三个核心命令

OpenSpec 默认是 Core 模式，只有三个核心命令：

`1`	`/opsx:propose → /opsx:apply → /opsx:archive`

/opsx:propose <name>：根据自然语言需求，一键生成 proposal.md + design.md + specs/ + tasks.md。
/opsx:apply：按 tasks.md 逐项实现，每完成一项打勾。
/opsx:archive <name>：把变更归档，delta 合并到 specs/，整个目录从 changes/ 移除。

三个命令的边界极其清楚：

propose 阶段只动 Markdown，不动代码。
apply 阶段才真正写代码。
archive 阶段关闭变更，留下审计痕迹。

🔍 探索模式 /opsx:explore

需求不清时还有 /opsx:explore 兜底。它和 propose 的区别是：

propose 会生成正式文档。
explore 不产生产物，只和 AI 一起梳理思路，把模糊意图问清楚。

实操经验：拿到一个不清晰的需求时，先 /opsx:explore 把问题问透；等需求清晰、边界明确后，再 /opsx:propose 生成正式规范。避免边探索边写规范，导致 spec 反复返工。

🪞 完整生命周期

一个 OpenSpec 变更的完整生命周期是这样的：

需求提出
   ↓
/opsx:explore（可选，需求不清时）
   ↓
/opsx:propose <name>     → 生成 proposal / design / specs / tasks
   ↓
人工 review + 修订规范
   ↓
/opsx:apply              → 按 tasks 逐项实现
   ↓
测试与验证
   ↓
/opsx:archive <name>     → 合并 delta 到 specs/，删除 changes/<name>/

这个流程里有两个**人在环路（Human-in-the-Loop）**的检查点：

propose 之后必须 review 规范。
archive 之前必须验证实现。

跳过任何一个检查点，OpenSpec 就退化为"自动写代码的脚手架”，失去意义。

💻 安装与初始化

📦 前置要求

OpenSpec 的安装门槛非常低：

Node.js 18+
任意一个支持的 AI 工具（Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini CLI、Cline、Trae 等 25+ 工具）

⚙️ 项目初始化

在项目根目录运行：

# 全局安装
npm install -g @fission-ai/openspec

# 初始化（按提示选择 AI 工具）
cd your-project
openspec init

openspec init 会做三件事：

创建 openspec/ 目录。
在所选 AI 工具的配置目录（如 .claude/commands/opsx/）写入斜杠命令定义。
生成一份默认的 AGENTS.md 提示词（告诉 AI 如何使用 OpenSpec）。

提示：如果想用非交互式初始化，可以直接指定工具：openspec init --tools claude。

🎛️ 切换工作模式

OpenSpec 提供两种工作模式：

Core 模式（默认）：3 个核心命令够用，适合大多数项目。
Expanded 模式：解锁更多细粒度命令（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard）。

切换方法：

# 查看当前配置
openspec config profile

# 勾选需要的命令（例如 new、continue、ff、verify、bulk-archive、onboard）
# 然后让 AI 重新识别
openspec update

经验之谈：除非项目特别复杂，否则 Core 模式完全够用。命令越多，记忆负担越大，反而拖慢节奏。

🧪 基本使用：一个最小例子

下面用一个最小例子把整套流程跑通。需求是"做一个 CLI 工具，能把文本按行编号输出"。

💡 需求描述

在 Claude Code 对话框里输入：

帮我用 OpenSpec 写一个 CLI 工具，名字叫 linenumber，支持读取文件路径参数，把每一行加上行号后输出到标准输出。要求：空行也要编号；如果不传文件参数，从 stdin 读取。

📋 Step 1：发起提案

`1`	`/opsx:propose linenumber`

OpenSpec 会在 openspec/changes/linenumber/ 下生成四个文件。其中 tasks.md 大致长这样：

## 1. 工程初始化
- [ ] 1.1 初始化 Node.js 项目（package.json、bin 入口）
- [ ] 1.2 解析命令行参数（支持文件路径或 stdin）

## 2. 核心逻辑
- [ ] 2.1 实现 `numberLines(input: string): string`
- [ ] 2.2 处理 stdin / 文件两种输入源
- [ ] 2.3 空行也要带行号

## 3. 测试
- [ ] 3.1 单元测试：numberLines 在空字符串、普通文本、含空行文本下的输出
- [ ] 3.2 集成测试：从文件读入、从 stdin 读入

## 4. 文档
- [ ] 4.1 写 README，给出 `linenumber file.txt` 和 `cat file.txt | linenumber` 两个示例

specs/cli/linenumber/spec.md 会长这样（节选）：

# Capability: linenumber

## ADDED Requirements

### Requirement: 给文本按行编号
系统 SHALL 读取输入文本（来自文件参数或 stdin），对每一行加上"行号 + 跳格 + 内容"格式的前缀，并把结果输出到 stdout。

#### Scenario: 来自文件的普通文本
- WHEN 用户执行 `linenumber sample.txt`，且 `sample.txt` 包含 3 行文本
- THEN stdout 输出形如 `1\t第一行\n2\t第二行\n3\t第三行`

#### Scenario: 空行也要带行号
- WHEN 输入包含空行
- THEN 空行也以行号占位（不跳过）

关键动作：在这个阶段，仔细 review 每一个 Scenario。如果验收条件不严密，AI 在 apply 阶段就会跑偏。

🔧 Step 2：执行实现

`1`	`/opsx:apply`

AI 会按 tasks.md 逐项推进，每完成一项就勾掉一项。期间你也可以随时打断，要求它重写或调整。

如果你有 TDD 习惯，可以叠加 Superpowers 的 test-driven-development 技能：

`1`	`/superpowers:test-driven-development`

它会强制 AI 走"红-绿-重构"循环，先写失败测试，再写最小实现。

🗃️ Step 3：归档变更

实现完成、测试通过后：

`1`	`/opsx:archive linenumber`

OpenSpec 会自动：

把 changes/linenumber/specs/cli/linenumber/spec.md 中的 ADDED Requirements 合并到 openspec/specs/cli/linenumber/spec.md。
删除 openspec/changes/linenumber/ 目录。
留下一条归档记录，方便日后回溯。

此时 openspec/specs/ 就成了这个 CLI 工具的活文档——任何人 onboarding 都可以直接读 spec.md 了解这个工具的全部行为。

📚 命令速查表

命令	阶段	作用	是否动代码
`openspec init`	初始化	初始化 OpenSpec，写入 AI 工具命令	✗
`openspec config profile`	配置	查看/切换工作模式	✗
`openspec update`	配置	让 AI 重新识别命令	✗
`/opsx:explore`	设计前	与 AI 梳理思路，不产生产物	✗
`/opsx:propose <name>`	设计	生成 proposal / design / specs / tasks	✗
`/opsx:apply`	实施	按 tasks.md 逐项实现	✓
`/opsx:archive <name>`	归档	合并 delta 到 specs/，删除变更目录	✗
`/opsx:bulk-archive`	归档	一次性归档多个已完成变更	✗
`/opsx:onboard`	学习	把现有代码反向生成 specs/ 草稿	✗
`/opsx:ff`	实施	Fast Forward，跳过部分审批	✓
`/opsx:verify`	验证	让 AI 自检当前实现是否符合 spec	✗

表中 openspec 前缀的是 CLI 命令（在终端跑），/opsx: 前缀的是 Skill 命令（在 AI 对话框里跑）。别把它们搞混。

⚠️ 适用场景与局限

✅ 适合用 OpenSpec 的场景

长期维护的项目：规范合并到 specs/ 后就是活文档，新成员 onboarding 直接读 spec 即可。
需要审计的变更：每次新功能都有完整的 proposal.md + specs/ + tasks.md 留痕。
多 Agent 协作：把 OpenSpec 仓库和任务交给多个 AI 工具，它们读同一份 specs/，行为是一致的。
跨会话延续：规范是文件系统级的，新开会话也能立刻接上——不依赖对话历史。

❌ 不适合用 OpenSpec 的场景

小修小补：改文案、修样式、hot fix 走完整流程反而拖慢节奏（参考 [Spec Coding 的踩坑实录](../Spec Coding的踩坑实录/index.zh-cn.md)）。
探索性 PoC：需求还没定型，频繁改 spec 成本太高。
只有一两人的小项目：维护 spec 的边际收益可能不够抵消写作成本。
强实时性的项目：spec 写完到代码合入有延迟，不适合需要快速响应的场景。

💎 几条经验

propose 的输入质量决定产物质量：需求描述越具体，生成的 spec 越准；模糊的输入会产生模糊的 spec。
apply 之前一定要 review spec：设计阶段返工成本低，实现阶段返工成本高 10 倍。
archive 之前一定要 verify：跑测试、对照 spec 逐条勾选验收条件，别让"看起来对"变成"实际对"。
保持 spec 文件的精简：每个 Scenario 描述一个具体行为，不要把 spec 写成"伪代码"。
配合 TDD 纪律使用：OpenSpec 管"做什么"，TDD 管"做得对不对"，两者缺一不可。

📖 参考资料

OpenSpec 官方仓库：https://github.com/Fission-AI/OpenSpec
OpenSpec 官网：https://openspec.dev/
GitHub Spec Kit：https://github.com/github/spec-kit
AWS Kiro：https://kiro.dev/
Fission-AI 组织：https://github.com/Fission-AI

Spec Coding的踩坑实录

Sat, 27 Jun 2026 20:45:00 +0800

🛠️ 目前的落地方式

SDD（Spec-Driven Development）可以先简单理解成：先写一份“规格说明书”，再让 AI 按照说明书写代码。类比盖房子，就是先画图纸，再让施工队施工。

目前采用的是 OpenSpec + Superpowers 的融合方案。OpenSpec 负责定义“做什么”（What），产出 proposal、spec、design 等结构化文档；Superpowers 负责“怎么做”（How），用 Skills 推着 AI 走 brainstorming、writing-plans、TDD、code review 这条执行链路。

一开始想得很理想：OpenSpec 像图纸，Superpowers 像施工队，各管一段。但真正跑起来以后，我们发现两套工具不是简单拼起来就能协作，很多地方反而互相抢活。最明显的冲突有三个：

Superpowers 的 brainstorming 也会产出 design doc，和 OpenSpec 的 design 职责重叠。
OpenSpec 里的验收标准，后面又会被 Superpowers 的 TDD plan 转成 test case，原来的 spec 反而不再是主要验证手段。
两层审批互不信任，开发者经常不知道到底该以哪一层为准。

⚖️ 不是所有需求都需要 Spec Coding，有的时候 Plan Mode 就足够

业界常说 Spec Coding 有三条铁律：No Spec, No Code；Spec is Truth；Reverse Sync。听起来很合理，实践里却很容易变成误区。

No Spec, No Code。如果需求本身是“一个人半天能搞定”的小任务，写 spec 的时间可能已经超过直接改代码的时间。这时候坚持 no spec no code，最后就变成了为了流程而流程。
Spec is Truth。Spec 是自然语言写的，AI 再按自己的理解生成代码。中间至少经历两次翻译：人把意图翻译成 spec，AI 把 spec 翻译成 code。每一层都会丢信息。

真正能代表系统状态的，不是 spec，而是跑得通、测得过、能在线上工作的代码。

📉 损耗发生在哪里

第一层损耗：意图 → spec。很多隐性知识很难完整写出来。比如你觉得“余额不能为负”显而易见，但如果没有写进约束里，AI 未必会自动补上。
第二层损耗：spec → code。AI 对同一段 spec 的理解并不完全稳定。通常能遵循 70%—90%，但复杂需求里，总会有一部分需要人工改。
两层叠加后，差距会被放大。如果每层损失 20% 信息，最终保真度大概是 0.8 × 0.8 ≈ 64%。这和我们在复杂需求里的体感很接近：生成代码经常需要改 30%—40%。

相比之下，Plan Mode 是“意图 → 代码”一步到位。人在交互过程中可以随时补充遗漏细节，用即时反馈替代静态文档。对简单任务来说，这种方式的对齐度反而更高。

因此建议做出以下调整

Spec 不追求绝对精确。写得越像代码，成本越接近代码本身。
Spec 更适合作为“验收基准”，不是“生成蓝图”。它应该回答怎么判断对不对，而不是要求 AI 一比一照抄。
简单任务优先 Plan Mode，不是偷懒，而是减少中间损耗。
Code 才是最终事实依据。Spec 更像脚手架，帮 AI 生成第一版，后续真正被维护的是代码和测试。
过时的 spec 不只是没用，还可能误导 Agent。留在仓库里的错误前提，会变成下一次生成代码时的噪音。

⚠️ 业界主流 Spec 框架不一定适配模型能力

这个坑来自时间错配：工具的默认流程，往往跟不上模型能力的变化。Superpowers、Spec Kit、Kiro 等 SDD 工具，大多是在 2024—2025 年形成的。那时模型还没现在强，确实需要更细的 spec 才能生成可用代码。到了 2026 年，强模型在很多单模块任务里，已经能根据很短的意图描述生成 80% 以上可用代码。

问题是，很多工具的默认流程还停留在旧假设里：先写大段 spec，再写 design，再写 tasks，再审批，再执行。模型变强后，这套流程的边际收益变低，但写作、阅读、审批、维护成本仍然存在。

OpenAI Codex 团队（Harness Engineering，2026.02）。他们更强调四象限轻量 prompt：Goal、Context、Constraints、Done-When，再配合 AGENTS.md 约束项目边界。架构一致性靠 linter、structural test 和 CI 守住，而不是靠人反复 review spec。
Anthropic Claude Code 团队。CLAUDE.md 控制在较短篇幅，每个需求主要写验收标准和关键约束，而不是把完整实现方案写成蓝图。

一个趋势很明显：模型越强，spec 越薄。真正需要补足的不是流程控制，而是上下文、边界和验证。

换句话说，更应该追求 More Context, Less Control。Context 是信息，能帮助模型做判断；Control 是流程约束，过多时会变成负担。

📚 不是只有独立的 Spec 文件才是 SDD

实践	是不是 Spec	为什么
OpenSpec 的 `spec.md`	是	显式描述 What 的结构化文件
Superpowers 的 `design doc`	是	描述 What + How 的设计边界
Plan Mode 的 prompt	是	“先调研、给方案、确认后再写代码"本身就是轻量 spec
`CLAUDE.md` / `AGENTS.md`	是	项目级约束，是持久化的 spec
验收测试	是	可执行的 spec，也是最强的约束形式
一句话口头意图	边界形态	很轻，但仍然在约束实现空间。

经常有人说：“Plan Mode 不算 SDD，因为它没有写 spec 文件。”也有人说：“Superpowers 才是正统 SDD，因为它有 design doc。”这些说法背后有一个默认前提：只有独立的 spec 文件，才算 Spec-Driven。

实际上Spec 是一个光谱，不是某一种固定格式。从一句口头意图，到 AGENTS.md，再到验收测试，都是不同浓度的 spec。重新定义 SDD 的成功标准，也许更合理：不是“有没有写 spec 文件”，而是“AI 是否在正确的约束空间内工作”。例如

Plan Mode 不是没有 spec，而是 spec 和执行发生在同一条交互链里。
AGENTS.md 不是普通配置文件，它记录的是项目级行为边界。
TDD 的测试不只是测试，它也是最严格、最可执行的 spec。

🎯 不需要 100% 走 Spec 流程

最开始，默认所有需求都走 Superpowers 完整流程。结果连改一行文案，也要先brainstorming，再生成 design doc，再 review，再写 plan，再 TDD，再执行，再code review。

对于“一个人半天能搞定”的小需求。它们走完整流程时，brainstorming + design 的时间约等于编码时间的 60%—80%，端到端反而更慢，也就是说，超过一半需求被套上了过重流程。

更合理的分流方式应该是

档位	示例	更适合的方式
零 spec	改文案、修样式、hot fix	直接改代码
轻 spec	加筛选项、改接口参数	Plan Mode + 一句话意图
中 spec	新增业务模块、跨人协作	验收标准 + 关键约束
重 spec	架构重构、新系统设计	OpenSpec + Superpowers 全流程

Spec Coding 的实践指南

Sat, 27 Jun 2026 20:30:00 +0800

🏗️ 让 AI 基础建设

🗂️ 项目背景和环境准备

📖 项目背景

本文假设你已经有一个需求，需要使用 Spec Coding 来实现。这个系统引入AI coding的目标很直接:让AI熟知所有规则和业务背景，独立完成从需求分析到代码实现的全流程，人只做设计审核和最终决策。但由于这个系统历史悠久，存在许多历史包袱，并且各个模块开发时间不同，人工编写的代码又缺乏强力的规范，又没有文档传承。人为理解已经是困难至极。现在最大的难点更在于:如何让AI理解这个系统的复杂业务逻辑，以及各种历史包袱代码。

⚙️ 环境准备

本文采用Claude Code作为Agent，Spec Coding 框架选择OpenSpec。同时通过SuperPowers遵循TDD原则，即先写测试，再写实现。

🧱 构建AI Coding的背景上下文

在让 AI 接手开发之前，需要完成三项基础建设。这三项工作非常重要，直接影响AI生成的代码质量和准确性。三项工作都可以让 AI 来做初版，然后人工修正，再反过来用修正结果改进代码。

📄 生成项目级CLAUDE.md的初稿

使用/init命令生成项目级的CLAUDE.md文件。执行上述命令 Claude Code 会阅读项目源码，输出它理解到的架构约定和模式。这一步通常只能覆盖一部分规则，比如模块结构、包命名、错误处理方式等从代码里就能读出来。

🧠 人工补充隐形业务规则

AI 生成的 CLAUDE.md 初始稿通常只能覆盖一部分业务规则，比如模块结构、包命名、错误处理方式等从代码里就能读出来。人工补充这些规则，是确保 AI 能够正确理解业务逻辑的关键。这些规则需要人工根据业务背景，拆分到规则文件中。

├── CLAUDE.md                    # 主入口，指向各规则文件
└── rules/
    ├── code-style.md            # 命名、日志格式、错误处理
    ├── pipeline-architecture.md # 并发管道约束、统计规范、反模式禁止
    ├── commands.md              # 子命令基线、共享参数约束、日期默认值规则
    └── database-access.md       # 数据库访问规范

规则内容必须足够的具体，可映射到真实代码路径，避免写成"要注意性能"这种模凌两可的描述，AI无法执行这种口号。

最后还要告诉AI要保持维护所有Rules，比如我会在CLAUDE.md中增加以下指令：

1
2

- 更新对应模块代码时同步更新对应的规则文件。
- 更新各个模块代码时，必须同步更新对应的文档目录下的文档，以及集成测试目录下的测试用例。

🔍 让AI反向Review历史代码

规则完善后，就可以让 Claude Code 用这套规则扫描所有存量代码，找出不符合规则的地方。此时只需要告诉claude code修复这些问题，它就会触发superpowers的skill自行修复

💡 让AI理解设计理念和业务逻辑

规则约束的是"怎么写代码"，但 AI 还需要理解"为什么这样设计"，才能在新需求时做出正确的架构决策。

📚 让AI根据代码生成初版设计文档

让 Claude Code 阅读模块的所有代码实现，生成三份文档：

design.md: 代码架构设计文档，描述当前代码实现下的数据流、预处理规则、退款处理、消费摊销、汇总口径与校验规则，不展开命令行操作说明。
readme.md: 模块使用说明文档，只描述如何使用此模块的可执行命令，各个功能和参数说明，不涉及业务逻辑。
user-guide.md: 业务指南文档，用于描述纯粹的业务逻辑，不展开代码细节。在系统中每个模块都编写对应的三份文档，确保 AI 能够正确理解业务逻辑。

1
2
3

├── design.md
├── readme.md
├── user-guide.md

🛠️ 人工审核和修正设计文档

代码里体现不出来的业务背景需要手动补充

🔁 让AI根据设计文档再次Review代码

文档补充完整后，让 AI 对照文档检查代码实现，找出"文档说是这样，代码不是这样"的地方。

🧪 补充单元测试和集成测试

📋 让AI 根据代码和文档生成初版单元测试/集成测试

直接对claude code下达指令：参考提示词如下：

根据当前模块的文档和代码，生成单元测试，要求代码覆盖率必须至少达到80%。单元测试中如果遇到需要依赖第三方接口服务或者数据库的情况，统一用mock代替。

集成测试要分开生成：

根据当前模块的文档和代码，生成集成测试用例。尽可能覆盖更多的测试场景，设想更多的业务场景。允许你使用xxx数据库地址作为测试库，生成所需的测试数据。所有的测试场景和用例都要落实到文档中记录。

✏️ 人工补充测试场景

AI 首次生成的测试用例通常不够完备，同样需要人工review和补充测试用例。但你不需要手动去改代码，你只需要直接告诉claude code补充哪些场景的测试，或者修改测试文档即可。

🎯 AI 用测试反向 review 代码

测试跑起来之后，让 AI 分析覆盖率，找出测试暴露的逻辑分支问题，修复后再回归。关键前提：先有充分的设计文档和规则，AI 才能生成高质量测试——知道"这个字段应该是什么值"，而不是只生成结构正确但断言空洞的空壳测试。

🚀 AI Coding实践

完成了规则、文档、测试这三块基础建设，AI大模型基本上已经完全熟悉整个项目了。接下来就可以让 AI 真正接管开发流程了。开发过程中我们主要使用openspec的指令作为入口即可，superpowers的skills集合是在各个阶段自动触发的，无需手动调用。

📝 使用OpenSpec提案

命令： /opsx:propose
关键技巧：/opsx:propose 的输入质量直接决定生成工件的质量。模糊输入和具体输入的差距很大：一定要注意需求描述要足够具体，openspec 就能一次生成完整的文档，否则可能需要多次来回的沟通调整。

🧐 人工审核提案

在上一步产生的文档经过人工审核通过之后，接下来就是实施阶段。在执行 /opsx:apply 之前，必须认真审读 design.md和各个spec.md文档，给claude code提出反馈。这一步非常关键：设计阶段发现的问题，改起来通常只需要更新文档。但如果实现到一半才发现设计有缺陷，代价高出一个数量级。

🌿 创建worktree，执行 apply

在启动 Claude Code 时通过 –worktree 创建隔离工作区，或使用 superpowers:using-git-worktrees skill：参考提示词

# 方式一：启动时创建 worktree
claude --worktree

# 方式二：在 Claude Code 中使用 skill
# /superpowers:using-git-worktrees

工作区隔离后，使用类似以下Prompt执行

`1`	开始实施，整体流程使用`openspec-apply-change` skill，写代码时使用`subagent-driven-development`这个skill

此举触发superpowers的相关skills，开始执行任务。比如 subagent-driven-development 会创建多个子agent开始并行执行不同任务。

🤖 subagent-driven-development 的工作机制

对每个任务，superpowers skill 会依次循环三层：

Implementer subagent（内嵌 TDD）:每个任务派遣一个独立的 Implementer subagent，它内部强制执行红绿重构循环：

Step 1: 写一个失败的测试（RED）
Step 2: 运行测试，确认失败（必须看到失败，不能跳过）
Step 3: 写最小实现代码（GREEN）
Step 4: 运行测试，确认通过
Step 5: 重构，保持绿色
Step 6: 提交，报告状态（DONE / NEEDS_CONTEXT / BLOCKED）

Spec Reviewer subagent: Implementer 完成后，派遣 Spec Reviewer 独立读代码，逐行对比 spec 和实现，验证"构建了被要求的（不多不少）"。这个 reviewer 不信任 Implementer 的声明，自己读代码验证。
Code Quality Reviewer subagent: Spec 审核通过后，派遣 Code Quality Reviewer，验证是否"构建足够得好"：
- 文件职责清晰，可以独立理解
- 测试测的是真实代码而非 mock
- 没有创建不必要的巨型文件

任一审核不通过 → Implementer 修复 → 重新审核，直到两层都通过。

✅ 完成验证

所有任务完成后，superpowers的verification-before-completion skill 会开始介入，要求：运行完整测试套件，贴出实际输出，才能做"完成"声明。

📦 归档

命令:/opsx:archive 完成代码验收之后将 openspec 文档（proposal design specs / tasks）提交到 master 分支，形成可回溯的变更记录。

🔄 完整协作流程

蓝色节点是 openspec 指令，绿色节点是 superpowers skill 自动触发点。

Spec Coding 的定义

Sat, 27 Jun 2026 20:00:00 +0800

🧠 写在前面：AI 编程缺的不是模型，是图纸

2024 年到 2026 年这两年，我用 Claude Code、Cursor、Copilot 写过的代码比过去十年加起来都多。但越用越清楚地意识到一件事：

AI 不缺写代码的能力，缺的是一张’图纸’。

Vibe Coding 的爽感我们都体会过——敲一句"做个登录页"，五秒钟出 HTML。Demo 截图发到群里人人点赞。但只要把这段代码接进真实项目，问题就接踵而至：

上下文漂移：改了一个文件，三处不相关的代码跟着坏。
需求漂移：你说"登录支持手机号"，AI 默认走了 OAuth 流程。
知识孤岛：昨天为什么这么设计，没人记得——AI 不记得，你自己也不记得。
质量不稳：同样的需求，时好时坏，全看模型心情。
协作断点：同事接手时只能对着代码反推意图，最后的结论往往是"别动这段"。

这些痛点指向同一个结论：AI 编程的下一个瓶颈不是模型能力，而是"人机协作的工程方法论"。

GitHub 在 2025 年正式把这套方法论命名为 Spec-Driven Development（SDD），社区里更口语化的叫法是 Spec Coding——用规格驱动编码。

这篇文章是我对 Spec Coding 的一份系统化实践笔记，重点不在某一个具体工具，而在它作为一种开发范式，到底解决了什么、要怎么落地、有什么坑。

⚖️ 什么是 Spec Coding

📖 定义与定位

Spec Coding（或 SDD, Spec-Driven Development）是一种把"可执行的规格"置于软件开发生命周期中心的工程实践。它借鉴了传统软件工程中"契约优先"（Contract-First）的思想，但做了关键升级：

规格不再是静态文档，而是与代码一同演进、版本化、可被 AI 直接消费的活工件。
代码不再是 Source of Truth，而是规格的"最后一公里输出"。
AI 不是替代者，而是被规格约束的"高级实现者"。

一句话概括：

过去是先写代码再补文档；现在反过来——先写规格，代码只是规格的编译产物。

🔍 Spec Coding vs Vibe Coding

维度	Vibe Coding	Spec Coding
核心信念	“AI 心领神会”	“规格是契约”
输入形态	自然语言提示	结构化规格文档
上下文管理	靠对话历史	靠版本化的文件
决策可追溯	不可追溯	每个决策都有据可查
变更成本	改一处牵全身	改规格 → 重新生成
适合场景	Demo、探索、PoC	真实项目、长期维护、协作
典型代表	Cursor 自由对话	Spec Kit / Kiro / OpenSpec

它们不是对立关系，是不同阶段的工具：

想快速验证一个想法 → Vibe Coding 更轻。
想把想法变成可交付、可维护的产品 → Spec Coding 更稳。

社区里越来越多人把 Spec Coding 视为 Vibe Coding 的"工业化升级版"。

🔄 核心工作流：Specify → Plan → Tasks → Implement

主流 SDD 框架（GitHub Spec Kit、AWS Kiro、OpenSpec）虽然在命令名上略有差异，但底层都收敛到了同一个四阶段工作流：

1
2

Specify  →  Plan  →  Tasks  →  Implement
（定目标）  （定方案）  （拆任务）  （按规格实现）

每一个阶段都遵循**人在环路（Human-in-the-Loop）**原则：必须由人审阅、批准，才进入下一阶段。

🛠️ 阶段一：Specify（定目标）

回答的问题：我们要解决什么问题？给谁用？成功的标准是什么？

这一阶段不涉及任何技术选型，只关注：

用户故事（User Story）
业务目标（Goal）
验收标准（Acceptance Criteria）
边界条件与异常场景

输出通常是一份 spec.md，语言要"无歧义、可测试"。AWS Kiro 在这一步使用 EARS（Easy Approach to Requirements Syntax）格式，能让 AI 自动生成覆盖边角情况的验收条件。

## Feature: 用户注册

### US-1 注册新账号
- WHEN 用户提交合法的邮箱与密码
- THEN 系统创建账号并发送验证邮件
- AND 5 秒内返回 201

### 边界情况
- WHEN 邮箱已被注册
- THEN 返回 409 Conflict
- AND 提示"该邮箱已注册"

🧩 阶段二：Plan（定方案）

回答的问题：在已知的约束下，怎么实现？

这一阶段把"业务目标"翻译成"技术决策"：

技术栈（语言、框架、数据库）
架构风格（单体 / 微服务 / Serverless）
关键依赖（第三方服务、合规要求）
性能与安全目标
风险点与备选方案

输出通常是 plan.md，可以并列多个方案让 AI 比较。比如：“用 Postgres 全文检索 vs. 用 ElasticSearch”——AI 会根据 Spec 给出权衡分析。

## 技术方案
- 框架：Go 1.22 + Gin
- 数据库：PostgreSQL 16
- 缓存：Redis
- 部署：Docker + Kubernetes
- 鉴权：JWT + Refresh Token
- 关键风险：邮件发送失败的重试策略

⚙️ 阶段三：Tasks（拆任务）

回答的问题：怎么把方案变成可执行、可验收的小步骤？

这一阶段不写代码，只生成任务清单。Spec Kit / Kiro 在这一步生成的 tasks.md 通常长这样：

- [ ] T001 创建数据库表 `users`（含唯一索引）
- [ ] T002 实现 `POST /api/v1/register` 路由
- [ ] T003 集成邮件服务（带重试）
- [ ] T004 写单元测试（密码强度校验）
- [ ] T005 写集成测试（注册 → 验证 → 登录）
- [ ] T006 在 staging 环境跑一遍 e2e

关键纪律：

每个任务 2~5 分钟可以完成
任务之间有清晰依赖
每个任务有明确"完成"的定义（DoD）
不写代码——代码是下一阶段的事

🚀 阶段四：Implement（按规格实现）

回答的问题：让 AI 在规格约束下，把任务逐个变成代码。

这一阶段 AI 才真正开始写代码，但它会严格对照前面的 Spec/Plan/Tasks。如果发现实现与规格冲突，应该回头改规格，而不是偷偷改逻辑。

一个常见的纪律：任何偏离 Spec 的实现，都必须先回退到 Spec 修改并重新走批准流程。

实践上还可以叠加 TDD、子代理并行、Code Review 等纪律——这部分可以参考 Superpowers 与 OpenSpec 的配合使用一文。

🧪 实践示例：做一个 CLI Todo 应用

把上面四阶段跑一遍。需求是"做一个命令行 Todo 工具，支持增删改查与本地持久化"。

💡 Step 1：明确业务目标

先用一句话把目标写清楚：

给我做一个 CLI 工具，名字叫 todo，支持添加、列出、完成、删除 Todo，数据存本地 JSON 文件。

然后让 AI 协助扩成结构化的 spec.md：

## 功能需求

### US-1 添加 Todo
- WHEN 用户运行 `todo add "买牛奶"`
- THEN 在 todos.json 中追加一条 `{id, content, done=false, created_at}`
- AND 输出 "已添加 #1: 买牛奶"

### US-2 列出 Todo
- WHEN 用户运行 `todo list`
- THEN 按 id 升序列出所有未完成 Todo
- AND 每行格式 `[#id] [ ] content`

### US-3 标记完成
- WHEN 用户运行 `todo done 1`
- THEN 把 id=1 的 Todo 标记为 done
- AND 输出 "已完成 #1: 买牛奶"

### 边界情况
- 当 todos.json 不存在时，自动创建
- 当 id 不存在时，提示 "未找到该 Todo"
- 当 JSON 损坏时，备份原文件并重新创建

🔹 Step 2：编写规格

plan.md（技术方案）：

- 语言：Go 1.22
- 第三方依赖：仅 `spf13/cobra`
- 存储：本地 JSON 文件，路径 `~/.todo/todos.json`
- 并发：单进程，不需要锁
- 测试：表格驱动 + golden file

📐 Step 3：拆解任务

tasks.md（任务清单）：

- [ ] T001 初始化 Go module 与 cobra 骨架
- [ ] T002 实现 `add` 子命令
- [ ] T003 实现 `list` 子命令
- [ ] T004 实现 `done` 子命令
- [ ] T005 实现 `del` 子命令
- [ ] T006 实现 storage 层（load/save/append）
- [ ] T007 写单测覆盖所有命令
- [ ] T008 跑 go vet / go test / go build

✅ Step 4：交付与验证

把四份文档喂给 Claude Code，让它按 tasks.md 逐项实现，每个任务完成后自动跑测试：

1
2

# 提示词示例（使用 Claude Code + Spec Kit）
$spec-kit implement

AI 写完一个任务，会自检：

是不是严格按 spec.md 实现？
单测是否覆盖了所有验收条件？
是否触犯了 plan.md 中的"约束清单"？

如果发现规格本身漏了边界情况（比如"删除已完成的 Todo 要二次确认"），就回头改 Spec，让规格成为唯一真相。

最终交付物：

4 份 Markdown 文档（spec / plan / tasks / constitution）
一个可用的二进制 todo
一份与 Spec 一一对应的测试报告

💻 工具链速览

SDD 在 2025-2026 年迎来了一波工具爆发。这里按定位简单梳理：

🎯 GitHub Spec Kit

当前最主流的开源 SDD 框架。Python CLI 工具，原生支持 GitHub Copilot，兼容 Claude Code、Gemini CLI、Amazon Q 等 30+ AI 编码代理。

四阶段流程：Specify → Plan → Tasks → Implement。

最独特的设计是 Constitution（宪法）——一份放在项目根目录的长效文档，定义架构原则、编码规范、安全要求。AI 每次开发都必须遵守。

1
2
3

# 初始化
uv tool install spec-kit
specify init my-project

适合：想入门 SDD 的团队，已有 IDE 体系，不想切换工具链。

🤝 AWS Kiro

最"原生"的规格驱动 AI IDE。基于 Code OSS（VS Code 同源）构建，但要求开发者先正式定义需求，再进入开发。

三阶段流程：Requirements → Design → Tasks，每阶段用 EARS 格式描述，自动生成用户故事、验收条件、边界场景。

独有 Agent Hooks——事件驱动的自动化系统，保存文件后自动跑测试、刷新 README、执行安全扫描。

适合：企业级团队，需要正式 SDD 流程，多人协作的复杂项目。

🏗️ BMAD-METHOD

最"团队化"的多 Agent 开发框架。MIT 开源，内部编排 12+ AI 角色（产品经理、架构师、UX、Developer、QA、Scrum Master），Agent 之间通过文件"交接棒"完成交付。

`1`	`需求 → 设计 → 开发 → 测试 → 交付`

适合：大型团队，多角色协作，需要严格流程的组织。

📚 其他值得关注的工具

工具	定位	一句话总结
OpenSpec	变更管理专家	提案式流程，`ADDED/MODIFIED/REMOVED` 增量标记
Augment Code	大规模代码上下文	Context Engine 维护 40 万+ 文件级架构理解
TaskFlow	任务编排	把 Spec 拆成 DAG，让多个 AI Worker 并行执行
Claude Code Spec Mode	轻量级 Spec	内置于 Claude Code，适合个人开发者

工具只是手段，不是目的。先想清楚你的 Spec 应该长什么样，再选工具。

⚠️ 常见陷阱与最佳实践

Spec Coding 不是银弹。方法论选错了，文档反而比代码更难维护。

❌ 陷阱一：把 Spec 写成"伪代码"

最常见的失败模式是——Spec 写得太细，直接写 SQL、建表语句、函数签名。

# 错误示例
function register(email, password) {
  const hash = bcrypt(password, 10);
  return db.query(`INSERT INTO users ...`, [email, hash]);
}

为什么有问题：

Spec 变成了"另一种代码"，AI 写代码时直接照抄，失去意义。
改业务逻辑要改两份（Spec + 实现），维护成本反而更高。
评审 Spec 等于评审代码，门槛变高，参与人变少。

正确做法：Spec 关注意图与验收条件，不关注实现细节。

# 正确示例
WHEN 用户提交合法邮箱与密码
THEN 系统创建账号并发送验证邮件
AND 5 秒内返回 201

🔁 陷阱二：跳过 Plan 直接写代码

很多人写完 Spec 就急着让 AI 写代码，跳过 Plan 阶段。结果：AI 自由发挥，技术栈与项目现状脱节。

正确做法：Plan 阶段是"防 AI 跑偏"的最后一道闸。再小的项目，也要回答三个问题：

技术栈是什么？
有没有不能用的依赖？
性能/安全底线是什么？

💎 最佳实践总结

最后是几条在真实项目里验证过的经验：

Spec 写在版本控制里：与代码同仓库，PR 时一起 Review。
Constitution 是项目宪法：定义"AI 永远不能违反的规则"，比如"不允许用 any"、“不允许直接 rm -rf"。
任务粒度 2~5 分钟：太大的任务 AI 容易跑偏；太小又失去意义。
规格变了，先 PR Spec：实现跟着 Spec 走，不要反过来。
Spec 也是产品文档：业务方、PM、QA 都能看懂同一份 Spec。
不要追求"完整 Spec”：80% 的清晰度已经能换来 80% 的可靠性，最后 20% 让实现阶段补。
Vibe Coding 与 Spec Coding 混用：探索阶段用 Vibe，确定方案后切到 Spec。

📝 总结

回到开头那句话：AI 编程缺的不是模型，是图纸。

Spec Coding 不是要取代 Vibe Coding，而是给"自由探索"配上一条"工业化产线"。当你有了：

一份清晰的 Spec（业务目标）
一份严谨的 Plan（技术方案）
一份可验证的 Tasks（任务清单）
一份长效的 Constitution（项目宪法）

AI 就不再是"凭感觉的代码打字机"，而是一个严格按图纸施工的工程师。

未来一两年，随着模型能力的进一步提升，瓶颈会更集中在 Spec 的质量上。会写 Spec 的开发者，会比会写代码的开发者更稀缺。

如果你还没试过，可以从一个小工具开始：

找一个本周要做的小功能
花 20 分钟写一份 Spec
让 Claude Code 按 Spec 实现
体会一下"几乎一次跑通"的感觉

你会发现，写 Spec 的过程本身，就是一次深度思考。

延伸阅读：

Superpowers 与 OpenSpec 的配合使用

[Claude Code 最佳实践](../Claude Code最佳实践/index.zh-cn.md)

GitHub Spec Kit 官方仓库

AWS Kiro 官方介绍

EARS 需求描述规范