1. 工作流为什么值得搭先理解 SDD 和 TDD 的真实定位我一直在用 Claude Code 辅助写代码最初阶段基本是想到什么让 AI 写什么结果项目刚起步时跑得飞快越到后面越乱。尤其是全栈项目前后端接口、数据库字段、页面状态管理混在一起AI 经常出现“改完 A 崩了 B”的连锁反应。后面我意识到问题不在 AI 本身而在我的使用方式没给它一个稳定的上下文和验证闭环。后来我接触到了 OpenSpec 和 Superpowers 这套组合把 SDDSpec-Driven Development规格驱动开发和 TDDTest-Driven Development测试驱动开发真正落到了 AI 编程工作流里。先说结论这套流程的核心目的不是“让 AI 写更多代码”而是“让 AI 在明确的边界内写对代码”。适合谁适合那些已经用 Claude Code、Cursor 或其他 AI 编程工具做实际项目、但总觉得交付不稳定的人。也适合想从“聊天式写代码”升级到“工程化交付”的开发者。SDD 的思路其实很朴素在写任何业务代码之前先把“做什么、不做什么、怎么验证”用结构化的文档定下来。这个文档不是给人看的摆设而是给 AI 看的约束。TDD 的思路也早就不新鲜先写测试再写实现用测试结果作为完成标准。把两者结合起来等于给 AI 配了一份需求说明书加一份验收清单。OpenSpec 负责“需求说明书”那一层。它定义了一套标准化的规格文件格式用来描述功能特性、需求条目、验收标准并且能输出成 AI 友好的 markdown 文档。Superpowers 负责“执行层”。它是一组针对 Claude Code 的技能增强包提供了计划分解、文件操作、测试执行等原子化能力让 Claude Code 的行动更有章法。2. 搭建前的准备两个核心工具到底装了什么2.1 OpenSpec 的安装与核心概念OpenSpec 的安装命令很简单官方文档给的是curl -fsSL https://openspec.dev/install.sh | bash装完后它会初始化一个.openspec目录用于存放项目的规格文件。这个目录的结构大致是这样.openspec/ ├── project.md # 项目级说明描述整体目标和技术栈 ├── specs/ │ ├── feature-name/ # 每个功能一个目录 │ │ ├── proposal.md # 功能说明 │ │ ├── requirements.md # 需求列表 │ │ └── checklist.md # 验收标准 │ └── archive/ # 归档 └── templates/ # 规格模板我为啥觉得这个结构很有价值因为它强制你按照固定模式思考而不是让 AI 猜你的需求。specs 目录下的每个功能都有独立的 proposal、requirements、checklist 三件套。proposal 回答“为什么做这个”requirements 回答“具体要做什么”checklist 回答“怎么做才算完成”。举个例子如果你要做用户登录功能requirements 里会写清楚“用户可以通过邮箱和密码登录”“登录成功后跳转到首页”这类条目每条最好都带上独立的 ID。checklist 则对应验收标准比如“提供错误密码时显示错误提示”这种可验证的条目。OpenSpec 还提供了命令行工具可以检查和渲染这些规格。其中我觉得比较实用的命令是openspec check它能验证规格文件格式是否正确。还有一个openspec prompt之类的指令能把规格内容组装成适合发给 AI 的提示词避免你手动复制粘贴大段 markdown。2.2 Superpowers 的安装与定位Superpowers 是一个给 Claude Code 用的技能总成Github 地址是github.com/obra/superpowers安装方式很直接claude install superpowers装完后它会在 Claude Code 的配置目录里加入一系列技能文件核心能力包括计划技能把大任务拆解成子任务清单每步都有明确目标和完成标准。文件技能提供读写文件的严格流程避免 AI 乱改文件导致项目崩溃。测试技能自动查找测试命令、运行测试、定位失败原因并修复。调试技能面对报错时系统化缩小排查范围而不是随机试错。我一开始以为 Superpowers 就是往 Claude Code 里塞了一堆 prompt没什么大不了的。实际用下来发现我低估了它的价值。它的技能文件不只是“提示词”而是一套可执行的流程。比如计划技能会要求 AI 先生成计划让我确认后再行动。这个确认环节看起来拖慢速度实际上省掉了大量返工时间。另外要注意Superpowers 对工作目录有要求。它会把技能文件安装到~/.claude/skills或项目目录的.claude/skills下。如果你发现 Claude Code 没有加载到这些技能多半是路径配置有问题后面我会专门说怎么排查。2.3 两者的分工与配合逻辑OpenSpec 管“定义”Superpowers 管“执行”SDD 和 TDD 是把两者串起来的完整闭环。我把这个流程总结成一句话OpenSpec 提供规格蓝图Superpowers 驱动 Claude Code 按蓝图施工并在每一层用测试来验证。这里有一个常见误区有人以为用了 OpenSpec 就不再需要 TDD或者用了 TDD 就不需要写规格。实际上 SDD 解决的是“范围的确定性”TDD 解决的是“结果的可验证性”。没有 SDD 的 TDD 容易陷入“测试写了不少但测的根本不是用户要的功能”这种局面没有 TDD 的 SDD 则是“文档写得漂亮代码跑起来一团糟”。两者缺一不可。3. 实操从零开始搭建 SDDTDD 工作流3.1 初始化项目与规格文件第一步先在项目根目录初始化 OpenSpec 目录结构cd my-project openspec init如果你用的是其他初始化命令以当前版本输出为准。初始化完成后我会先编辑.openspec/project.md把这个项目的技术栈、目录结构、常用命令写进去。这一步特别重要因为 Claude Code 会把 project.md 作为全局上下文来读取它会直接影响 AI 后面所有决策的“世界观”。举个例子我的一个全栈项目里 project.md 写的是# 项目说明 - 技术栈FastAPI React SQLite - 后端入口app/main.py - 前端入口src/App.tsx - 数据库文件dev.db由 SQLAlchemy 自动创建 - 测试命令后端 pytest前端 npm test - 代码规范Python 使用 blackTypeScript 使用 eslint别小看这段描述它等于给 AI 定了边界。没有这些信息时AI 可能默认项目是 Node.js 写的然后给你生成一堆没用的 package.json 配置。有了明确的 project.mdAI 第一次行动的方向就会准确得多。第二步创建功能规格。拿我之前做的一个“任务提醒”功能举例openspec new remind这条命令会在.openspec/specs/remind/下生成模板文件。接下来我按需求编辑三个文件。proposal.md里写的核心内容## 为什么做 用户经常忘记重要的待办事项需要在指定时间收到提醒通知。 ## 目标 - 用户可以为任务设置提醒时间 - 到时间后系统通过应用内通知提醒用户 - 提醒支持取消 ## 非目标 - 不做邮件提醒 - 不做短信提醒requirements.md里写详细需求## 功能需求 - REQ-1: 用户可以为任务设置一个提醒时间 - REQ-2: 系统在到达提醒时间时显示应用内通知 - REQ-3: 用户可以在提醒触发前取消提醒 ## 界面需求 - 设置提醒时间时使用日期时间选择器 - 通知区域显示任务标题和提醒时间 ## 数据需求 - 提醒时间字段直接挂在任务记录上 - 取消提醒等于将任务提醒时间置空checklist.md写验收清单## 验收标准 - [ ] 用户能设置提醒时间且时间精确到分钟 - [ ] 到达提醒时间后应用内弹出通知 - [ ] 未触发提醒前用户可以取消提醒 - [ ] 已触发的提醒不会二次弹出写完这三个文件后我会跑一下openspec check确保格式没有问题。理论上这时 OpenSpec 会把规格文件渲染成更结构化的 markdown方便后续发给 AI。3.2 让 Claude Code 加载 Superpowers 并制定计划规格文件就绪后打开 Claude Code把需求描述给它同时点名要它使用 Superpowers 的计划技能。我的典型提示词是这样请阅读 .openspec/specs/remind/ 下的所有文件。 使用 superpowers 的计划能力把这个功能拆解为可执行的子任务。 计划需要包含每一项任务的输入、输出、验证方式。 在开始写任何代码前先把完整计划展示给我确认。这里的关键词是“先展示计划等我确认”。如果没有这句Claude Code 很容易一上来就开始改代码一旦理解偏差后面的测试和修改都会跟着错。Superpowers 的计划技能会产出一个结构化的子任务清单每项包含任务目标、涉及文件、完成标准。比如它会列出创建 Task model 的提醒时间字段迁移更新 API 接收提醒时间的 schema前端添加日期时间选择器组件编写提醒触发逻辑测试覆盖设置/取消提醒场景我会先看看这个计划是否合理有没有漏掉边界情况。确认后再让 Claude Code 按计划执行。很多人在这一步容易跳太快。我想提醒一句计划确认环节是整个流程中最值得耐心的部分。宁可在这里花十分钟看计划也不要在代码写完后花三个小时修 bug。3.3 先写测试再写实现TDD 的落地方式计划确认后进入具体的开发环节。按照 TDD 的节奏第一件事不是写业务代码而是写测试。我让 Claude Code 先基于 checklist 里的验收标准生成测试。以提醒功能为例后端测试可能在tests/test_reminders.py里def test_set_reminder_with_valid_time(client, auth_headers): task_id create_task(client, auth_headers) response client.post( f/api/tasks/{task_id}/reminder, json{remind_at: 2025-06-01T10:00:00}, headersauth_headers, ) assert response.status_code 200 assert response.json()[remind_at] 2025-06-01T10:00:00 def test_cancel_reminder(client, auth_headers): task_id create_task_with_reminder(client, auth_headers) response client.delete( f/api/tasks/{task_id}/reminder, headersauth_headers, ) assert response.status_code 200 assert response.json()[remind_at] is None前端测试大概长这样test(任务可以设置提醒时间, () { render(TaskCard task{mockTask} /); const timeInput screen.getByLabelText(提醒时间); fireEvent.change(timeInput, { target: { value: 2025-06-01T10:00 } }); expect(screen.getByRole(button, { name: 保存提醒 })).toBeEnabled(); });测试先写出来意味着我们把“什么叫完成”提前固定了。之后 Claude Code 写业务代码时它的目标就不再是“大概实现类似功能”而是“让这批测试通过”。写测试时有个要点测试不要写得太细、太耦合到实现。如果测试断言卡死了内部函数名或者 UI 组件的具体层级后面重构时测试反而成了负担。我一般会强调“基于行为写测试”也就是用户视角的输入输出而不是代码视角的内部调用。3.4 循环执行实现、测试、修复测试准备好后让 Claude Code 按计划实现功能。这时候 Superpowers 的测试技能会起作用它会自动找到项目的测试命令跑一遍测试然后把失败结果带回来修复。我常用这样的指令现在开始实现计划中的任务 1。 完成后运行测试并对照 specs/remind/checklist.md 的验收标准逐项检查。 如果测试失败分析原因后修复直到测试全部通过。实现阶段Claude Code 会根据 project.md 里的技术栈信息选择合适的代码风格。比如项目用了 FastAPI它就会生成 FastAPI 的 router、schema项目用了 SQLAlchemy它就会更新 model 和 migration。跑测试时后端会用 pytest前端会用 npm test。如果两者都通过再让 Claude Code 逐条把 checklist 勾掉。这个过程就是我们常说的“红-绿-重构”循环只是执行者从人变成了 AI。人的角色变成了检查者和决策者AI 成了具体执行者。从我实际使用的感受来看这套循环最大的价值在于AI 每完成一小步都被验证过一次。就算中途出了偏差问题会被尽早暴露修复成本也低得多不会拖到最后一口气爆出十几个 error。4. 工作流落地里的细节我踩过的坑与实用技巧4.1 规格文件是给 AI 看的“需求合同”别写成散文我见过不少人在 requirements.md 里写出大段大段的描述性文字比如“用户希望能方便地设置提醒时间系统应该提供友好的界面”。这种话对 AI 来说几乎是无效信息因为它无法从中提取出可执行的验收标准。正确的做法是让需求条目保持原子性、可验证性和独立性错误写法正确写法用户能方便地设置提醒REQ-1: 在任务编辑页提供日期时间选择器系统能及时提醒用户REQ-2: 到达提醒时间后 5 秒内弹出应用内通知数据保存要稳定REQ-3: 提醒时间保存后刷新页面仍可见每一条需求都应该能被一个测试或一次人肉检查覆盖。如果一条需求没法判断“通过还是没通过”它对 AI 来说就是无用信息。另外proposal.md 里的“非目标”也要认真写。AI 的常见问题是过度实现你让它做 A它顺手把 B、C、D 都做了代码量暴增、风险变大。非目标清单可以帮助 AI 收敛实现范围避免过度设计。4.2 关于确认环节别嫌麻烦多确认一次Superpowers 的计划技能默认会要求确认再执行但如果你在提示词里没有指定或者上下文太长导致它忘记了这个要求它可能会直接一路跑到底。我习惯在每轮会话开头强调一遍规则。对于大项目我通常会分阶段确认对于小改动可能只确认一次就够了。把握一个原则变更影响范围越大确认层级越要细分。比如只改一个按钮文案可以全自动跑但涉及数据库 schema 变更每一步都要盯着。4.3 测试失败时别让 AI 靠“猜”修复TDD 流程中出现测试失败是常态。很多人的处理方式是把报错信息直接丢给 AI让它“修复一下”。这种方式偶尔好用但常常会修出新的问题。我建议给 AI 更多上下文让它先定位再修复。举个例子后端测试 test_set_reminder_with_valid_time 失败失败信息是 KeyError: remind_at 请先查看 app/routers/tasks.py 中创建提醒接口的实现 以及 tests/test_reminders.py 中测试的请求结构 分析是字段名不匹配还是返回结构缺少字段修复后重新运行全部测试。这种指令让 AI 的诊断路径清晰很多而不是盲目重试。另外一个技巧是让 AI 在修复后解释原因。让它告诉你“为什么会出现这个 bug、修了什么、影响范围是哪些”这样你能判断它是否真正理解了问题也能在代码审查时更有把握。5. 常见问题与排查技巧实录5.1 问题速查表现象可能原因解决方法OpenSpec 命令找不到安装脚本没把 bin 目录加入 PATH检查安装路径手动 export PATH或重启终端Claude Code 不执行 Superpowers 技能skills 目录放错位置或版本不兼容检查 skills 是否在~/.claude/skills或项目.claude/skills重装规格文件运行 check 报错格式不合法比如缺少必需字段用openspec check看具体错误行对照模板修改AI 不按照 requirements 实现自己发挥上下文太长导致规格被忽略在提示词中重新放置规格文件内容或拆分功能规模测试一直过不去AI 反复修同一处测试本身写错了或与实现预期不一致人工检查测试代码确认测试和需求对得上跑了测试之后 AI 忘了下一步任务清单不完整重新让 AI 读取计划技能并按清单逐项执行5.2 重要提示环境依赖与 Python 相关报错如果你是第一次配置 OpenSpec可能会遇到类似“请安装缺失的包以使用此工作流”的提示。这个提示一般是说你当前 Python 环境缺少某些依赖尤其是你通过pip安装了一些基础包后OpenSpec 的辅助脚本跑不起来。解决办法很简单按提示在你的 Python 环境里把缺失包装上就行。我踩过的一个具体坑是同时装过不同版本的 Python系统默认的python3指向 3.8但 OpenSpec 需要更高版本特性。后来我改用虚拟环境把依赖全部装在里面再用绝对路径调用问题就消失了。所以如果你有多个 Python 环境务必确认 OpenSpec 运行时用的是哪一个。如果你在虚拟环境中先激活虚拟环境再运行安装和检查命令会省掉很多不必要的麻烦。5.3 确保 Claude Code 使用最新的项目上下文如果你在编辑.openspec/project.md之后发现 AI 的反应还是老样子没有体现新的项目描述大概率是上下文被缓存了。最简单粗暴但有效的做法是开一个新的 Claude Code 会话或者用/clear清空当前会话上下文然后再把规格文件路径指给它。另外当功能规模变大比如一个 spec 里有 20 条 requirementAI 可能在执行到后面时忘掉前面的内容。我会定期把 requirements.md 的核心内容重复贴进对话或者在每个子任务开始时让它重新读取一次 checklist确保它始终以验收标准为参照。6. 让工作流适配你的项目几个可扩展的方向6.1 并行推进多个功能时的规格管理如果你的项目同时有三四个功能在开发建议一个功能对应一个 spec 目录互不干扰。OpenSpec 的 specs 目录天然支持这种并行结构每个目录独立维护自己的 proposal、requirements、checklist。我个人习惯是每个功能分支上只允许修改自己 spec 目录下的文件和对应代码文件。这样等代码审查、合并回主分支时规格和代码是一一对应的审查起来一目了然。6.2 从单体项目扩展到多模块架构当项目越来越大.openspec 目录还会继续膨胀。到后期我通常会在project.md里增加“模块地图”小节把每个模块对应的 spec 目录列出来并标注模块间的依赖关系。这能帮助 Claude Code 在全局理解的基础上做局部变更避免改了这个模块却影响另一个模块。例如## 模块地图 - auth用户认证依赖 user 库规格见 specs/auth/ - tasks任务管理依赖 auth规格见 specs/tasks/ - reminders提醒功能依赖 tasks规格见 specs/remind/6.3 把它接入 CI让验收标准自动执行既然每一个 checklist 都对应着测试用例理论上就可以把这些测试接入 CI。当 CI 跑不过时问题会直接关联到对应的 spec。这样从需求到代码到验证整条链路全部有迹可循。这个思路也意味着你的项目在工程化上迈了一大步。以前验收靠人盯现在验收靠测试跑AI 写代码的压力也小了很多因为边界和标准都提前界定好了。7. 写在最后的一点个人体会我自己用这套 OpenSpec Superpowers 的组合大概有几个月时间最大的感受是“AI 的产出稳定性提升了而不是产出速度提升”。如果不做规格和测试约束AI 写代码快是真的快但经常快中出错。而一旦建立了 SDDTDD 的闭环AI 的试错成本被大大降低它更像一个能自己检查作业的实习生而不是一个闷头乱写的打字机。如果让我给刚开始尝试的人一个建议我会说别急着一次性把整个流程铺到所有项目上。先选一个小功能比如一个列表页面的查询、一个表单校验完整走一遍从写规格到测试通过的闭环。跑通之后你心里就有底了再逐步扩大使用范围。因为这套流程的收益是在你熟悉它之后才真正体现出来的。最后再分享一个小技巧每次功能收尾后把规格文件里的 checklist 全部勾上的那一刻记得让 AI 输出一段简短的“实现纪要”记录关键决策、改动文件和遗留问题。这样即使过几个月再回来看这个功能你和 AI 都能快速恢复上下文不必从头把代码重新读一遍。这套工作流的价值会随着项目复杂度增加而被越来越放大。