直接回答

Spec Coding 是面向 AI 辅助开发的“需求到证据”工程方法。团队在实现前定义范围、规范性行为、约束、非目标、风险和验收证据；人或 Agent 再生成代码，最后由独立门禁判断实现是否符合规格。

Spec 不是加长版 Prompt、自动生成的任务清单或质量证明。它是一份可版本化、其主张能够被证伪的变更契约。

Spec Coding 不是重新发明需求工程

它的稳定基础早于生成式 AI。ISO/IEC/IEEE 29148 定义了系统与软件全生命周期中的需求工程过程和信息项；RFC 2119 与 RFC 8174 定义了 MUST、SHOULD、MAY 等规范性词语。行为规格、契约式设计、API First、模型驱动工程与验收测试都在连接意图和验证。

AI 改变的是成本结构，而不是工程规律。当 Coding Agent 能从几句话生成大范围 Diff 时，缺失假设会更快扩散。Spec Coding 是把既有需求、追踪和验证实践适配到“生成便宜、评审注意力稀缺”的执行环境。

常见说法 准确边界
“Spec 替代代码” 代码决定已部署行为，Spec 定义预期行为
“AI 从 Spec 派生正确代码” AI 提出实现，证据判断是否符合
“Spec 消除歧义” 审查暴露并减少歧义，无法消除未知
“一份文档是真相” 应按决策类型声明权威来源
“越详细越好” 只有约束决策或验证的细节才有价值

规格是一份决策契约

有效的规格会在实现前分配关键决策。

契约字段 它回答的问题
Owner 与状态 谁可以批准或修改？
背景与问题 哪个已观察条件证明需要变化？
目标与结果 哪个用户或系统结果必须改变？
范围 包含哪些组件、角色和状态？
非目标 哪些相邻改动明确不在本次范围？
规范性需求 哪些行为 MUST、SHOULD 或 MAY 发生？
场景 在哪些前置条件、事件和状态下发生？
接口与数据 哪些 Schema、兼容性和迁移规则适用？
质量属性 安全、时延、可靠性、隐私和无障碍有什么上限？
证据 什么能独立证明每条需求？
发布与回滚 如何限制暴露并撤销？
flowchart LR A["已观察问题"] --> B["经过审查的规格"] B --> C["设计决策"] C --> D["实施任务"] D --> E["代码与配置"] E --> F["验证证据"] F --> G{"符合规格？"} G -- 否 --> B G -- 是 --> H["受控发布"]

契约还应区分事实、决定、假设和开放问题。把未核验假设伪装成需求，是 Agent 自信实现错误系统的最短路径之一。

编写能够失败的需求

只有当评审者可以判断是否满足时，一条需求才有工程价值。

text 
REQ-REFUND-001（MUST）
Given 已认证的客服操作员
And 订单属于操作员所在租户
When 操作员提交退款草稿
Then 服务不得创建任何资金交易
And 记录订单 ID、操作员 ID、策略版本和幂等键。

证据：
- 契约测试：refund-draft-authority
- 集成测试：no-payment-side-effect
- 审计断言：required-fields-present

不要使用无法测量的形容词：“快速”“安全”“友好”“健壮”“可扩展”只有在规格给出工作负载、威胁、阈值、失败模式或评测程序后才是要求。RFC 2119 也明确提醒，规范性词语应谨慎用于互操作或限制潜在伤害，而非表达风格偏好。

分离需求、设计、任务与证据

这些制品回答不同问题，不能静默覆盖彼此。

制品 负责 不应冒充
需求 可观察行为与约束 文件级实现方式
设计 架构与已选权衡 业务批准
任务 工作拆分与依赖 正确性证明
测试或评审结果 某条需求的证据 需求意图
Release Manifest 精确部署版本和回滚 产品决策理由

任务完成只证明工作被执行过。生成测试只有在评审者确认断言与需求对应后才构成证据。Agent 勾完所有任务，也不能证明已部署结果符合规格。

建立双向需求追踪

追踪让团队既能从需求走到证据，也能从代码改动反查被授权的意图。

flowchart LR R["需求 ID"] --> S["场景"] R --> D["设计决定"] R --> T["实施任务"] T --> C["代码改动"] R --> E["验证证据"] C --> E E --> M["发布清单"]

对于重要变更，维护一张小型矩阵：

需求 设计 代码 / 配置 证据 结果
REQ-REFUND-001 ADR-014 refund-draft 服务 契约 + 集成测试 通过
REQ-REFUND-002 ADR-014 策略网关 授权测试 通过
REQ-REFUND-003 ADR-021 审计发送器 Schema + 保留审查 阻塞

正向追踪能发现没有实现或证据的需求；反向追踪能发现没有授权需求的代码和配置改动。Agent “顺手优化”相邻文件时，后者尤其重要。

控制变更，而不是冻结 Spec

活规格通过审查演进，而不是在实现期间静默漂移。

flowchart LR A["草稿"] --> B["已审查"] B --> C["已批准"] C --> D["实施中"] D --> E["验证中"] E -- "发现偏差" --> C E -- "证据通过" --> F["已发布"] F -- "新版本获批" --> G["已替代"]

实现中发现遗漏场景时，应先分类：

  1. 实现缺陷：修代码，Spec 仍然权威。
  2. 规格缺陷：修订需求、影响分析、任务和证据计划。
  3. 新增范围：创建独立变更，不能塞进当前 Diff。
  4. 紧急偏差：记录批准人、理由、有效期、补偿控制和对账任务。

聊天中的新指令不得在不留下版本记录的情况下覆盖已批准制品。

在正确层级让 Spec 可执行

“可执行规格”不代表每句话都生成代码，而是重要主张都有可强制或可重复执行的检查。

  • API 行为：OpenAPI / JSON Schema 校验与契约测试。
  • 事件：AsyncAPI、Schema 兼容与消费者测试。
  • 授权：租户、对象和动作级策略测试。
  • 数据变更：迁移、回滚、不变量和对账。
  • 用户行为：验收与无障碍测试。
  • 可靠性：故障注入、超时、重试和恢复测试。
  • 性能：明确工作负载、环境、分位数和预算。
  • 安全：威胁场景、静态/动态分析与人工评审。

部分证据仍必须由人判断，例如产品文案、法律解释、视觉质量或风险接受。应明确标注人工证据及负责人，而不是伪造自动化。

Spec Coding 与相邻实践的边界

Spec Coding 是协作层，不替代已有软件工程方法。

实践 核心问题 与 Spec Coding 的关系
Vibe Coding 能否快速探索想法？ 适合意图尚未稳定时
产品发现 这个问题值得解决吗？ 提供已验证问题与结果
需求工程 系统为何、必须做什么？ 核心基础
ADR / 设计评审 如何实现，为什么这样选？ 记录架构权衡
TDD / BDD 如何表达并验证行为？ 提供可执行证据
API / Schema First 接口契约必须保持什么？ 机器可检查子集
Harness Engineering 如何限制 Agent 执行？ 强制流程与运行门禁
CI/CD 当前版本能否集成发布？ 执行一致性和发布检查

OpenSpec 与 GitHub Spec Kit 只是围绕这些思想组织制品的不同工具。命令、模板和支持集成属于会变化的产品行为，不是 Spec Coding 的定义。工具操作请阅读 OpenSpec 教程，具体制品写法请阅读 AI 编程 Spec 实战。

按风险调整规格深度

规格深度应随歧义、协作、后果、不可逆性和生命周期增长。

变更 合适的契约
一次性原型 目标、时间盒和删除条件
小型可逆修复 复现、预期行为、回归测试
产品功能 范围、非目标、场景、数据、证据、发布
共享 API 规范性 Schema、兼容、消费者证据、弃用
数据迁移 不变量、对账、容量、回滚、Owner
安全或合规相关变更 正式评审、完整追踪、独立证据、批准留存

不要让每个修改都套用大型模板。无人审查的文档仪式会制造虚假信心，并消耗这套方法本应保护的评审注意力。

常见失败模式

  • 规格洗白：Agent 写完 Spec 后立即自行实现，没有独立审查。
  • 生成测试闭环：同一个误解同时生成代码和断言。
  • 权威来源冲突：工单、聊天、Spec、Schema 与代码不一致，却没有优先级。
  • 非目标泄漏：相邻重构未经批准进入 Diff。
  • 清单式合规：任务完成代替行为证据。
  • 契约过期：实现变化，需求和证据链接没有同步。
  • 工具教派化：团队争论框架，而不是需求和证据质量。
  • 合规表演：声称可追踪，但审计时无法沿链接复现。

评估 Spec Coding 是否有效

应比较采用前后相似变更，不能用生成行数或完成任务数作为成功指标。

建议测量：

  • 实现前澄清轮数；
  • 评审和返工分钟数；
  • 需求覆盖与无授权代码改动；
  • 按需求和风险切片统计的线上缺陷；
  • 从意图批准到变更验收的周期；
  • 实现中发现的规格缺陷；
  • 回滚与事故率；
  • 每个已验收变更的人力与模型总成本。

试验必须保留失败和放弃的变更。如果文档成本上升，而已验收质量、评审负载或恢复能力没有改善，就应简化流程或停止在该类变更上使用。

常见问题

Spec Coding 与 SDD 完全相同吗？

行业用法尚未标准化。本文把 Spec Coding 定义为规格驱动开发在 AI 编程中的务实应用；部分资料会把 SDD 专门用于形式化或模型驱动方法。不要只依赖标签，应明确制品、权威范围和验证等级。

每条需求都必须使用 Given/When/Then 吗？

不必。场景语法适合行为，但数据不变量、安全策略、性能预算、接口 Schema 和运营约束需要其他表达形式。应选择能让主张精确且可验证的表示。

AI Agent 能否批准自己写的 Spec？

高影响变更不能。Agent 可以起草、批判和检查一致性，但负责任的 Owner 必须批准意图与风险，实现也应由独立工具或评审者验证。

Spec 应包含实现细节吗？

只有当它们是真实约束时才写。协议、Schema、算法、依赖或文件边界若受到兼容、安全、运维或已批准架构约束，就应明确；否则应保留设计空间。

最小可用 Spec 包含什么？

普通功能至少需要 Owner、目标、背景、范围、非目标、规范性场景、接口、质量约束、证据、发布与回滚。可以删除不影响任何决策的字段，但不能省略如何判断成功和失败。

相关资源

一手资料