让 AI agent 直接动手写代码，是当下最常见的翻车现场：你说一句「给网站加个搜索功能」，agent 一口气吐出八百行代码，一跑发现它假设你用 Algolia、实际你用的是 Postgres 全文索引；你说「把仪表盘搞快点」，agent 上来就加缓存层，结果真正的瓶颈是首屏查询太慢。需求理解歪了，代码再漂亮也得推倒重来。根因不在 agent 笨，在动手前没把三件事想清楚：做什么、怎么做、做到什么程度算完。
spec 驱动开发（spec-driven development）就是治这个病的工程纪律：在写一行代码之前，先把需求落成一份 spec（规格说明）——讲清问题是什么、目标是什么、边界在哪、做到什么程度算验收通过——再由 AI 或人照着 spec 一步步实现。这套方法不是新概念，它是被 GitHub、Google 等团队反复验证的「写代码前先写规格」的工程实践。这篇 SOP 走一遍完整流程：写 spec、分块确认、生成实现计划、拆任务、逐任务实现并验证、对照 spec 验收收尾。每步带可复用的模板和示例，最后是踩坑记录和常见问题。
一、核心：动手前先写 spec，四道闸门逐道过
spec 驱动开发的骨架是四道带人工审核闸门的阶段，每道闸门没过就不许进下一道：
SPECIFY ──> PLAN ──> TASKS ──> IMPLEMENT
│ │ │ │
▼ ▼ ▼ ▼
人工审核 人工审核 人工审核 人工审核- SPECIFY（写规格）：把模糊想法落成结构化 spec，讲清问题、目标、边界、验收标准。
- PLAN（做计划）：照 spec 拆出技术实现计划，定组件、依赖、先后顺序。
- TASKS（拆任务）：把计划拆成一个个能在单次专注时段内做完的小任务，每个带验收和验证步骤。
- IMPLEMENT（实现）：逐个任务执行，每个任务做完即验证。
为什么要设四道闸门而不是一道？因为需求理解错误越早发现成本越低——spec 阶段改一句话，比代码写完再推倒重来便宜两个数量级。每道闸门都强制人过一眼，把「AI 自由发挥」的窗口压到最小。
二、第一步：写 spec
spec 不是说明书，是「在写代码前强迫你把需求想清楚」的工具。一份合格的 spec 至少覆盖五块：问题陈述、用户故事、功能边界、非目标、验收标准。
先亮明假设。 写 spec 正文前，把你在默默假设的东西摆上台面：
我在做的假设：
1. 这是一个 Web 应用（不是原生 App）
2. 鉴权用 session cookie（不是 JWT）
3. 数据库是 PostgreSQL（依据现有 Prisma schema）
4. 只兼容现代浏览器
-> 有错现在纠正，否则我按这些往下走。为什么这一步关键？因为假设是需求误解里最危险的一种——它不出声地填了需求的空白，等代码写完才暴露。亮明假设等于给「我猜你想要 X」一个被当场否决的机会。
spec 模板。 下面是一个可直接套用的模板，以「给内容站加全文搜索」为例：
# Spec: 站内全文搜索
## 问题陈述
用户目前只能靠分类和标签翻文章，找不到「半年前那篇讲 RAG 评估的」。
站内无搜索，流失率高，老内容触达低。
## 用户故事
- 作为读者，我想输入关键词搜到相关文章，按相关度排序
- 作为编辑，我想看到搜索热词，知道读者在找什么
## 功能边界（做什么）
- 对已发布文章的标题、摘要、正文做全文检索
- 支持中文分词
- 结果按相关度排序，高亮命中词
- 搜索无结果时返回推荐文章
## 非目标（明确不做什么）
- 不做个性化推荐排序
- 不做跨站搜索
- 不做图片/视频内容搜索
- 不做实时索引（索引延迟可接受到分钟级）
## 验收标准
- 输入「RAG 评估」能返回相关文章，首条相关
- 中文分词正确，不把「评估」切成「评」和「估」
- 搜索响应 P95 < 300ms
- 无结果时显示推荐列表，不显示空白页
- 搜索框在移动端可用注意「非目标」这一块——它和「功能边界」同样重要。非目标的作用是给 agent 划红线：这些事明确不做，别自由发挥加进去。很多 agent 翻车不是因为少做了什么，而是多做了一堆你没要的东西。
把模糊需求重述成可验收条件。 拿到「把仪表盘搞快点」这种话，别直接开干，先翻译成具体可测的条件：
原始需求：「把仪表盘搞快点」
重述为验收标准：
- 4G 网络下仪表盘 LCP < 2.5s
- 初始数据加载 < 500ms
- 加载过程无布局偏移（CLS < 0.1）
-> 这些目标对吗？这一步让你能对着一个清晰目标去迭代，而不是猜「快点」到底是什么意思。
三、第二步：分块确认
spec 写完别一次性甩给人拍板。一份覆盖五块的 spec 信息量大，人一口气读完容易走眼，关键的边界和非目标常被扫过去。正确做法是分块逐段确认：
1. 先确认「问题陈述 + 用户故事」——对齐「我们在解决什么问题」
2. 再确认「功能边界 + 非目标」——对齐「做什么、不做什么」
3. 最后确认「验收标准」——对齐「怎么算做完」每块确认完再进下一块。这比一次大 spec 直接拍板好在哪？它把误解掐死在最小范围——如果「问题陈述」就理解歪了，后面三块写得再细也白搭。分块确认等于在 spec 内部又设了一层闸门。
实操上，你可以让 agent 每写完一块就停下来问「这块对吗？有补充吗」，确认后再写下一段。这比 agent 一口气写完整份 spec 再让你审，反馈回路短得多，返工成本也低。
四、第三步：生成实现计划
spec 定稿后，照着它拆技术实现计划。计划要回答四个问题：
- 有哪些主要组件，彼此依赖什么（如：索引服务、搜索 API、前端搜索框、结果页）
- 实现顺序（什么必须先建——比如得先有索引才能测搜索 API）
- 哪些能并行，哪些必须串行
- 阶段间的验证检查点
计划应该是「人能读得懂、读得出对错」的——人扫一眼能说「对，就这么干」或「不对，改 X」。计划不是代码，别在这一步写实现细节。
照上面的搜索 spec，计划大概长这样：
实现计划：站内全文搜索
组件：
- 索引服务：读取已发布文章，建全文索引
- 搜索 API：接前端查询，查索引返回结果
- 前端搜索框 + 结果页：输入、展示、高亮
依赖与顺序：
1. 先建索引服务（搜索 API 依赖索引存在）
2. 再建搜索 API（前端依赖 API 返回）
3. 最后做前端（接 API）
并行机会：
- 索引服务和前端搜索框 UI 可并行（UI 先 mock 数据）
验证检查点：
- 索引建完：手动查一条已知文章，确认能搜到
- API 通：curl 查「RAG」返回 JSON
- 端到端：前端输入，看到高亮结果五、第四步：拆任务
把计划拆成一个个能在单次专注时段（通常一两小时）内做完的小任务。拆任务有三条硬规矩：
- 每个任务有明确的验收条件（做完时什么为真）
- 每个任务带验证步骤（怎么确认做完——测试命令、构建、手动检查）
- 单个任务改动不超过约 5 个文件，否则说明拆得太大
任务模板：
- [ ] 任务：搭建文章索引服务
- 验收：已发布文章标题、摘要、正文进入索引，中文分词正确
- 验证：查「RAG 评估」能命中文档，分词不切「评估」
- 文件：src/lib/search/indexer.ts, src/lib/search/indexer.test.ts
- [ ] 任务：实现搜索 API 端点
- 验收：GET /api/search?q= 返回按相关度排序的 JSON
- 验证：curl localhost:3000/api/search?q=RAG 返回非空数组
- 文件：src/app/api/search/route.ts, src/app/api/search/route.test.ts
- [ ] 任务：前端搜索框 + 结果页
- 验收：输入关键词展示结果，命中词高亮，移动端可用
- 验证：浏览器手动查 + 移动端视口检查
- 文件：src/components/search-box.tsx, src/app/search/page.tsx任务按依赖排序，不按「看起来重不重要」排序。每个任务的「文件」字段提前定好，等于又一次约束 agent 的改动范围——它只能动这几个文件，不会顺手重构半个仓库。
六、第五步：实现与验证
逐个任务执行，每做完一个立刻验证，不要攒着一波验证。这一步可以上测试驱动（TDD）：先写测试定义预期行为，再写实现让测试过。TDD 和 spec 驱动天然契合——spec 里的验收标准直接翻译成测试用例。
任务执行循环：
1. 读 spec 里这个任务相关的段落（别把整份 spec 全塞给 agent）
2. 先写测试（红）
3. 写实现让测试过（绿）
4. 跑全量测试 + 构建，确认没破坏别的
5. 标记任务完成，进下一个关键细节：按需加载 spec。一份大 spec 全塞给 agent，上下文一长它就开始丢细节。每个任务只需要 spec 里跟它相关的那一段，加载这一段就够了——这比把整份 spec 拍 agent 脸上效果好得多。
实现阶段如果发现 spec 有遗漏或新决策（比如发现数据模型得改），规矩是：先改 spec，再改代码，而不是直接改代码把 spec 晾成废纸。spec 是活文档，不是写完就锁死的遗物。
七、第六步：对照 spec 验收收尾
所有任务跑完不等于完事。最后一步是照 spec 的验收标准逐条核对：
验收核对（对照 spec）：
- [ ] 输入「RAG 评估」返回相关文章，首条相关 —— 通过
- [ ] 中文分词正确 —— 通过
- [ ] 搜索响应 P95 < 300ms —— 实测 180ms，通过
- [ ] 无结果时显示推荐列表 —— 通过
- [ ] 移动端可用 —— 通过任何一条没过，就不是「做完了」，是「还差一项」。这一步的价值在于把「我觉得做完了」变成「验收标准说做完了」——后者是可证伪的，前者不是。
收尾时还有两件小事：把 spec 提交进版本控制（spec 和代码同仓，不是另开个文档站），在 PR 里回链 spec 对应的段落。这样三个月后有人接手，能顺着 spec 理解当初为什么这么设计，而不是去猜代码里的隐含意图。
八、工具：spec-kit 与 /spec agent-skill
这套流程不用工具也能跑，但脚手架能省不少事。
github/spec-kit 是 GitHub 官方开源的 spec 生成脚手架，它把 SPECIFY → PLAN → TASKS → IMPLEMENT 这套带人工闸门的工作流固化成了可运行的命令——你给它一个模糊想法，它引导你逐段把 spec、计划、任务清单生成出来，每一步都停下等人确认。如果你想深入了解 spec-kit 本身是什么、怎么装，本站有配套的 spec-kit-resource 一文专门讲它。（两篇成对：那篇讲「是什么」，这篇讲「怎么用」。）
本站内嵌的 /spec agent-skill。如果你用 Claude Code 这类支持 agent skill 的工具，本仓库内嵌了一个 /spec 技能，它是同一套 spec 驱动方法论的本地化实现——触发后它会走 SPECIFY → PLAN → TASKS → IMPLEMENT 四阶段，每阶段结束停下等你审核。日常立项、做新功能时直接调 /spec 就能跑这套流程，不用额外装工具。
两者关系：spec-kit 是通用脚手架（任何项目能用），/spec agent-skill 是针对本仓库工作流裁剪过的内嵌版本，方法论一致，挑顺手的用。
九、踩坑记录
坑一：spec 写太粗，agent 自由发挥。 spec 只写一句「加搜索功能」，没边界、没非目标、没验收标准。agent 默认给你塞 Algolia 集成、个性化推荐、搜索分析后台——你只要一个 Postgres 全文索引。spec 的价值在细节里，粗 spec 等于没 spec。
坑二：spec 写太细，沦为写代码。 另一个极端：spec 里直接写函数签名、循环逻辑、变量名。这不叫 spec，叫用自然语言写代码。spec 应该停在「做什么、做到什么程度」，不碰「怎么实现」——后者是计划和代码的事。判断标准：spec 里出现具体代码实现就过界了。
坑三：不验收。 任务跑完直接交付，没人对照验收标准核对。结果搜索能跑但响应要 3 秒、中文分词是乱的、移动端按钮挤一块——验收标准白写了。验收不是走形式，是 spec 闭环的最后一环，缺了它前面全白干。
坑四：spec 写完不更新，变成僵尸文档。 实现中途改了方案（比如从 Algolia 换成 Postgres 全文索引），代码改了 spec 没改。三个月后新人照 spec 理解，和实际代码对不上，spec 反而成误导。spec 是活文档，决策一变先改 spec 再改代码。
坑五：把 spec 当事后文档。 代码写完了再补一份 spec 存档。这叫文档，不叫规格。spec 的全部价值在「写代码前强迫你想清楚」——事后补的 spec 失去了这个作用，只是给既成事实写说明。先 spec 后代码，顺序不能反。
十、常见问题 FAQ
Q1：spec 和 PRD 有什么区别？ PRD（产品需求文档）面向产品和业务，讲市场、用户画像、商业目标，篇幅长、面向人。spec 面向工程实现，讲问题、边界、验收标准，篇幅短、面向 AI/工程师照着实现。一个功能可能从 PRD 里摘出一段，落成一份 spec 再开干。简单说：PRD 决定「做不做、为什么做」，spec 决定「做成什么样算完」。
Q2：小项目也要写 spec 吗？ 看复杂度不看规模。改个文案、修个 typo 不用 spec。但只要需求有一点模糊、要动多个文件、要做架构决策，就值得写——哪怕只是两三行的验收标准。判断标准：这个任务会不会因为「理解歪了」而返工？会，就写 spec。一份 15 分钟的 spec 能挡掉几小时的返工。
Q3：spec-kit 怎么和这套流程配合？
spec-kit 就是这套流程的脚手架——它的命令对应 SPECIFY、PLAN、TASKS 阶段，引导你把 spec、计划、任务清单逐段生成并确认。你不用自己记模板，spec-kit 把模板和闸门逻辑固化好了。本站的 spec-kit-resource 专门讲它怎么装怎么跑。如果不想装额外工具，本仓库的 /spec agent-skill 是同一套方法论的本地实现。
Q4：spec 该 AI 写还是人写？ 最好是「AI 起草、人审核」。AI 擅长按模板快速产出结构化初稿，但需求里的业务判断、优先级取舍、非目标界定这些得人拍板。实操上：你给 AI 一个模糊想法，它产出 spec 初稿并亮明假设，你逐块确认或纠正，它改。这样 spec 的「想清楚」是人和 AI 一起完成的，不是单方甩锅。
Q5：怎么验收才算到位？ 照 spec 里的验收标准逐条核对，每条给出「通过/未通过」加证据（测试结果、实测数据、手动检查记录）。验收标准必须是可测的——「搜索要快」没法验收，「P95 < 300ms」能验收。如果发现某条标准没法客观判定过没过，说明这条标准写得太虚，下次 spec 阶段就该重述成可测条件。
参考来源
- GitHub spec-kit 仓库 - github/spec-kit（spec 驱动开发脚手架）
- 本仓库内嵌
/specagent-skill（agent-skills/skills/spec-driven-development/SKILL.md），即 spec 驱动开发方法论的项目本地化实现，四阶段 SPECIFY -> PLAN -> TASKS -> IMPLEMENT 工作流据此落地