spec-kit实战：我用SDD方法论解决AI编码幻觉问题

不知道你有没有遇到过哲宏场景：使用 Cursor 写用户权限模块，vibe coding了3小时，代码跑起来才发现AI把角色继承的逻辑搞反了------我明明说过要RBAC0，它写成了RBAC1的继承方向。改到第5版的时候，AI已经忘了我最开始提的「不支持动态角色」的约束。

这种破事我起码遇到过十次。直到上个月试了GitHub官方出的spec-kit，才终于不用在AI的「自由发挥」和我的「反复返工」之间反复横跳。

为什么要搞清楚这件事？

很多人觉得SDD就是「先写文档再写代码」的老古董，这完全是误解。

SDD的核心是把spec从静态文档变成可执行合约，代码是spec的衍生品，而不是反过来让文档服务代码。这跟传统的「需求文档」有根本区别，需求文档写完就扔，spec写完之后是持续驱动的------每次改需求先改spec，再让AI根据spec重新生成代码。

我用vibe coding的时候，提需求全靠嘴，AI理解对了对我有利，理解错了我背锅。SDD的逻辑是反过来，我先花20分钟把需求、约束、验收标准写清楚，AI必须按照这个来生成代码，跑不通是AI的问题，不是我需求没说清。

维度	vibe coding	SDD（spec-kit）
需求表达	口头描述，每次可能不一致	spec文件，需求写入后AI每次都读
AI理解偏差	你说不清，AI瞎猜，翻车率高	spec精确+验收标准，翻车率低
需求变更	改了之后AI可能忘了之前的约束	改spec后重新生成，AI自动跟踪
返工成本	高，经常改到第5版还在改	低，改spec重跑一次implement
代码一致性	随着迭代越来越散	代码始终跟spec保持一致

spec-kit就是把这个逻辑做成通用工具链的产品，不是某一个AI编码工具的附属品------它现在支持Claude Code、Cursor、Copilot、Gemini CLI等30+编码代理，GitHub官方维护，截至2026-06-25已经有115,317 个star，最新版本是v0.11.8（2026-06-24更新），活跃度完全不用担心。

它是怎么工作的？

spec-kit的核心工作流是5步，每一步都有明确的输入、输出和验收标准。你可以跳过某些步骤，但代价是后面更容易翻车。

第1步：写项目宪法（/speckit.constitution）

这个步骤是定项目的「根本大法」。所有后续的spec、plan、代码都必须遵守这个文件里的规则。就像国家宪法高于所有法律，constitution高于所有spec。

我拿一个待办事项REST API做例子。执行命令：

/speckit.constitution

AI会问你几个问题，比如用什么语言、什么框架、代码规范是什么。我的回答是：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.plan

AI会根据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`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

第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.implement，AI会自动更新对应的代码。

这里有个设计哲学值得琢磨。 spec-kit把「做什么」和「怎么做」彻底分离了。spec只管意图，plan只管技术路径，代码只是两者的最终表达。这意味着你可以随时换技术栈------只要改plan里的技术选择，重新implement就行，spec完全不用动。GitHub官方博客的作者Tomas Vesely甚至尝试过把一个Go项目的spec直接编译成另一个语言，代码全部扔掉重新生成。

动手接入：从安装到第一次实现（10分钟）

本文环境： macOS / specify-cli v0.11.8 / Claude Code / Python 3.10+ / uv

第1步：安装specify CLI

# 用uv安装指定版本
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.11.8

# 验证安装
specify --version

✅ 验证：输出 specify-cli v0.11.8 即安装成功

第2步：初始化项目

# 创建项目，指定集成Claude Code
specify init todo-api --integration claude
cd todo-api

✅ 验证：项目目录下出现 .specify/ 目录，里面包含 constitution.md 模板和 templates/ 子目录

如果你用其他工具，初始化的时候换integration就行：

# Cursor用户
specify init todo-api --integration cursor-agent

# Copilot用户
specify init todo-api --integration copilot

# 查看所有支持的integration
specify integration list

第3步：走完5步核心流程

依次执行：

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement

✅ 验证：每个步骤完成后检查 .specify/specs/ 目录下对应的 .md 文件是否生成

常见报错与解决

报错1：uv tool install 失败，提示 Python 版本不兼容

原因：specify-cli 要求 Python 3.10+，如果你的系统Python版本低于3.10会报这个错。解决：

# 用uv自带的Python
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.11.8 --python 3.12

报错2：/speckit.constitution 执行后AI没有生成constitution.md

原因：spec-kit是通过slash command和AI编码代理交互的，如果你的代理版本太旧可能不支持slash command。解决：升级你的AI编码代理到最新版本，或者检查 .claude/commands/ 目录下是否有speckit相关的命令文件。

和Superpowers SDD的延续性：从内部机制到通用工具

写过我之前那篇「Superpowers v6.0 SDD重写深度拆解」的朋友应该记得，Superpowers的核心设计是Do Not Trust the Report------不信任subagent的自我汇报，必须通过diff验证结果。

spec-kit其实是把Superpowers内部的SDD方法论抽出来做成了通用工具，核心逻辑完全一致：

Superpowers（Skill内部）	spec-kit（通用工具链）
subagent生成spec	/speckit.specify生成spec
subagent验证结果（diff check）	/speckit.converge验证代码和spec一致性
Do Not Trust the Report原则	clarify步骤确保spec无歧义
只能在Claude Code里用	支持30+编码代理

核心哲学都是Power Inversion------spec是老大，代码必须服从spec。在Superpowers里，这是通过subagent的内部架构实现的，普通人看不到也用不了。在spec-kit里，同样的哲学变成了任何人都能执行的slash command。

区别不是方法论不同，是可触达性 不同。Superpowers是「SDD在Skill内部的工程实践」，spec-kit是「SDD作为通用开发流程对外开放」。前者需要你装特定Skill，后者只需要一个uv tool install。

3种spec持久化模型：不同团队怎么选

这部分是很多介绍spec-kit的文章都没讲到的，我特意翻了官方的docs/concepts/spec-persistence.md，整理了三种模型的适用场景。

模型	核心逻辑	适用场景	主要风险
Flow-back Spec	各artifact可以互相影响，改了代码可以反过来更新spec	小团队（<5人）快速迭代	静默漂移，代码改了spec没更
Flow-forward Spec	已完成artifact视为不可变，改需求就新建feature目录	需要审计的场景（金融、医疗）	大量重复artifact，维护成本高
Living Spec	spec.md是唯一合约，plan和tasks是可丢弃的衍生品	产品合约稳定，需求变动少的场景	需求频繁变动时需频繁更新spec

说实话，这三种模型不是spec-kit发明的。Martin Fowler在分析SDD工具的时候就提过类似的分类：Spec-first（先写spec然后可以扔掉）、Spec-anchored（spec写完保留，后续变更参照）、Spec-as-source（spec是唯一源，代码是衍生品）。spec-kit只是把这些策略变成了可选择的配置。

我个人的建议：10人以下的团队直接用Flow-back，灵活度高，每周做一次/speckit.converge检查一致性就够。金融类的团队必须用Flow-forward，审计的时候能追溯到每一次需求变更。Living Spec适合产品已经稳定、只需要维护和少量迭代的项目------比如你公司内部的管理后台，需求一年改不了几次。

Extensions和Presets系统：自定义你的SDD流程

spec-kit支持扩展，你可以自己加命令、加hook，也可以自定义模板。优先级从高到低：

1. Project-Local Overrides （.specify/templates/overrides/）------单项目调整，不改全局
2. Presets------自定义核心模板和术语，比如把默认的MIT协议改成你公司的内部协议
3. Extensions------添加新命令、hook、capabilities，比如在implement之后自动跑代码扫描
4. Core------spec-kit核心默认模板

模板解析是运行时的------spec-kit从上往下找，第一个匹配的就用。这意味着你可以在不改核心代码的情况下，几乎完全定制SDD流程。

比如你可以写一个test扩展，在/speckit.implement完成之后自动跑单元测试。也可以自定义preset，把默认生成的spec模板改成你团队习惯的格式。社区已经有人贡献了一些扩展和preset，可以在spec-kit官方文档的Community页面找到。

踩坑实录：不要跳过clarify步骤

我第一次用的时候觉得自己的需求写得够清楚了，跳过了/speckit.clarify步骤，结果plan的时候AI默认给待办删除做了软删除，而我们的需求是硬删除。后面改的时候要改spec、plan、tasks三个文件，花了将近1小时。

后来我每篇spec都跑一遍clarify，哪怕需求只有3句话。AI会列出你可能没想到的边界条件：空值怎么处理、并发冲突怎么解决、异常情况返回什么状态码。这些点如果不提前确认，implement的时候就全靠AI自己猜，猜错了你又要返工。

还有一个坑：constitution里如果只写「用Go」，不写具体框架，AI可能选标准库net/http而不是Gin。所以constitution尽量写具体，技术栈、框架版本、代码规范、禁止项，一个都别漏。

什么时候用spec-kit，什么时候别用

适合用的场景：

• 新项目从0到1，需求还没完全想清楚------先写spec帮你理清思路
• 给现有系统加新功能------spec能确保新代码和现有架构一致
• 团队协作，需求变更频繁------spec是共享的真相源，每个人看到的都一样
• 用AI编码代理写代码，经常因为需求理解偏差返工------SDD能大幅减少返工

不适合的场景：

• 一次性脚本、临时工具------写spec的时间比写代码还长
• 需求已经100%明确且不会变------直接写代码更快
• 你不用AI编码代理------spec-kit的价值在于让AI按照spec生成代码，如果你全程手动写，spec只是额外负担

常见问题

Q：spec-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确实能减少返工，比喊口号有用。试点成功之后再推广到更大的项目，循序渐进。

Q：spec变了之后旧代码怎么办？

取决于你选的持久化模型。Flow-back模式下旧代码和旧spec可以共存，新spec生成新代码后逐步替换。Flow-forward模式下旧代码不动，新需求在新的feature目录里独立实现。Living Spec模式下直接更新spec重新生成就行。

我的判断

我之前vibe coding踩的坑够写三篇文章，现在用spec-kit至少少了80%的返工。这不是因为spec-kit有多神奇，是因为SDD方法论本身解决了AI编码最大的痛点------需求模糊导致AI瞎猜。spec-kit只是把这个方法论做成了可执行的工具。

说真的，SDD不是新概念。Power Inversion（spec高于code）这个哲学，在我们做后端架构的时候早就有了------接口契约高于实现，API文档高于代码。spec-kit只是把这个原则推到了更极端的位置：spec不只是指导实现，spec直接生成实现。

后面我会更新怎么自己写spec-kit的extension，把单元测试、代码扫描都集成到SDD流程里，感兴趣关注码哥跳动，别到时候找不到。要是你觉得这篇文章帮你少踩了几个坑，点个「在看」让我知道，也欢迎转发给身边还在被vibe coding翻车困扰的朋友。

参考资料

1. spec-kit官方仓库：https://github.com/github/spec-kit
2. GitHub官方博客：Spec-driven development with AI：https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
3. GitHub博客：Using Markdown as a programming language：https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
4. 码哥跳动：Superpowers v6.0 SDD重写深度拆解
5. Martin Fowler：Exploring SDD tools：https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html