仓库优先的方法

Spec as Code 主题 Hub

Spec as Code 的核心是：决策产物和实现代码放在同一条评审路径里。一份短 spec.md 进入仓库，编码前先评审，PR 中持续引用，行为改变时同步更新。

生成规格 打开功能模板

最近更新：2026-05-19

Spec as Code 解决什么

很多交付偏差不是因为工程师写代码能力差，而是需求、实现和证据散落在不同位置。产品备注在工单里，真正决策发生在聊天里，PR 只展示代码，QA 只能从 diff 里反推行为。Spec as Code 把那份小而关键的决策记录放进和代码相同的评审路径。

它不是要求每个功能都写成长设计文档，而是在大 diff 出现之前，把会影响实现、测试和上线的行为暴露出来。评审者能在同一个 PR 中看到规格、边界、测试和上线证据，团队讨论的就不再是记忆，而是一份可追踪的契约。

对 AI 编码尤其重要的是，规格不会随着聊天窗口结束而消失。下一次修 bug、回滚或追加需求时，团队仍然能回到同一份文件，看到当时为什么这么做、哪些范围被排除、合并前看过哪些证据。

Spec as Code 与相关术语

术语更准确的含义本站建议动作
Spec-First Development先决定行为、范围和验收，再进入实现。需要完整方法时打开 Spec-First Hub。
Spec as Code把规格放进仓库，像代码一样版本化和评审。需要文件结构、评审规则和证据链接时使用本页。
Code Spec很多用户搜索“小型实现规格”时会用的词。写一份短 spec.md，说明受影响文件、接口和测试。
Coding Spec面向实现动作的实用规格。从验收标准、允许范围、边界情况和合并前证据开始。
SDD规格驱动开发：规格、计划、任务、测试和证据组成的流程。需要多步骤交付和 AI 编码治理时打开 SDD Hub。

仓库结构

repo layout可复制
/specs
  /checkout-coupon
    feature.spec.md
    acceptance.md
    evidence.md
    decisions.md

/src
  /checkout
    coupon-service.ts
    coupon-service.test.ts

/docs
  release-notes.md

靠近代码，但不要被埋掉

一个好的位置应该容易从工单和 PR 里链接。可以把规格放进固定的 /specs 目录，也可以放在它约束的模块旁边。不要把唯一副本留在聊天、私有文档或一次性的 AI prompt 里。

  • 使用稳定文件名，例如 feature.spec.md 或 api-contract.spec.md。
  • 从 issue、PR、release note 和测试证据里链接同一份规格。
  • 如果取舍以后还会被重新讨论，把被拒绝方案记录进 decisions.md。

评审流程

01

起草

写清目标、非目标、验收标准、受影响接口和证据要求。

02

评审

让产品、工程、QA 和运维在编码前拒绝模糊范围。

03

实现

把 diff 控制在已批准范围内；行为变化时同步更新规格。

04

证明

合并或发布前附上测试、日志、放量说明和回滚信号。

证据矩阵

变更类型最小规格内容合并前证据
功能行为目标、非目标、验收标准、边界情况单元测试、集成测试、视觉或流程场景的 QA 记录
API 契约请求、响应、错误、兼容性、迁移计划OpenAPI diff、消费者测试、重试和超时覆盖
数据库变更模式意图、迁移顺序、回滚、数据安全规则迁移 dry run、回填指标、回滚演练记录
AI 生成代码允许文件、prompt 边界、验收标准、风险等级文件变更映射、测试命令、评审记录、证据日志
发布流程责任人、放量阈值、停止信号、回滚责任人看板链接、日志查询、发布清单、事故兜底动作

常见错误

  • 规格虽然进了仓库，但没有成为评审门禁。
  • 只写叙述性说明，没有可测试的验收标准。
  • 实现发生偏移，却没有在同一个 PR 里更新规格。
  • 只把规格当作 prompt，AI 会话结束后丢失真正的事实来源。
  • 声称变更完成，却没有链接测试、日志、指标或上线证据。

推荐资源

生成规格包

把粗略需求转成规格、任务拆解、验收标准和证据清单。

打开工具

浏览规格模板

使用功能、API、数据库、证据日志和 AI 编码评审模板。

打开模板

对比 SDD 参考

参考 OpenSpec、Superpowers 和 Spec Kit 的现代规格驱动交付模式。

阅读对比

编码前评审

在大 diff 开始前检查规格是否足够具体、可测试、可上线。

使用清单

看真实前后对比

看一个模糊需求如何变成可评审的规格包和验收证据。

打开案例

理解 Spec-First

当团队需要的不只是文件格式，而是一套共同交付方法时，从这里开始。

打开 Hub

常见问题

Spec as Code 是什么意思？

Spec as Code 指规格和代码放在同一个工程上下文里，通常是仓库中的 markdown 文件，在实现前通过 git 或 PR 评审。它有版本、有链接，并且行为变化时同步更新。

Spec as Code 和 Spec-First 是一回事吗？

两者有重叠但不完全相同。Spec-First 强调先决定行为再编码；Spec as Code 强调规格放在哪里、如何版本化、如何被评审，以及如何连接证据。

代码规格里应该写什么？

有用的代码规格应该包括目标、非目标、验收标准、受影响文件或接口、边界情况、测试、上线说明和合并前证据。

小团队也需要 Spec as Code 吗？

当变更有风险或容易误解时需要。最小可用版本就是一个 spec.md，链接到工单和 PR。

它如何帮助 AI 编码？

AI 编码更需要明确边界：允许修改哪些文件、验收标准是什么、需要什么测试和证据。Spec as Code 把这些约束放在可评审的位置，而不是只留在聊天记录里。

当用户搜索 code spec 或 coding spec，本质上通常是在找一份短小、可评审、能指导实现的 spec.md。

生成规格 浏览模板