Context
这次改动在哪里，哪些文件已经相关，应该复用什么现有模式。
它和相邻方法的关系
Spec Coding 不是完整产品流程，也不是沉重的形式化规格系统。它是模糊聊天提示和生产 diff 之间那份小的工作文件。
| 方法 | 主要产物 | 适合场景 |
|---|---|---|
| Vibe coding | 只有聊天 | 探索、一次性脚本、原型，以及错误成本很低的尝试。 |
| spec-coding | feature.spec.md | 日常功能开发：需要对齐，但不值得写 30 页 PRD。 |
| SDD / formal spec | spec.md + design.md + tasks.md | 监管系统、多团队交付，以及写错成本很高的改动。 |
| Working Backwards | PR / FAQ | 实现前的产品框架。Spec Coding 处理它下面的一次具体功能实现。 |
| Shape Up | pitch + appetite | 周期规划和 shaping。spec 是 shaped work 内部的实现协议。 |
推荐阅读路径
第一次来可以按顺序读；已经有具体任务时，也可以直接跳到对应步骤。每一步都指向真实页面、模板或工具。
01
为什么要 spec-first？
不要从模糊工单直接跳进 AI coding agent。
02
一份 spec 的结构
上下文、目标、计划、非目标、验收标准和证据。
03
选一个模板
为下一次改动选择最小、最合适的文件。
04
把模糊需求改成 spec
看一个松散请求如何变成可评审实现契约。
05
实现前先评审
交给人或 AI 之前，先用 12 个问题检查。
06
生成 AI Coding Spec Packet
从一个需求生成 spec、任务拆解、验收标准和证据清单。
07
深入 SDD
从一个 spec 文件扩展到 spec.md、design.md、tasks.md 和 evidence.md。
AI Coding Spec Packet
复制 starter spec，或生成包含 spec.md、tasks.md、验收标准和证据清单的完整规格包。
一份 spec 的结构
有用的 spec 要足够小，小到不会打断动手势头；也要足够具体，具体到 agent 不能随便发散。
Goal
上线后用户或系统行为具体发生什么变化。
Plan
可评审的实现步骤、命名文件、依赖关系和测试命令。
Out of scope
那些诱人的重构、顺手优化和相邻需求，明确不做。
Acceptance and evidence
可观察的通过标准，以及合并前需要提供的测试、日志、截图或发布信号。
review-ready-spec.md
spec.md
## Context 现有 checkout 总价在 billing/totals.ts 中计算。 ## Goal 付款创建前应用一个有效优惠码。 ## Plan 1. 通过小 API endpoint 校验优惠码。 2. 校验后更新 checkout summary。 3. 保持 draft order 状态幂等。 ## Out of scope - 优惠码后台 UI - 多个优惠码叠加 - 无关的 totals 重构 ## Acceptance - 过期优惠码显示内联错误 - 付款金额使用折扣后总价 - 刷新后保留已选择优惠码 ## Evidence - 校验规则单元测试 - checkout total 集成测试 - 回滚开关已记录
模板库
模板用 repo 文件列表的方式展示，因为团队实际就是这样使用它们：打开、复制、修改、评审。
| 文件 | 什么时候用 | 行数 | 更新 | 操作 |
|---|---|---|---|---|
feature.spec.md |
标准功能开发：新 endpoint、新页面或新流程。 | 42 | 2026-05-15 | 打开 |
api.spec.md |
API 契约、请求响应示例、错误码和兼容规则。 | 48 | 2026-05-15 | 打开 |
database.spec.md |
Schema 变更、索引、约束、回填和回滚计划。 | 39 | 2026-05-15 | 打开 |
spec.md |
目标、非目标、验收标准、开放问题和证据要求。 | 36 | 2026-05-11 | 打开 |
design.md |
架构选择、接口、被拒绝方案、上线顺序和回滚。 | 52 | 2026-05-11 | 打开 |
tasks.md |
可评审实现切片，包含允许文件和测试命令。 | 44 | 2026-05-11 | 打开 |
evidence.md |
测试、截图、日志、指标、手工检查和发布停止信号。 | 31 | 2026-05-11 | 打开 |
复制预览区
template.md
点击上方任意“复制”按钮，这里会显示模板内容。
从模糊需求到可评审 spec
这个方法最容易被信任的方式，是直接看到前后对比。下面把一个松散产品请求拆成范围、计划、验收和证据。
Before
“给 checkout 加优惠码。无效码不要影响支付。”
After
- Context 写明 checkout、billing totals 和现有 coupon 数据。
- Goal 把行为限制为付款前应用一个优惠码。
- Out of scope 排除后台管理、叠加和 totals 重构。
- Acceptance 覆盖过期、重复使用和有效优惠码状态。
- Evidence 指名单元测试、集成测试和回滚开关。
after.spec.md
## Acceptance - 过期码显示内联错误 - 已使用码不能重复应用 - 付款金额使用折扣后总价 ## Evidence - 优惠码校验单元测试 - checkout total 集成测试 - 回滚开关已记录
常见问题
你可能最关心的几个问题。
Spec 会不会太"文档化"，拖慢节奏？
最贵的 spec 是你跳过的那份。一份短 spec 只要在代码评审前抓住一个范围歧义，就能省掉一周返工。从历史上给你造成最多生产问题的决策点开始写：验收标准、边界条件和回滚方案。
我已经用 AI 写代码了，还需要 Spec 吗？
越是用 AI，越需要 Spec。没有规格，AI 会发散：多写、多改、多加功能，最后更难收敛。Spec 是 AI 的"护栏"。
适合个人/小团队吗？
反而更适合。小团队最怕"上下文丢失"和"口头约定"，Spec 让你过一周再回来也能秒捡起来。
需求中途变了怎么办？
更新 Spec 就好。Spec 本来就是活文档，不是刻在石头上的契约。用 git 管理版本，Spec 永远反映当前的真实需求。
Spec 和 PRD 有什么区别？
PRD 从业务视角描述产品该做什么；Spec 从工程视角描述代码必须做什么——包含验收标准、边界情况和可测试的契约。两者互补，不是替代关系。
精选文章
关于 Spec-First 交付的实践长文，覆盖从需求到上线的每个环节。
SDD 工具
OpenSpec、Superpowers 和 Spec Kit
对比三个现代 SDD 参考，提炼 spec、plan、tasks、tests 和 evidence 这些可复用产物模式。