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

先说说一个真实场景。你用 Cursor 写用户权限模块，Vibe Coding 了三个小时，代码跑起来才发现角色继承逻辑搞反了——明明指定了 RBAC0，AI 却写成了 RBAC1 的继承方向。改到第五版，AI 已经彻底忘了最开始提的「不支持动态角色」这个约束。

这种翻车经历，我见过太多。直到上个月试了 GitHub 官方出的 spec-kit，才终于不用在 AI 的「自由发挥」和我的「反复返工」之间来回拉扯。

为什么要搞清楚这件事？

很多人听到 SDD（Spec-Driven Development），第一反应是「先写文档再写代码」的老古董，这其实是个误解。

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 分钟）

第 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 流程里。

参考资料

1. spec-kit 官方仓库：github.com/github/spec…
2. GitHub 官方博客：Spec-driven development with AI：github.blog/ai-and-ml/g…
3. GitHub 博客：Using Markdown as a programming language：github.blog/ai-and-ml/g…
4. Martin Fowler：Exploring SDD tools：martinfowler.com/articles/ex…