先写一份小的 spec.md
再让 agent 写代码。

Spec Coding 把模糊的 AI 编码请求变成一份短的、可评审的规格包：上下文、范围、验收标准、允许修改和合并前证据，先写清楚，再让 agent 动手。

阅读指南 浏览模板
纯 Markdown Agent 可读 编码前可评审

术语说明

很多人会用 spec-first、spec as code、code spec 或 coding spec 搜索这类方法。中文里也可以把它理解为 规范编码：先把行为、边界和证据写清，再进入实现。在本站，它们都指向同一个实用产物：一份靠近代码、实现前可评审的短 spec.md。

公开资产

不只是文章，而是可以检查的工程产物。

真正可复用的方法应该能被复制、放进仓库、挂到 PR，并随着代码一起评审。Spec Coding 把模板、案例和生成器都做成开发者能直接使用的文件形态。

GitHub spec-kit

功能、API、迁移、事故复盘和评审门禁的 Markdown 规格模板。

 GitHub openapi-spec-starter

带 lint、mock 校验、fuzz 检查和 CI 证据的 OpenAPI 起手架。

 案例库 完整规格包案例

覆盖 checkout、API 错误、数据库变更和通知偏好的前后对比。

 浏览器工具 AI 编码规格包

本地生成 proposal、spec、design、tasks、验收标准和证据清单。

问题不是 AI 会写代码，而是它会猜缺失的规格。

大多数 AI 辅助开发失败，不是因为模型不会改文件，而是提示词没有写清范围、边界、Owner 和证据。Spec Coding 把这些决策提前变成可评审文本。

01

范围漂移

Agent 顺手加相邻重构、新字段或产品行为，评审时才发现没人授权。

02

验收不可测试

PR 看起来合理，但评审者无法把 diff 对应到明确的用户可见行为。

03

证据缺失

测试、截图、日志、发布信号和回滚路径都在代码之后才临时补。

松散交接

“给 checkout 加优惠码。无效码体验做友好一点。”

规格交接
  • Context：checkout route、totals module、coupon table
  • Scope：付款前只能应用一个有效优惠码
  • Non-goals：后台 UI、叠加优惠、totals 重构
  • Evidence：校验测试、checkout 集成测试、回滚开关

它和相邻方法的关系

Spec Coding 不是完整产品流程，也不是沉重的形式化规格系统。它是模糊聊天提示和生产 diff 之间那份小的工作文件。

方法主要产物适合场景
Vibe coding只有聊天探索、一次性脚本、原型，以及错误成本很低的尝试。
spec-codingfeature.spec.md日常功能开发：需要对齐，但不值得写 30 页 PRD。
SDD / formal specspec.md + design.md + tasks.md监管系统、多团队交付，以及写错成本很高的改动。
Working BackwardsPR / FAQ实现前的产品框架。Spec Coding 处理它下面的一次具体功能实现。
Shape Uppitch + appetite周期规划和 shaping。spec 是 shaped work 内部的实现协议。

大多数返工不是代码质量问题，而是假设没有对齐。

如果十分钟能写清 spec，通常就能省掉 agent 三轮错误实现。如果写不清，说明这个功能可能还没准备好进入编码。

一次变更，一组可评审规格包

小任务用一份 spec.md 就够。风险更高的变更，需要一个小文件夹，把意图、行为、设计、任务和证据分开，让评审者能挑战正确的层级。

生成规格包 浏览规格包模板
docs/specs/checkout-coupon/
proposal.md        为什么做、影响谁
spec.md            需求、场景、非目标
design.md          决策、取舍、上线方式
tasks.md           实现切片和允许范围
test-evidence.md   合并前必须提供的证据

推荐阅读路径

第一次来可以按顺序读；已经有具体任务时，也可以直接跳到对应步骤。每一步都指向真实页面、模板或工具。

01 为什么要 spec-first？ 不要从模糊工单直接跳进 AI coding agent。 5 分钟 02 一份 spec 的结构 上下文、目标、计划、非目标、验收标准和证据。 7 分钟 03 选一个模板 为下一次改动选择最小、最合适的文件。 3 分钟 04 把模糊需求改成 spec 看一个松散请求如何变成可评审实现契约。 10 分钟 05 实现前先评审 交给人或 AI 之前，先用 12 个问题检查。 4 分钟 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、验收标准和证据清单的完整规格包。

查看案例

六条资源路径

按你眼前的任务选择入口。这里不是被动阅读站点，而是一组可以直接复制、生成、评审和交接的工程产物。

01

从这里开始

理解轻量习惯：在编码开始前，先写下能阻止返工的关键决策。

阅读路径
02

模板

复制可放进仓库的 Markdown 文件：功能、API、数据库、任务和证据。

浏览模板
03

案例

对比模糊需求和完成后的规格包，覆盖 checkout、API、迁移和通知。

查看案例
04

生成器

当你已经知道需要哪类产物时，再用浏览器工具生成规格包、Gherkin 场景、API 规格、数据库规格和复盘笔记。

使用工具
05

评审门禁

用清单和证据要求判断一次变更是否已经准备好进入实现。

阅读清单
06

AI 交接

在 Claude Code、Cursor、Codex 或其他 agent 写代码前，先给它一个窄事实来源。

阅读模式
热门起点 Claude Code spec 模板 Cursor spec 模板 Agent spec.md 模板 AI 编码验收标准 AI PR 评审清单 Vibe 与 Spec 对比

一份 spec 的结构

有用的 spec 要足够小，小到不会打断动手势头；也要足够具体，具体到 agent 不能随便发散。

01

Context

这次改动在哪里，哪些文件已经相关，应该复用什么现有模式。

02

Goal

上线后用户或系统行为具体发生什么变化。

03

Plan

可评审的实现步骤、命名文件、依赖关系和测试命令。

04

Out of scope

那些诱人的重构、顺手优化和相邻需求，明确不做。

05

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 Coding 和 spec-first、spec as code、code spec 是一回事吗？

它们有重叠。中文里可以把 Spec Coding 理解为规范编码：先把行为、边界和证据写清，再进入实现。spec-first 强调先写行为再写代码；spec as code 强调把规格放进代码仓库；code spec 和 coding spec 常被用来搜索同一类小产物：可评审、可实现的 spec.md。

精选操作指南

从让 AI 交付更可控的内容开始读：基本方法、交接规格包和编码前评审门禁。

基础概念

什么是 Spec-First 开发

从"先写代码"到"先写规格"的完整转变：为什么这样做能减少返工，如何让 AI 编码更可控。

阅读文章
AI 编码

AI 编码前的规格包

先写清任务边界、允许修改的文件、验收标准和测试证据，再让 AI 开始生成代码。

阅读文章
评审

编码前的 Spec 评审清单

用十二个问题检查范围、非目标、验收标准、边界情况、允许文件、测试证据和上线停止信号。

阅读清单
浏览全部文章

准备评审一份更好的 spec 吗？

先读指南、复制模板，再用案例对照你的草稿，最后再让 agent 按清晰范围、验收标准和证据要求写代码。

浏览模板 查看案例