如果你也用AI写过代码大概率经历过这些“翻车”瞬间让AI加一个功能它顺手把不相干的文件全改了让它修个bug修完多出三个新bug今天能跑的代码明天换句话问它就给你重写一遍。我一开始以为是模型不够聪明后来才意识到问题不在AI而在我根本没有一套能约束它的工作流。这篇要讲的OpenSpec Superpowers Claude Code这套组合就是专门解决这个问题的。它把软件工程里的SDDSpec-Driven Development规范驱动开发和TDDTest-Driven Development测试驱动开发真正落地到AI编程场景让你从“用AI碰运气”变成“让AI按规格稳定交付”。如果你被AI乱改代码折磨过或者想在自己的项目里建立一套可持续的AI协作方式这篇内容应该能给你一个可以直接照抄的答案。1. AI编程为什么总翻车从“聊天写代码”到“规范驱动”1.1 聊出来的代码改出来的坑先说一个我自己的真实案例。有一次我想让AI给一个FastAPI项目加个分页参数需求描述得很清楚“给列表接口加page和page_size参数返回total字段。”结果AI不仅改了接口文件还顺带“优化”了数据库查询、重构了响应模型最后把另一个接口的字段名也改了。代码能跑但整个模块的风格全乱套了。这种情况不是个例。很多人的AI编程体验都是“第一版惊艳后续改起来想骂人”。原因其实很简单大语言模型的本质是“根据上下文续写文本”它没有一个全局的、稳定的“项目蓝图”概念。你问它“帮我改一下登录逻辑”它会基于当前看到的代码去猜而猜出来的结果往往带着它自己的“审美偏好”和“过度发挥”。这就像你让一个技术很厉害但从来不看图纸的施工队去装修你说“这里加个插座”他能给你把整面墙的线路都重新排一遍。活干得漂亮但你原本的规划全被打乱了。1.2 SDD和TDD到底在解决什么问题为了解决“AI乱发挥”的问题软件工程里的两个经典方法论被重新捡了起来。SDDSpec-Driven Development规范驱动开发。它的核心思路是在写代码之前先把“做什么、为什么做、怎么做、怎么验收”全部写成一份结构化的规格文档然后让AI严格按照这份文档去执行。文档里没写的事AI一律不做文档里写了的AI必须做。这样AI的“自由发挥空间”被压缩到了最小。TDDTest-Driven Development测试驱动开发。它的核心思路是先写测试再写实现。一个功能要满足什么条件才算完成先把这些条件写成自动化测试然后让代码去跑通测试。测试不过代码就不能算写完。这保证了“AI说它做完了”不靠谱但“测试都过了”才是真靠谱。单看这两个概念都不新鲜但放到AI编程场景里它们解决了一个非常关键的问题如何让AI的产出可验证、可追溯、可回退。过去我们靠“人肉review”去检查AI写的代码现在我们把验收标准前置让AI自己先过一遍“测试关”你再基于测试结果和diff去做判断效率完全不一样。1.3 OpenSpec和Superpowers的角色定位既然SDD和TDD是对的那怎么落地靠人手动写规格、手动写测试、手动盯着AI太累了。这时候就需要工具把这两个方法论固化到工作流里。OpenSpec就是负责“SDD落地”的工具。它把一次需求变更定义成一个结构化的目录里面包含变更提案、任务拆解、规格文档和验收条件。AI会基于OpenSpec的规范去生成这些文档再照着文档写代码。你不需要反复跟AI解释需求所有上下文都在文档里。Superpowers则是负责“AI工作流纪律”的工具。它是Claude Code的一套skills增强包给AI装上一整套“工程SOP”如何头脑风暴、如何写计划、如何执行计划、如何用Git规范提交、如何做8D问题分析。它让AI从“一次性对话生成代码”变成“按流程推进任务”。一句话定位OpenSpec管“做什么”Superpowers管“怎么做”Claude Code管“动手做”。三者合在一起就是一套完整的SDDTDD工作流。2. 拆开看OpenSpec和Superpowers它们凭什么能稳住AI2.1 OpenSpec把“需求”变成AI能执行的规格文档OpenSpec是一个开源命令行工具它的设计思路非常有意思。传统的需求文档是给人看的一堆Word、PDF、Wiki页面AI根本没法结构化地理解。OpenSpec反其道而行它把一次需求变更变成项目里的一个专属目录所有内容都是MarkdownAI可以直接读取、生成、修改。一次变更在OpenSpec里长这样changes/ 20250201_add-pagination/ proposal.md # 变更提案背景、目标、非目标、方案、权衡 tasks.md # 任务拆解具体的实施步骤 spec/ # 变更后的规格文档描述系统应该长什么样 tests/ # 验收条件可执行的测试描述proposal.md是这个变更的“说明书”回答的是“为什么要做这件事”。AI在生成代码前必须先想清楚背景、方案、替代方案。这一步看着多余实际上非常关键。很多AI写代码翻车就是因为需求还没想清楚就直接开写写出来自然南辕北辙。tasks.md是这个变更的“施工计划”回答的是“这件事要分几步做完”。每个task都应该是小而明确的便于AI逐步执行也便于你逐步review。spec目录记录的是“修改后的系统规格”它是项目长期演进的“宪法”。tests目录则把验收条件固化成文字每个核心功能点都有对应的验收标准。OpenSpec还提供了一套CLI命令来管理这些变更比如openspec validate检查文档格式是否符合规范openspec plan让AI基于规格生成任务计划openspec build让AI按计划逐项实现。这套机制的好处是从需求到实现的每一步都有文档记录且文档本身就是工作流的驱动源。AI不再是靠对话理解需求而是靠文档理解需求对话只是触发它去读文档的机制。2.2 Superpowers给AI装上“工程纪律”和“操作手册”如果说OpenSpec是“施工图纸”那Superpowers就是“施工队长手里的SOP手册”。Superpowers是Jesse Vincent发起的开源项目本质上是针对Claude Code设计的一套skills集合。它把AI编程过程中需要用到的各种能力拆成了一个个独立的skill每个skill都是一份结构化的指令文档包含触发条件、执行步骤、输出要求。我用的几个核心skill包括brainstorming在动手写代码前先和AI进行多轮结构化思考厘清需求和边界writing-plans把头脑风暴的结果转成一份可执行的分步计划executing-plans按计划逐步实施每完成一步就检查一步而不是一口气生成整个项目git-workflow让AI自主处理Git操作包括审查diff、生成规范的提交信息、创建分支、提交代码8d-problem-solving遇到问题时按“8D问题解决法”逐层排查而不是瞎猜瞎试。这些skill的作用是把“AI会做的事情”从“写代码”扩展成了“像工程师那样工作”。举个例子以前你让AI修一个bug它可能直接改一行代码就算完事。但有了8D和debugging skill它会先复现问题、再定位根因、写一个失败测试、修复、确认测试通过、最后提交。这一整套流程本质上就是TDD和工程实践的自动化。Superpowers的另一个关键特性是“multi-agent模式”。它可以让一个主Agent协调多个子Agent并行工作一个负责调研、一个负责写代码、一个负责审查。这种协作模式在OpenSpec拆解出多个task之后特别有用可以大幅缩短开发时间。2.3 两者如何组成SDDTDD闭环OpenSpec和Superpowers不是两套孤立的工具它们在工作流里是串在一起的。我实际跑的流程是这样的需求输入 ↓ Superpowers brainstorming和AI多轮对话把模糊的想法梳理清楚 ↓ OpenSpec生成Change ProposalAI基于梳理结果生成proposal.md和tasks.md ↓ Superpowers writing-plans把tasks细化成具体的执行计划 ↓ OpenSpec planAI读取spec规划本次要改哪些文件、写哪些测试 ↓ TDD红绿循环先用OpenSpec的tests/写失败测试再写实现让测试通过 ↓ Superpowers git-workflowAI审查diff、生成commit、提交代码 ↓ 验收并更新spec确认功能符合预期后更新规格文档项目进入下一轮迭代这套流程最妙的地方在于SDD负责把“需求”变成“规格和任务”TDD负责把“任务”变成“可验证的代码”而Superpowers则负责让AI在每一步都按规范操作。你不再是“盯着AI写代码”而是“盯着AI走流程”每一步都有产出物每一步都可检查、可回退。我经常用一个比喻OpenSpec是施工图纸Superpowers是施工流程手册Claude Code是施工队。图纸保证了“盖出来的楼是设计好的样子”流程手册保证了“施工队不偷懒、不跳步”施工队负责实际搬砖。三者缺一不可。3. 从零搭建工作流环境准备与安装细节3.1 前置环境清单与版本检查在动手安装之前先把环境检查一遍。这步看着繁琐但能省掉后面一大半的麻烦。# 检查Python版本需要3.10以上 python3 --version # 检查Node.js版本建议18以上 node --version # 检查Git git --version我自己的环境是macOS Python 3.12 Node 20跑起来没有任何问题。如果你用的是Windows建议优先用WSL2因为Superpowers里的很多脚本是按Linux环境写的直接在PowerShell里跑容易遇到路径和权限问题。还要准备一个能跑AI编程助手的终端工具。我的主力是Claude Code它通过命令行与项目交互适合这种“AI自主执行多步骤任务”的场景。如果你用的是Cursor或者其他AI编辑器也可以尝试但后面关于Superpowers的很多自动化流程还是Claude Code体验最好。3.2 安装并初始化OpenSpecOpenSpec的安装很简单官方提供了一键脚本curl -fsSL https://openspec.dev/install.sh | bash安装完成后确认一下版本openspec --version然后在你想要应用这套工作流的项目根目录里初始化openspec init这一步会在项目里生成一个openspec/目录里面包含了默认的规格目录结构和配置文件。整个项目会多出类似这样的结构openspec/ project.md # 项目级规格描述 specs/ # 当前系统规格快照 changes/ # 变更提案目录如果你的电脑安装后提示“openspec: command not found”多半是安装目录没有加到PATH里。安装脚本执行完会打印出需要添加的路径把它加到~/.zshrc或~/.bashrc里就行。3.3 安装并接入SuperpowersSuperpowers的安装方式比OpenSpec稍微“手工”一点因为它本质上是给Claude Code加载的一套skills增强包。先把仓库克隆到你熟悉的目录比如用户根目录git clone https://github.com/workswarm/superpowers.git ~/superpowers接着在项目里创建或编辑CLAUDE.md文件告诉Claude Code去加载这套skills。我习惯的做法是做一个软链接把Superpowers的skills目录挂到项目的.claude/skills下mkdir -p .claude ln -s ~/superpowers/skills .claude/skills如果你不想用软链接也可以直接把skills目录复制到项目里只是后续升级Superpowers时要再覆盖一次。对于需要长期维护的项目我推荐软链接易升级、不占仓库空间。然后在CLAUDE.md里写清楚引用说明## 工作流指南 本项目的所有AI辅助开发任务必须遵循以下工作流 1. 使用OpenSpec管理需求变更先创建Change Proposal再拆解Tasks。 2. 使用Superpowers的skills执行任务涉及规划和执行时参考对应的skill流程。 3. 采用TDD先写失败测试再实现功能确保测试全部通过后才算完成。 4. Git提交使用conventional commits格式提交前审查diff。这一步很关键因为Claude Code是通过CLAUDE.md来理解项目约定的。你不写清楚它就不会主动去加载Superpowers的skill流程。3.4 验证安装让AI主动识别这套工作流安装完不是就完事了先做个快速验证。打开Claude Code简单输入请列出现有项目的OpenSpec变更提案并说明你准备如何开始一个新功能。如果一切正常AI会主动读取openspec/目录和CLAUDE.md然后告诉你当前有多少个change、哪些在进行中。如果它完全没反应大概率是CLAUDE.md路径不对或者工作目录不对——确认一下你是在项目根目录打开的Claude Code。还有一个很常见的坑Superpowers的skill加载依赖“有没有把skills目录放对位置”。如果你发现AI完全不理会skills先检查.claude/skills软链接是否存在再检查CLAUDE.md中是否明确要求AI使用这些skill。我之前曾经在.claude目录外创建了软链接结果AI完全找不到白白折腾了一个小时。4. 实战用SDDTDD工作流开发一个待办事项API4.1 从一句需求到Change Proposal理论说再多不如跑一遍真实项目。我拿一个很常见的场景来演示用Python FastAPI给一个待办事项应用实现REST API支持创建任务、查询列表、标记完成任务、删除任务。我打开Claude Code输入需求需求实现一个待办事项REST API支持以下能力 1. 创建待办事项包含标题和截止日期 2. 按ID查询单个事项 3. 查询所有事项默认按创建时间倒序排列 4. 将事项标记为完成 5. 删除事项。 请使用OpenSpec流程先创建Change Proposal不要直接写代码。AI在OpenSpec规范引导下会在changes/目录下新建一个change proposal结构类似changes/ 20250215_todo-api/ proposal.md tasks.md spec/ tests/proposal.md里会写清楚背景用户需要一个待办事项管理能力、目标提供一套REST接口、非目标暂不做用户认证、不做UI、技术方案FastAPI SQLite、替代方案重量级框架Django以及数据模型和接口设计的初步草案。这里要敲黑板提醒你Change Proposal生成后一定要自己读一遍逐项确认。AI写的proposal可能有它自己的假设这些假设如果不符合你的意图后面实现完再改就很费劲了。比如AI可能会默认“截止日期”是必填字段但你的业务场景里它是可选的那就要在proposal里改清楚。4.2 把Proposal拆成可执行的TasksProposal通过review后AI会生成tasks.md把整个实现拆成几个小步骤。我那次生成的task列表大致是这样的## Tasks - [ ] task1: 定义Todo数据模型id, title, due_date, completed, created_at - [ ] task2: 创建数据库表结构使用SQLite SQLAlchemy - [ ] task3: 实现创建待办事项接口 POST /todos - [ ] task4: 实现查询待办事项接口 GET /todos 和 GET /todos/{id} - [ ] task5: 实现标记完成接口 PATCH /todos/{id}/complete - [ ] task6: 实现删除接口 DELETE /todos/{id} - [ ] task7: 编写所有接口的集成测试这个拆分有几个好处。第一每个task都足够小AI一次只干一件事出错范围可控。第二每个task都有清晰的验收标准接口能返回预期的状态码、数据格式正确适合用TDD逐个验证。第三task之间有依赖顺序AI按顺序执行时逻辑更接近人类工程师的工作方式。我习惯在拆task的时候要求AI在每个task后面标注“测试策略”比如task3要重点验证“创建成功后返回201和id”、“缺少title时返回422”。这样到了写测试阶段就不会临时想边界条件而是按计划执行。4.3 TDD红绿循环测试先行的实际体验Task拆好之后按OpenSpec的工作流AI会先处理task1和task2也就是数据模型和数据库表结构。这部分比较机械直接按规范写就行。关键在于task3往后的部分先写测试再写实现。以“创建待办事项接口”为例AI会先在tests/目录下写一个失败测试# tests/test_create_todo.py from fastapi.testclient import TestClient from app.main import app client TestClient(app) def test_create_todo_returns_201_and_todo(): payload {title: 写周报, due_date: 2025-03-01} response client.post(/todos, jsonpayload) assert response.status_code 201 data response.json() assert data[title] 写周报 assert data[completed] is False assert id in data def test_create_todo_missing_title_returns_422(): payload {due_date: 2025-03-01} response client.post(/todos, jsonpayload) assert response.status_code 422写完之后先跑一遍确认测试是失败的pytest tests/test_create_todo.py看到失败结果红再让AI去实现POST /todos接口。实现完成后再次跑测试直到全部通过绿。这个过程看着多了一道工序但它带来的稳定性是值得的。AI写完代码后“测试通过”替代了“AI说它做完了”前者的可信度高得多。等所有task都完成执行项目里全部测试确认没有回归pytest如果你发现某个测试很脆弱或者断言写错了导致“假绿”一定要立即修正测试本身。TDD里最怕的不是“测试失败”而是“测试错误地通过”那意味着验收标准是错的整个工作流就失去了意义。4.4 让AI自己提交代码Superpowers的Git工作流代码写完了、测试也过了接下来就是工程化最见功力的环节——Git提交。很多人的习惯是让AI写代码然后自己手动commit这样又回到“人工打杂”的模式了。Superpowers的git-workflow skill就是专门解决这个痛点的。在完成一个task后我会要求AI执行git提交。它会先查看当前的diff检查有哪些文件改动然后对照conventional commits规范生成一个提交信息。比如feat(todo): 添加创建待办事项接口 - 实现POST /todos接口 - 支持title和due_date字段 - 缺少必填字段时返回422 - 新增create_todo接口测试AI还会自动判断提交的粒度。比如task3和task4是相互独立的接口实现它会分批提交而不是把所有改动揉成一个大的commit。这和你自己写代码时的习惯是一致的每个提交对应一个逻辑变更方便后续回溯和回退。如果你是在团队协作里用这套工作流还可以让AI在完成一批功能后基于Git历史自动生成一份PR描述把变更内容、测试结果、影响范围都写清楚。我自己用下来的体验是团队review代码时不再需要从头到尾猜“这段代码为什么这么写”PR本身就是一份完整的设计文档。5. 真实环境里最容易踩的坑和排查方法5.1 环境与依赖问题速查在实际落地这套工作流时环境问题往往是第一个坎。下面是我遇到过的几类典型问题你可以直接对照排查。现象可能原因解决办法openspec: command not found安装目录未加入PATH将安装脚本输出的路径加入~/.zshrc或~/.bashrc重新加载Shell运行OpenSpec命令时提示缺少Python包Python环境未安装项目的依赖根据提示在Python环境中执行pip install -r requirements.txt或安装对应包Superpowers skill没有生效.claude/skills目录不存在或路径不对确认软链接/复制路径正确并在CLAUDE.md里明确要求AI使用这些skillOpenSpec生成的proposal格式校验失败Markdown格式不符合约定运行openspec validate查看具体错误按提示修正一下文档结构Claude Code没反应不读取任何工作流文件当前工作目录不在项目根目录切换到项目根目录再启动Claude Code特别是“运行OpenSpec命令时提示缺少Python包”这个问题是一个非常经典的环境坑。它的本质不是OpenSpec坏了而是你当前激活的Python虚拟环境里缺少对应依赖。我建议在项目里单独建一个虚拟环境把OpenSpec和项目依赖都装进去避免和系统Python环境互相污染。5.2 工作流失控的典型场景环境装好了工作流也不一定一帆风顺。我这段时间实践下来遇到过几个“流程崩坏”的典型场景。第一个场景是AI跳步。明明OpenSpec的change proposal只定义了“查询列表”接口AI在实现的时候顺手把“删除”接口也写了。表面上看是“AI更主动了”实际上这是非常危险的行为——它破坏了文档和代码的一致性后续的review和测试都会变得混乱。我的解决办法是在CLAUDE.md里加了一句话“严格按OpenSpec tasks.md中的task顺序执行每个task只完成该task定义的内容未列入task的功能一律不允许实现。”这句话能显著减少AI的“自主发挥”。第二个场景是测试假绿。AI写了一个测试断言写得很宽松比如只检查状态码是200不检查响应体内容。结果实现代码返回一个空对象测试照样过。这本质上不是AI的问题而是验收条件写得不够严格。后来我养成了一个习惯每个测试写完后先让它失败一次确认测试真的能捕获问题。如果某个测试从没失败过我对它的信任度会很低。第三个场景是spec文档和代码脱钩。随着功能迭代代码已经改了好几轮但OpenSpec的spec目录还停留在最开始的版本。时间一长新来的AI读到的规格和实际代码对不上就会产生各种“矛盾指令”。我现在每完成一个task都会要求AI同步更新对应的spec文档并在提交信息里体现“docs: 更新xxx规格”。5.3 独家避坑清单与个人心得经过几个项目的实践我整理了几条带个人色彩的建议供你在落地时参考。不要什么改动都走OpenSpec流程。修一个拼写错误、调一个日志级别直接让AI改完提交就行。OpenSpec的价值在于“有明确业务目标的需求变更”小改动走全流程反而增加负担。review Change Proposal的优先级高于review代码。很多人习惯等AI写完代码再review但从我的经验看如果proposal阶段方向就错了代码写得再漂亮也没用。我大概会花整个流程40%的时间在proposal和tasks的review上后面写代码反而很快。每完成一个task就提交一次不要攒到所有task完成后统一提交。一方面小提交的diff更清晰出问题好回退另一方面AI在单个task内的上下文更集中不容易迷失。定期跑openspec validate把它当成项目体检的一部分。这个命令会检查变更提案和规格文档的完整性与规范性能帮你早发现文档和代码脱钩的问题。最后我想说一点更主观的体会。这套工作流不是银弹它不会让AI突然变成10倍经验的资深工程师但它会改变你和AI的协作方式——从“让AI替我做”变成“让AI按我的标准做”。期间你会发现你把大量精力从“检查AI写得好不好”转移到了“定义什么算好”而后者恰恰是工程能力最核心的部分。这套组合本质上是在训练你像一个架构师那样思考。我的建议是先拿一个非核心模块跑通流程感受一下“规范驱动”和“聊天驱动”的区别再决定要不要推广到所有项目。我自己在跑通第一个完整流程后就再也没回到过“不写spec就让AI写代码”的老路上。