不知道你有没有遇到过这种场景使用 Cursor 写用户权限模块vibe coding了3小时代码跑起来才发现AI把角色继承的逻辑搞反了——我明明说过要RBAC0它写成了RBAC1的继承方向。改到第5版的时候AI已经忘了我最开始提的「不支持动态角色」的约束。这种破事我起码遇到过十次。直到上个月试了GitHub官方出的spec-kit才终于不用在AI的「自由发挥」和我的「反复返工」之间反复横跳。1为什么要搞清楚这件事很多人觉得SDD就是「先写文档再写代码」的老古董这完全是误解。SDD的核心是把spec从静态文档变成可执行合约代码是spec的衍生品而不是反过来让文档服务代码。这跟传统的「需求文档」有根本区别需求文档写完就扔spec写完之后是持续驱动的——每次改需求先改spec再让AI根据spec重新生成代码。我用vibe coding的时候提需求全靠嘴AI理解对了对我有利理解错了我背锅。SDD的逻辑是反过来我先花20分钟把需求、约束、验收标准写清楚AI必须按照这个来生成代码跑不通是AI的问题不是我需求没说清。spec-kit就是把这个逻辑做成通用工具链的产品不是某一个AI编码工具的附属品——它现在支持Claude Code、Cursor、Copilot、Gemini CLI等30编码代理GitHub官方维护截至2026-06-25已经有115,317个star最新版本是v0.11.82026-06-24更新活跃度完全不用担心。2它是怎么工作的spec-kit的核心工作流是5步每一步都有明确的输入、输出和验收标准。你可以跳过某些步骤但代价是后面更容易翻车。第1步写项目宪法/speckit.constitution这个步骤是定项目的「根本大法」。所有后续的spec、plan、代码都必须遵守这个文件里的规则。就像国家宪法高于所有法律constitution高于所有spec。我拿一个待办事项REST API做例子。执行命令/speckit.constitutionAI会问你几个问题比如用什么语言、什么框架、代码规范是什么。我的回答是Go 1.22 Gin GORM MySQL 8.0错误处理必须返回自定义错误码不允许panic不允许全局变量不允许在handler层直接写SQL。生成出来的constitution.md会把这些规则全部结构化记录下来后面每次specify、plan、implement都会自动遵守这些约束。这一步千万不要敷衍。constitution写得越详细后面AI瞎猜的空间就越小。我第一次用的时候只写了「用Go」结果AI给我选了标准库HTTP而不是Gin后来不得不从头重新plan。第2步写需求规格/speckit.specify这个步骤只写「要做什么」完全不涉及技术实现。你需要描述的是用户故事和验收标准不是技术栈。/speckit.specify我提的需求是「做一个待办事项API支持创建、查询、更新、删除待办每个待办包含标题、内容、截止时间、状态未完成/已完成支持按状态筛选」。生成的spec.md会自动拆分为用户故事和验收标准## 用户故事1. 作为用户我可以创建待办这样我不会忘记要做的事2. 作为用户我可以按状态筛选待办方便区分已完成和未完成## 验收标准- 创建待办必须包含标题缺少标题返回400错误- 截止时间格式必须为RFC3339格式错误返回400错误- 按状态筛选返回的结果只包含对应状态的待办第3步澄清模糊点/speckit.clarify可选但强烈建议我第一次用的时候跳过了这个步骤后面改需求改到吐。这个步骤是让AI把spec里模糊的点列出来让你确认。比如我刚才的spec里没说删除是软删除还是硬删除没说截止时间允许是过去的日期没说待办是否支持批量删除。AI会把这些模糊点全部列出来问你。/speckit.clarify回答完之后spec会自动更新。我后来养成了一个习惯不管需求多简单都要跑一遍clarify至少能少踩80%的需求理解偏差的坑。第4步写技术实现计划/speckit.plan这个步骤是把需求翻译成技术方案指定具体的实现细节。constitution里的技术栈约束会被自动应用。/speckit.planAI会根据constitution和spec生成技术计划包括目录结构、接口定义、数据库表结构## 目录结构├── handler/│ └── todo.go├── service/│ └── todo.go├── model/│ └── todo.go└── router/└── router.go## 数据库表结构CREATE TABLE todos (id bigint unsigned NOT NULL AUTO_INCREMENT,title varchar(255) NOT NULL,content text,deadline datetime NOT NULL,status tinyint NOT NULL DEFAULT 0 COMMENT 0-未完成 1-已完成,PRIMARY KEY (id)) ENGINEInnoDB DEFAULT CHARSETutf8mb4;第5步生成任务列表/speckit.tasks这个步骤是把plan拆成可执行的任务每个任务都有明确的验收标准类似TDD里的测试用例。/speckit.tasks生成的tasks.md里每个任务都是小而明确的## task001初始化项目结构验收标准目录结构和plan里定义的一致可正常启动服务## task002实现待办创建接口验收标准POST /api/todos可以创建待办参数校验正确第6步执行实现/speckit.implement到最后一步了。AI会按照任务列表逐一实现代码不需要你手动写任何业务逻辑。/speckit.implement每个任务完成之后都会自动跑单元测试。全部通过之后提示你验收。如果我后面要改需求比如给待办加个「优先级」字段不需要改代码。直接改spec.md然后执行/speckit.converge检查代码和spec的一致性再重新跑/speckit.implementAI会自动更新对应的代码。这里有个设计哲学值得琢磨。spec-kit把「做什么」和「怎么做」彻底分离了。spec只管意图plan只管技术路径代码只是两者的最终表达。这意味着你可以随时换技术栈——只要改plan里的技术选择重新implement就行spec完全不用动。GitHub官方博客的作者Tomas Vesely甚至尝试过把一个Go项目的spec直接编译成另一个语言代码全部扔掉重新生成。3动手接入从安装到第一次实现10分钟本文环境 macOS / specify-cli v0.11.8 / Claude Code / Python 3.10 / uv第1步安装specify CLI# 用uv安装指定版本uv tool install specify-cli --from githttps://github.com/github/spec-kit.gitv0.11.8# 验证安装specify --version验证输出specify-cli v0.11.8即安装成功第2步初始化项目# 创建项目指定集成Claude Codespecify init todo-api --integration claudecd todo-api验证项目目录下出现.specify/目录里面包含constitution.md模板和templates/子目录如果你用其他工具初始化的时候换integration就行# Cursor用户specify init todo-api --integration cursor-agent# Copilot用户specify init todo-api --integration copilot# 查看所有支持的integrationspecify integration list第3步走完5步核心流程依次执行/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement验证每个步骤完成后检查.specify/specs/目录下对应的.md文件是否生成4常见报错与解决报错1uv tool install失败提示 Python 版本不兼容原因specify-cli 要求 Python 3.10如果你的系统Python版本低于3.10会报这个错。解决# 用uv自带的Pythonuv tool install specify-cli --from githttps://github.com/github/spec-kit.gitv0.11.8 --python 3.12报错2/speckit.constitution执行后AI没有生成constitution.md原因spec-kit是通过slash command和AI编码代理交互的如果你的代理版本太旧可能不支持slash command。解决升级你的AI编码代理到最新版本或者检查.claude/commands/目录下是否有speckit相关的命令文件。5和Superpowers SDD的延续性从内部机制到通用工具写过我之前那篇「Superpowers v6.0 SDD重写深度拆解」的朋友应该记得Superpowers的核心设计是Do Not Trust the Report——不信任subagent的自我汇报必须通过diff验证结果。spec-kit其实是把Superpowers内部的SDD方法论抽出来做成了通用工具核心逻辑完全一致核心哲学都是Power Inversion——spec是老大代码必须服从spec。在Superpowers里这是通过subagent的内部架构实现的普通人看不到也用不了。在spec-kit里同样的哲学变成了任何人都能执行的slash command。区别不是方法论不同是可触达性不同。Superpowers是「SDD在Skill内部的工程实践」spec-kit是「SDD作为通用开发流程对外开放」。前者需要你装特定Skill后者只需要一个uv tool install。63种spec持久化模型不同团队怎么选这部分是很多介绍spec-kit的文章都没讲到的我特意翻了官方的docs/concepts/spec-persistence.md整理了三种模型的适用场景。说实话这三种模型不是spec-kit发明的。Martin Fowler在分析SDD工具的时候就提过类似的分类Spec-first先写spec然后可以扔掉、Spec-anchoredspec写完保留后续变更参照、Spec-as-sourcespec是唯一源代码是衍生品。spec-kit只是把这些策略变成了可选择的配置。我个人的建议10人以下的团队直接用Flow-back灵活度高每周做一次/speckit.converge检查一致性就够。金融类的团队必须用Flow-forward审计的时候能追溯到每一次需求变更。Living Spec适合产品已经稳定、只需要维护和少量迭代的项目——比如你公司内部的管理后台需求一年改不了几次。7Extensions和Presets系统自定义你的SDD流程spec-kit支持扩展你可以自己加命令、加hook也可以自定义模板。优先级从高到低Project-Local Overrides.specify/templates/overrides/——单项目调整不改全局Presets——自定义核心模板和术语比如把默认的MIT协议改成你公司的内部协议Extensions——添加新命令、hook、capabilities比如在implement之后自动跑代码扫描Core——spec-kit核心默认模板模板解析是运行时的——spec-kit从上往下找第一个匹配的就用。这意味着你可以在不改核心代码的情况下几乎完全定制SDD流程。比如你可以写一个test扩展在/speckit.implement完成之后自动跑单元测试。也可以自定义preset把默认生成的spec模板改成你团队习惯的格式。社区已经有人贡献了一些扩展和preset可以在spec-kit官方文档的Community页面找到。8踩坑实录不要跳过clarify步骤我第一次用的时候觉得自己的需求写得够清楚了跳过了/speckit.clarify步骤结果plan的时候AI默认给待办删除做了软删除而我们的需求是硬删除。后面改的时候要改spec、plan、tasks三个文件花了将近1小时。后来我每篇spec都跑一遍clarify哪怕需求只有3句话。AI会列出你可能没想到的边界条件空值怎么处理、并发冲突怎么解决、异常情况返回什么状态码。这些点如果不提前确认implement的时候就全靠AI自己猜猜错了你又要返工。还有一个坑constitution里如果只写「用Go」不写具体框架AI可能选标准库net/http而不是Gin。所以constitution尽量写具体技术栈、框架版本、代码规范、禁止项一个都别漏。9什么时候用spec-kit什么时候别用适合用的场景新项目从0到1需求还没完全想清楚——先写spec帮你理清思路给现有系统加新功能——spec能确保新代码和现有架构一致团队协作需求变更频繁——spec是共享的真相源每个人看到的都一样用AI编码代理写代码经常因为需求理解偏差返工——SDD能大幅减少返工不适合的场景一次性脚本、临时工具——写spec的时间比写代码还长需求已经100%明确且不会变——直接写代码更快你不用AI编码代理——spec-kit的价值在于让AI按照spec生成代码如果你全程手动写spec只是额外负担10常见问题Qspec-kit会不会让我写更多文档不会。constitution只需要写一次后面的spec、plan、tasks都是AI生成的你只需要确认对不对。反而比你反复和AI掰扯需求省时间。Q我用的Copilot/Cursor能用spec-kit吗可以。spec-kit支持30编码代理初始化的时候选对应的integration就行specify init my-project --integration copilot或者--integration cursor-agent。Q代码生成得不好怎么办直接改spec重新跑/speckit.implement。不需要手动改代码——手动改代码反而容易导致和spec不一致后面converge检查的时候会报冲突。Q团队怎么推广spec-kit先拿一个小需求试点让大家看到SDD确实能减少返工比喊口号有用。试点成功之后再推广到更大的项目循序渐进。Qspec变了之后旧代码怎么办取决于你选的持久化模型。Flow-back模式下旧代码和旧spec可以共存新spec生成新代码后逐步替换。Flow-forward模式下旧代码不动新需求在新的feature目录里独立实现。Living Spec模式下直接更新spec重新生成就行。12我的判断我之前vibe coding踩的坑够写三篇文章现在用spec-kit至少少了80%的返工。这不是因为spec-kit有多神奇是因为SDD方法论本身解决了AI编码最大的痛点——需求模糊导致AI瞎猜。spec-kit只是把这个方法论做成了可执行的工具。说真的SDD不是新概念。Power Inversionspec高于code这个哲学在我们做后端架构的时候早就有了——接口契约高于实现API文档高于代码。spec-kit只是把这个原则推到了更极端的位置spec不只是指导实现spec直接生成实现。后面我会更新怎么自己写spec-kit的extension把单元测试、代码扫描都集成到SDD流程里感兴趣关注码哥跳动别到时候找不到。要是你觉得这篇文章帮你少踩了几个坑点个「在看」让我知道也欢迎转发给身边还在被vibe coding翻车困扰的朋友。
