AI 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 需求描述规范

Claude Code 最佳实践

Sat, 27 Jun 2026 17:18:00 +0800

🧠 什么是 Claude Code

Claude Code 是 Anthropic 推出的终端优先（Terminal-First）的 AI 编程助手，它不是一个聊天框里的代码补全插件，而是一个直接运行在本地命令行、能够读取、编辑、执行真实项目代码的 Agent。

与传统的 IDE 插件式 Copilot 不同，Claude Code 把模型放进了你熟悉的开发环境里——Shell、文件树、Git、测试、构建脚本——让模型拥有和开发者一样的“动手能力”。

📖 核心理念

Agent 而非补全：模型不只生成代码片段，而是会主动规划、调用工具、执行命令、回看结果。
终端即界面：所有交互都发生在命令行中，没有额外的 IDE 锁定，跨编辑器、跨语言、跨项目通用。
上下文即工程：通过 CLAUDE.md、Subagents、Skills、MCP 等机制，把项目的“隐性知识”显性化喂给模型。

⚖️ 与传统 AI 编程助手的区别

维度	传统 Copilot	Claude Code
交互形态	行内补全 / 聊天面板	终端会话 + 多轮规划
环境感知	当前打开的文件	整个仓库、Git 历史、CLI 工具链
执行能力	只能生成代码建议	可读、写、执行、回滚
记忆机制	无持久化	`CLAUDE.md` + 项目级上下文
扩展能力	插件市场	MCP 协议 + Subagents + Skills

简单说：传统 Copilot 帮你打字，Claude Code 帮你做事。

🛠️ 安装与配置

💻 安装方式

Claude Code 通过 npm 全局安装，安装前需要 Node.js 18+：

# 全局安装
npm install -g @anthropic-ai/claude-code

# 安装完成后启动
claude

启动后会引导你完成 OAuth 登录，登录成功后即可在当前目录下使用。

🎛️ 基础配置

Claude Code 的配置主要围绕三件事：

环境变量：API Key、模型选择、Token 限额等
全局偏好：默认行为、主题、快捷键
项目配置：放在项目根目录的 .claude/ 目录和 CLAUDE.md

# 初始化当前项目（生成 CLAUDE.md 和 .claude 配置目录）
claude init

# 查看当前配置
claude config list

# 修改某一项配置
claude config set model claude-opus-4

提示：如果是第一次接触 Claude Code，可以先在空目录里 claude init，熟悉一下它生成的目录结构和 CLAUDE.md 模板。

⌨️ 核心命令与快捷键

🔄 常用斜杠命令

Claude Code 内置了一组以 / 开头的命令，覆盖日常高频操作：

/init：在当前目录生成 CLAUDE.md 项目记忆文件
/compact：当上下文变长时压缩对话历史，节省 Token
/clear：清空当前会话上下文，开启新对话
/resume：恢复历史会话，继续之前的任务
/memory：打开 CLAUDE.md 进行编辑
/agents：管理 Subagents 配置
/mcp：管理 MCP 服务器连接
/review：让模型审查当前分支的代码改动
/security-review：执行安全审查
/cost：查看当前会话的 Token 消耗
/help：查看所有可用命令

💡 高效交互技巧

多行输入：使用 \ 续行，或者在引号内写多行；按两次回车提交
@ 引用文件：@src/main.go 可以让模型直接读取引用文件的内容
! 运行命令：!git status 让 Claude Code 执行 Shell 命令并把输出回灌到上下文
图片拖入：直接把截图拖进终端，模型可以“看到”报错截图或设计稿
Plan 模式：先让模型给出执行计划，确认后再让其实施，避免误改

1
2

# 示例：在 Plan 模式下让模型规划重构方案
claude --plan "重构用户模块的权限校验逻辑"

📁 CLAUDE.md 项目记忆

CLAUDE.md 是 Claude Code 的项目级记忆文件，相当于给模型的一份“新员工入职手册”。每次会话开始时，它的内容会自动注入到上下文。

🗂️ 分层记忆

记忆文件分三层：

根目录的 CLAUDE.md：项目级通用规则
子目录的 CLAUDE.md：模块级特殊约定（模型就近加载）
全局的 ~/.claude/CLAUDE.md：个人偏好（跨项目生效）

my-project/
├── CLAUDE.md              # 项目级
├── pkg/
│   └── CLAUDE.md          # 公共库约定
├── internal/
│   └── service/
│       └── CLAUDE.md      # 业务层特殊规范

🧩 记忆文件的最佳实践

💰 复利工程

几乎每个教程都会提到，CLAUDE.md ，但多数人把它写成了一篇又臭又长的说明文档，塞满了废话 Anthropic 内部团队分享过，他们认为 CLAUDE.md 最佳实践是：每次Claude犯了一个错误，都要记录在 CLAUDE.md 中。不是人工维护，而是模型自己记录。每次纠正错误，最后加一句

`1`	把这个教训更新到 `CLAUDE.md` 中，确保你以后不会再犯

Claude 写给自己看的建议，它自己最明白如果遵守。

🧹 定期更新瘦身

Claude.md要定期瘦身。写了三个月，其中可能有很多过时的规则，可以隔几周让Claude帮你review一篇，删除掉不再使用的规则。保持精简。这个文件每个会话都会加载，越短越好。

保持简洁：只写“必须知道”的东西，过长的 CLAUDE.md 会挤占 Token
分模块组织：用清晰的二级标题区分“构建命令”、“代码规范”、“禁止事项”
定期更新：项目演进时同步更新，否则模型会按过时规则办事
避免敏感信息：不要把密钥、Token、内部域名写进去

⚙️ Hook 的最佳实践

CLAUDE.md本质上只是建议，Claude大多数时候遵守，但是他不是强制的。Hooks是强制的。 hook真正的价值在于控制Claude的行为，这是传统工具无法做到的。

hooks最优价值的用法有以下几点

🎯 使用 SessionStart 动态加载 skill

Claude Code 的 skill 系统有一个字符预算，默认是上下文窗口的 2%（大约 16,000 字符）。所有 skill 的描述信息需要塞进这个预算里，Claude 才知道有哪些 skill 可以用。当你装的 skill 越来越多，超出预算的 skill 就会被静默丢弃——你以为装了，其实 Claude 根本看不见。跑 /context 可以看到被排除的 skill 有哪些。

解决方案:不要一股脑把所有 skill 都装上，用 SessionStart hook 根据当前项目的技术栈动态挂载。

这样你可以在 ~/.claude/skill-library/ 里攒几十个 skill，但每个项目启动时只挂载真正用得上的那几个。字符预算花在刀刃上，不会因为装了一堆 Python skill 把你 React 项目里急需的前端 skill 给挤掉了。

🌀 并行工作

先说一个反直觉的情况：Anthropic 内部团队分享过，他们认为Claude Code 最大的生产力提升来自同时开3-5个会话并行干活

具体操作是用git worktree。你可以直接在命令行输入

`1`	`claude --worktree`

它会自动帮你创建一个隔离的工作目录，在里面开一个全新的会话。加上–tmux参数，会自动在tmux中打开一个新的窗口。

举一个实际场景:你同时要改一个API的逻辑，修复一个前端bug，写一个单元测试。以前只能排队干，现在使用三个worktree并行工作。每个里面都有一个Claude在干活

✅ 验证能力

Anthropic 官方 power user tips 里面，加粗标注了一句话：如果你只学一个技巧，请学这个——给 Claude 一种验证自己输出的方式。道理很简单：如果 Claude 能自己跑测试、自己检查结果，它就能自己迭代到正确为止。你只需要把验证手段告诉它。

做后端？让它跑完代码之后自动跑测试。做前端？装 Chrome 扩展。这个扩展的价值被严重低估了——想想看，你让一个工程师写网页但不给他浏览器用，能写出好东西吗？装了扩展之后，Claude 能看到页面长什么样，能自己迭代到视觉效果满意为止。

Desktop 版本内置了一个浏览器，能自动启动和测试 Web 服务器。如果你在 CLI 或 VS Code 里工作，用 Chrome 扩展也能达到类似效果。

还有个 /simplify 命令，在改完代码之后跑一下，它会启动多个并行 agent，从代码复用、质量、效率、规范合规几个维度同时审查你刚改的代码。一个命令完成一轮 code review。

更高阶的验证方式：让 Claude 自己质疑自己。做完研究或分析之后，告诉它：

🤖 Subagents 分工协作

当一个任务涉及多个领域（前端 + 后端 + 数据库 + 测试）时，可以让 Claude Code 启动多个 Subagent 并行处理：Subagent 的本质是上下文隔离。主 agent 处理核心逻辑，子 agent 负责具体的子任务，做完把结果交回来。主 agent 的上下文窗口保持干净，不会被大量细节信息污染。

最直接的用法：在你的 prompt 后面加一句 “use subagents”，Claude 就会自动把任务拆分成多个子任务并行处理。

1
2
3

# 让模型自主决定是否拆 Subagent
claude "为这个新功能补全前后端实现、数据库迁移脚本和单测，
        可以拆成多个 subagent 并行执行"

你也可以精细控制。在 .claude/agents/ 目录下创建 .md 文件来定义专属 agent：每个 agent 可以配置独立的名称、颜色、可用工具、权限模式、甚至使用不同的模型。跑 /agents 就能看到管理界面。

一个实战场景：PR 提交后，自动触发一组 agent，分别检查逻辑错误、安全漏洞、性能回退，然后各自贴出 inline 评论。Anthropic 内部就是这么搞的——代码产出上去了，review 反而成了瓶颈，于是他们把 review 也自动化了。

还有一种玩法叫 worktree agent。在 agent 的 frontmatter 里加上 isolation: worktree：

然后跟 Claude 说：“把所有同步 IO 迁移到异步。分成 10 批，启动 10 个带 worktree 隔离的并行 agent。每个 agent 独立测试自己的修改，测试通过后自动提 PR。”

# .claude/agents/worktree-worker.md

---

name: worktree-worker
model: haiku
isolation: worktree

---

10 个 agent 同时在 10 个隔离目录里干活，互不干扰。大规模重构从噩梦变成了一杯咖啡的事。

🔌 MCP 与扩展能力

MCP（Model Context Protocol） 是 Claude Code 连接外部工具和数据源的标准协议。通过 MCP，模型可以读写数据库、查询 GitHub、调用内部 API、操作 Figma 等。

常见的高频 MCP 服务器：

文件系统：跨目录读取项目文档
GitHub：查看 PR、Issue、Code Review
PostgreSQL / MySQL：直接查询开发库
Figma：读取设计稿
Slack / Notion：读取团队知识库

# 添加一个 MCP 服务器
claude mcp add postgres "postgresql://user:pass@localhost:5432/mydb"

# 列出已配置的 MCP 服务器
claude mcp list

# 在对话中使用 MCP 工具
claude "查一下 users 表里最近 7 天注册量最高的 10 个城市"

安全提示：MCP 服务器拥有真实的数据访问权限，仅添加你信任的服务器，并在生产库中谨慎使用。

⚠️ 常见陷阱与最佳实践

陷阱	表现	建议
上下文过载	模型开始“失忆”，理解错需求	用 `/compact` 压缩，定期 `/clear` 开启新对话
指令过宽	模型改了不该改的文件	任务要具体，限定文件范围；先 Plan 再执行
盲目信任	模型生成了看起来对、实际有 bug 的代码	必须 review，跑测试；不要跳过这一步
忽视 Git	改动后无法回滚	重要操作前先 `git commit` 留个回滚点
MCP 误用	模型意外删了生产数据	MCP 服务器只连开发环境，生产操作走人工
忽略 CLAUDE.md	模型每次都“重新学”规范	团队约定写进 `CLAUDE.md`，让规则自动生效

三条黄金法则：

小步快跑：一次只让模型做一件事，做完 review 后再继续
先 Plan 后动手：复杂任务先让模型出方案，确认后再执行
Git 是安全网：任何重要改动前先 commit，模型搞砸了随时回滚

📝 总结

Claude Code 的核心价值，是把 AI 从“代码生成器”升级为“能独立完成任务的工程协作者”。要真正用好它，关键在于三件事：

清晰的项目记忆：写好 CLAUDE.md，把团队的隐性规则显性化
合适的任务边界：把大任务拆成可验收的小任务，先 Plan 再执行
工程化的安全网：Git、MCP 权限、Code Review，缺一不可

当你把 Claude Code 当作一个“需要规范、需要 review、需要边界”的同事来对待，而不是一个“无所不能的魔法”，它才能真正稳定地提升你的开发效率。

一句话总结：Claude Code 不会取代工程师，但会用 Claude Code 的工程师，会取代不会用的人。

参考资料：

Superpowers与OpenSpec的配合使用

Thu, 25 Jun 2026 23:33:15 +0800

🧠 写在前面：AI 编程为什么需要"两件套"

2024 年到 2026 年，AI 编程助手的能力突飞猛进——几百行代码随手就能写出来。但只要真正把 Claude Code、Cursor、Copilot 之类工具放进真实项目里，你大概率会撞上这几面墙：

需求漂移：你说"做个登录功能"，AI 心领神会地写出一整套 OAuth；你要的其实只是手机号 + 验证码。
缺乏流程：AI 不会主动问"为什么"，拿到需求就开干，写完也不知道它按什么逻辑写的。
质量不稳：今天生成的好，明天生成的差；改一个 Bug 引入三个新 Bug。
不可追溯：改了很多版，没人记得为什么改；后来人不敢动这段代码。

这些问题的本质是：AI 默认模式是"尽力完成当前指令"，而不是"遵循一套严谨的工程流程"。

社区给出的答案是两个相互补位的工具：

OpenSpec：管"做什么"——把需求变成可审查、可追溯的规范文档。
Superpowers：管"怎么做"——强制 AI 走完"需求分析 → 制定计划 → TDD → 代码审查 → 验证"的工程流程。

一个管契约，一个管纪律。这两件套组合起来，被不少开发者称为 AI 编程的"黄金搭档"。

🧩 OpenSpec：给 AI 立一份"需求契约"

1.1 它是什么

OpenSpec 是由 Fission-AI 开源的 Spec-Driven Development（SDD）框架 + CLI 工具，核心口号是 “Align before code”（先对齐规格，再写代码）。

它的形态很轻量：

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

支持 25+ AI 工具，包括 Claude Code、Cursor、Codex、GitHub Copilot、Windsurf、Gemini CLI、Cline、Trae 等。

1.2 核心设计：双文件夹模型

OpenSpec 在项目根目录的 openspec/ 下维护两套内容：

1
2
3

openspec/
├── specs/    # 系统当前生效的规范（Source of Truth，事实来源）
└── changes/  # 正在进行的变更提案（每个功能一个子目录）

每次新功能都在 changes/<name>/ 下开一个独立目录，里面包含：

文件	作用
`proposal.md`	为什么要做、改动范围
`design.md`	技术方案、关键决策
`specs/`	需求与场景的 delta（差异清单）
`tasks.md`	实施任务的 checkbox 清单

/opsx:archive 完成后，规范会自动合并到 specs/，作为活文档继续维护。

1.3 三步走的核心命令（Core 模式）

安装完默认进入 Core 模式，命令精简到三个：

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

/opsx:propose <name>：一键生成 proposal.md + design.md + specs/ + tasks.md
/opsx:apply：按 tasks.md 逐项实现
/opsx:archive：归档完成的变更

需求不清时还有 /opsx:explore 兜底——不产生产物，只梳理思路。

🛠️ Superpowers：给 AI 装一个"工程化大脑"

2.1 它是什么

Superpowers 是 GitHub 用户 obra 开源的一个 Claude Skill 框架 + 软件开发方法论。它由一组 Markdown 格式的 SKILL.md 文件组成，被 Claude Code / Codex / Cursor / Gemini CLI 等工具读取并执行。

它的设计哲学是：

不是让 AI 多会写代码，而是尽量让它少在错误的时机写代码。

2.2 八个核心技能（Skills）

Superpowers 把开发流程拆成 8 个可触发的技能，每个对应一个环节：

技能	触发时机	白话解释
`brainstorming`	写代码前	像产品经理一样追问，把模糊需求变清晰
`using-git-worktrees`	设计批准后	在新分支建隔离工作区
`writing-plans`	设计通过后	把大任务拆成 2~5 分钟的小步骤
`subagent-driven-development`	计划完成后	派多个子代理并行干活、互相审查
`test-driven-development`	实现过程中	强制红-绿-重构循环
`systematic-debugging`	调试阶段	4 步根因诊断法
`requesting-code-review`	任务之间	写完代码自动找人审查
`verification-before-completion`	收尾阶段	交活前全部跑一遍

这套技能的最大特点是 按上下文自动触发——你不需要手动敲命令，AI 看到合适的时机就会自己调用。

2.3 安装（以 Claude Code 为例）

# 注册市场
/plugin marketplace add obra/superpowers-marketplace

# 安装插件
/plugin install superpowers@superpowers-marketplace

装完后开一个新会话，说一句"帮我做一个登录功能"，Superpowers 就会自动激活 brainstorming 技能开始追问。

🔄 两者的协同关系：契约 + 纪律

把两个工具叠在一起看，它们的边界其实非常清楚：

维度	Superpowers	OpenSpec
定位	AI 的执行纪律（怎么做）	项目的规格说明书（做什么）
解决问题	防止跳过设计、保证编码质量	防止需求遗忘、保证规范可追溯
核心产物	对话决策、实施计划、代码	proposal.md、specs/、tasks.md
工作流	单任务高质量闭环	长期增量变更管理
状态持久	依赖对话历史	基于文件系统，跨会话持久
擅长场景	执行阶段	设计阶段

一句话总结：OpenSpec 让 AI 写代码前先签"合同"，锁定设计（做什么），Superpowers 让 AI 写代码时按"工艺"，保障执行（怎么做）。两者合起来，AI 才真正像个能交付的高级工程师，而不是"按行计费"的代码打字机。

单独 OpenSpec：有规范但执行可能跳步，缺少 TDD 纪律。
单独 Superpowers：有纪律但设计共识仅存于对话，无法持久化。

组合价值：OpenSpec 将设计固化为文件资产，Superpowers 在执行中强制 TDD、调试、审查等纪律。

方案一:superpowers-openspec-team-skills

superpowers-openspec-team-skills 是 github上的一个解决方案，用于管理 OpenSpec 和 Superpowers 项目的开发流程。官方仓库地址：superpowers-openspec-team-skills

具体使用

1）安装

`1`	`npm install -g superpowers-openspec-team`

2）项目初始化

`1`	`sot init /path/to/your/project`

3）工作流选择具体的工作流

superpowers-openspec-superpowers：先用 Superpowers 把问题想透，再用 OpenSpec 把事实锁准，最后回到 Superpowers 把实现、验证和归档做稳
openspec-superpowers：先完成 OpenSpec 变更产物，再交给 Superpowers 继续实现、验证和归档
superpowers-feature：只使用 Superpowers 的设计、计划、TDD、验证纪律(等价于单独使用superpowers)
superpowers-learning：不是主交付流程，而是其他 workflow 完成后的增强收尾层，用来更新项目记忆、沉淀经验，并让下一次会话可以直接接上当前成果
openspec-feature：先完成 OpenSpec proposal、design、specs、tasks，再进入实现(等价于单独使用Superpowers)

这些 workflow 只应在以下情况启用：

用户明确点名某个 workflow
用户明确要求按这种 workflow 风格执行
仓库策略明确要求使用该 workflow

它们不应该成为 AI 工具的默认后台流程。

示例：

`1`	`请使用 $superpowers-openspec-superpowers-workflow 处理这个功能。`

4）预计产物 1. docs/superpowers/specs/ 下的 Superpowers 设计草稿 2. openspec/changes// 下的 proposal、design、specs、tasks 3. docs/superpowers/plans/ 下的实现计划 4. 已验证的代码变更 5. 完成后的 OpenSpec change 归档

工作流

工作流的选取逻辑

想先用 Superpowers 做探索、再用 OpenSpec 锁定、最后回到 Superpowers 执行，用 superpowers-openspec-superpowers
想先从 OpenSpec 产物起步，再交给 Superpowers 继续交付，用 openspec-superpowers
只想要 Superpowers 工程纪律，不需要 OpenSpec change 产物，用 superpowers-feature
工作已经做完，想把这次经验、状态和可复用知识沉淀下来，并让下一次会话直接接上，用 superpowers-learning
只想先补齐 OpenSpec 变更文档，用 openspec-feature

其中 superpowers-learning 需要特别注意：它更像其他 workflow 的“增强收尾层”，不是一条替代开发流程的主入口。通常是在 superpowers-feature、superpowers-openspec-superpowers、openspec-superpowers 这类交付型 workflow 完成之后，再用它把本次会话里真正值得长期保留的内容写回 .superpowers-memory/，包括稳定项目事实、当前状态、简短会话记录，以及后续可沉淀成 skill、checklist 或知识库条目的经验。

对持续协作的项目，推荐这样串联：

先运行一个交付型 workflow
完成实现与验证
再运行 superpowers-learning，把这次工作的稳定事实、当前状态、会话记录和可复用经验写回项目记忆

openspec-superpowers 工作流

openspec-superpowers-workflow 是完整功能交付的总入口。它把 Superpowers 的探索、设计确认、实现计划、TDD、验证纪律，与 OpenSpec 的 proposal、design、spec、tasks 产物组合在一起。适合用于“既要想清楚、又要留下正式规范记录、最后还要可靠实现”的功能开发。

适用场景

用户明确要求使用 OpenSpec + Superpowers。
功能不是简单改动，需要澄清、方案、规范、任务、实现、测试和验证。
仓库或团队要求行为变更前先补齐 OpenSpec 产物。
希望用一个入口统一协调从想法到验证完成的完整流程。

工作流顺序

先用 Superpowers 探索上下文、澄清需求、比较方案，并确认设计方向。
再用 OpenSpec 创建或补齐 proposal.md、design.md、spec delta 和 tasks.md。
让用户确认生成出来的 OpenSpec tasks.md。
回到 Superpowers 编写实现计划，按 TDD 执行开发，并运行新的验证。
如果项目流程需要，再进入后续审查或归档步骤。

如果本次工作还需要沉淀项目记忆或可复用经验，可以在交付完成后继续使用 superpowers-learning-workflow。

示例提示词

`1`	`请使用 $openspec-superpowers-workflow 处理这个功能。在 OpenSpec 的 tasks 生成后，先展示给我，并等待我确认后再进入实现。`

superpowers-openspec-superpowers 工作流

superpowers-openspec-superpowers-workflow 适合那些不想靠猜、不想抢跑、也不想把复杂功能做着做着做乱掉的团队。

工作流顺序

先用 Superpowers 探索上下文、澄清需求、比较方案，并确认设计方向
再用 OpenSpec 生成 proposal.md、design.md、specs/…/spec.md、tasks.md
展示并确认生成出来的 tasks.md
tasks.md 确认后，先暂停并询问是否继续执行开发
回到 Superpowers，写实现计划，按 TDD 执行实现，并进行 fresh verification
开发与验证完成后，再暂停并询问是否继续代码审查
如果代码、测试和规格已经对齐，再归档 OpenSpec change

如果这次工作还产生了值得长期保留的经验，建议在归档后继续使用 superpowers-learning-workflow 更新项目记忆。

示例提示词

`1`	`请使用 $superpowers-openspec-superpowers-workflow 处理这个功能。在 OpenSpec 的 tasks 生成后，先展示给我，并等待我确认后再进入实现。`

superpowers-feature 工作流

superpowers-feature-workflow 覆盖 Superpowers 侧的功能交付流程：需求探索、设计确认、实现计划、worktree、TDD 和最终验证。

它不会创建 OpenSpec 产物。适合只需要严谨实现流程，但不需要正式 OpenSpec change 记录的场景。

openspec-feature 工作流

openspec-feature-workflow 用于创建并补齐实现前需要的 OpenSpec change 产物：proposal、design、specs 和 tasks。它专注于“把变更正式化”。它本身不负责 TDD、worktree 或实现后的验证流程。

superpowers-learning 工作流

superpowers-learning-workflow 是一个在重要工作结束后使用的反思型 workflow，用来把当前会话真正值得保留下来的内容沉淀到仓库里。适合接在这些 workflow 后面使用：

superpowers-feature-workflow
superpowers-openspec-superpowers-workflow
openspec-superpowers-workflow 它会帮助团队把最近的工作整理成四类内容：
稳定的项目事实
当前工作状态
简短的会话记录
未来可能沉淀成 workflow、skill 或 checklist 的可复用经验

🚀 标准 SOP：六阶段配合流程

下面给出一套经过社区验证的"六阶段标准操作流程"（SOP），把两个工具的指令串成一条完整的链路。

阶段 1：创建分支

`1`	`git checkout -b feature/user-registration`

保持 main 分支干净，所有变更在独立分支进行。

阶段 2：提案定义（OpenSpec 主导）

`1`	`/opsx:propose user-registration-with-verification`

AI 会在 openspec/changes/user-registration-with-verification/ 下生成完整文档结构：

openspec/changes/user-registration-with-verification/
├── proposal.md   ← 变更动机与范围
├── design.md     ← 技术方案
├── specs/        ← 需求与场景
└── tasks.md      ← 实施任务清单

人工必做：仔细 review proposal.md，确认需求方向正确后再继续。

阶段 3：深度设计（Superpowers 主导）

`1`	`/superpowers:brainstorming "用户注册功能的具体设计"`

Superpowers 不会直接动代码，而是启动苏格拉底式追问，把 OpenSpec proposal 里没写清楚的边界条件、异常分支、验收标准再问一通，并产出设计问答记录。

阶段 4：计划拆分（Superpowers 主导）

`1`	`/superpowers:writing-plans`

把设计拆成 2~5 分钟就能完成的小任务，每个任务写明：

精确的文件路径
完整的代码片段
验证步骤（如何知道这一步做对了）

输出物是一份给"热情但无判断力的初级工程师"也能照着做的计划文档。

阶段 5：TDD 执行（Superpowers + OpenSpec 共同主导）

1
2
3

/superpowers:subagent-driven-development
# 或
/opsx:apply

两种用法可选：

想用子代理并行：/superpowers:subagent-driven-development，Superpowers 会为每个任务派一个全新子代理，并通过两阶段审查（规范符合性 + 代码质量）。
想沿用 OpenSpec 节奏：/opsx:apply，AI 按 tasks.md 逐项打勾实现。

无论哪种，TDD 都不能跳过——先写测试，看着它失败；再写最小代码让它通过；再重构。Superpowers 的 test-driven-development 技能会强制执行这条纪律。

阶段 6：归档收尾

`1`	`/opsx:archive user-registration-with-verification`

实现完成后，OpenSpec 会把 changes/ 下的产物归档，并把规范 delta 合并到 openspec/specs/ 中。这步会留下完整的审计轨迹，方便后续人员回看"这个功能当时是怎么设计的"。

🧪 实操示例：用户注册功能

下面用一个最小例子把整套流程跑通。

Step 1：初始化项目

1
2
3

mkdir demo-app && cd demo-app
npm init -y
openspec init --tools claude

按提示选择 Claude Code，确认后 openspec/ 与 .claude/ 目录会一并生成。

Step 2：提案

在 Claude Code 对话框输入：

`1`	`/opsx:propose user-registration-with-email-verification`

需求描述示例：

添加用户注册功能：邮箱 + 密码，注册成功后发送验证邮件，72 小时内未验证则账号失效。

OpenSpec 会输出 4 个文档，其中 tasks.md 大致长这样：

## 1. 数据模型
- [ ] 1.1 创建 User 模型（email、passwordHash、status、emailVerifiedAt）
- [ ] 1.2 添加数据库迁移脚本

## 2. 接口实现
- [ ] 2.1 POST /api/register 入参校验
- [ ] 2.2 密码哈希存储（bcrypt）
- [ ] 2.3 发送验证邮件（含 72h 过期 token）

## 3. 测试
- [ ] 3.1 单元测试：邮箱格式校验
- [ ] 3.2 集成测试：注册 → 验证 → 登录完整流程

Step 3：触发 Superpowers 设计追问

`1`	`/superpowers:brainstorming "用户注册中的边界条件：邮箱重复怎么办？验证邮件链接重复点击怎么办？"`

Superpowers 会把"重复注册"“邮件链接过期"“重发验证邮件"这些边界条件逐条澄清，并写入设计文档。

Step 4：拆任务并 TDD 执行

1
2

/superpowers:writing-plans
/superpowers:test-driven-development

接下来 AI 会严格按红-绿-重构循环逐项推进。tasks.md 里的 checkbox 会一项项被勾掉。

Step 5：归档

`1`	`/opsx:archive user-registration-with-email-verification`

归档成功后 openspec/specs/user/spec.md 就会出现新的 Requirement / Scenario，整套变更历史可追溯。

⚠️ 注意事项与最佳实践

命令类型别搞混

CLI 命令（openspec init、git checkout -b）：在终端里直接跑。
Skill 命令（/opsx:propose、/superpowers:brainstorming）：在 AI 对话框里输入，由 AI 自动执行对应流程。

选对工作模式

OpenSpec 默认是 Core 模式（4 个命令够用）。如果项目复杂、需要更细的粒度，可以切换到 Expanded 模式：

1
2

openspec config profile   # 勾选 new/continue/ff/verify/bulk-archive/onboard
openspec update           # 让 AI 识别这些新命令

模型选型有讲究

OpenSpec 的 propose 与 Superpowers 的 brainstorming 都很吃推理能力，建议使用 Opus、GPT-5、Claude Sonnet 4.5 这一档；执行阶段（apply、TDD）可以用更便宜的模型，因为有规范文档兜底，弱模型也能稳住。

上下文要保持干净

OpenSpec 的精髓是"规范是上下文”。在 /opsx:apply 之前，建议新开一个干净的对话窗口，让 AI 只能从 specs/ 与 tasks.md 里读上下文，避免旧对话污染判断。

变更结束立刻归档

完成一个变更就 /opsx:archive，不要堆十几个 changes/ 不归档，否则规范库会越积越乱。

两种工具的"分工"再强调

阶段	谁主导	为什么
需求对齐	OpenSpec	需要结构化文档作为契约
设计澄清	Superpowers	需要反复追问，文档很难替代对话
计划拆分	Superpowers	需要按"工程师可执行"粒度拆
代码实现	两者皆可	看团队习惯
质量审查	Superpowers	强制 TDD 与 code-review 闭环
变更归档	OpenSpec	需要把 delta 合并到活文档

📝 总结

Superpowers 与 OpenSpec 不是一个二选一的问题，而是 “上规矩 + 下工艺” 的互补关系：

OpenSpec 把"想做什么"变成可审查、可追溯的规范文档，解决"AI 跑偏"的问题。
Superpowers 把"应该怎么写"变成强制的工程工作流，解决"AI 偷工减料"的问题。

两者配合后，AI 不再是一个"需要时刻盯着的实习生”，而是一个按规范交付、按流程实施、按纪律收尾 的工程师。比起单打独斗，组合使用至少带来三方面收益：

可审计：每个变更都有 proposal.md、specs/、tasks.md 留痕。
可复用：规范合并到 specs/ 后是活文档，新成员 onboarding 直接读 spec 即可。
可规模化：多人/多 Agent 协作时，规则在文档里、纪律在 Skill 里，AI 行为是一致的。

参考资料

OpenSpec 官方仓库：https://github.com/Fission-AI/OpenSpec
Superpowers 官方仓库：https://github.com/obra/superpowers