直接回答
一份 AI 编程 Spec 达到“可实施”标准,意味着另一个工程师或 Coding Agent 无需猜测隐含业务规则,就能判断要改什么、不能改什么,以及如何证明结果正确。真正有用的单位不是一段很长的 Prompt,而是一份版本化行为契约:需求能追踪到可观察场景、技术决策、可审查任务与独立证据。
本文用 Go 订单取消接口贯穿完整案例,覆盖归属校验、幂等、状态转换、并发、事件与回滚。案例借用 OpenSpec 的 proposal.md、增量 spec.md、design.md 与 tasks.md 结构,但方法同样适用于 RFC、配合 ADR 的技术方案或普通 Markdown。
先定义要做的决策,而不是先套模板
有价值的 Spec 从团队必须做出的决策和验收所需证据开始,而不是从模板、AI 工具或页面列表开始。
在让 Agent 起草文档前,先写清六件事:
| 问题 | 必须给出的答案 |
|---|---|
| 谁遇到了问题? | 明确的角色或下游系统 |
| 哪个结果要改变? | 一项可观察行为 |
| 本次不做什么? | 明确的非目标 |
| 哪些契约可能被破坏? | API、数据、权限、事件、延迟、兼容性 |
| 哪些情况会失败? | 非法状态、重试、并发、依赖故障、滥用 |
| 什么能证明完成? | 测试、测量、评审、迁移与回滚证据 |
如果答案是“Agent 可以从仓库里推断”,Spec 中仍然存在未声明假设。代码仓库可以呈现当前实现,却不能替产品和系统负责人决定预期行为。
Spec Coding 核心方法解释了规格为什么应当成为决策契约;本文只解决工件应该怎么写。OpenSpec 当前安装、命令、Profile、Delta 语义和归档方式,请查看独立的 OpenSpec 教程。
把五类信息分开放
当动机、行为、设计、任务和证据混在一张清单里,规格会很难评审。每类信息应由对应工件负责。
| 层次 | 回答的问题 | 应包含 | 不应包含 |
|---|---|---|---|
| Proposal | 为什么做,为什么是这个范围? | 问题、结果、受影响能力、影响范围 | 类名、任务复选框 |
| Behavior Spec | 外部观察者必须看到什么? | 输入输出、状态规则、错误、场景 | 框架选型、实现顺序 |
| Design | 系统如何满足契约? | 架构、备选方案、数据一致性、迁移、风险 | 重复业务需求 |
| Tasks | 依赖顺序是什么? | 带验证方法的小步改动 | 藏在任务里的新决策 |
| Evidence | 什么证明已经交付? | 测试报告、基准清单、评审记录、灰度状态 | “Agent 说已经完成” |
OpenSpec 当前默认 Schema 也采用类似分层:先写 Proposal,再写 Spec 与 Design,最后生成 Tasks。官方文档还规定 design.md 可按复杂度省略;只有行为没有变化时,变更才可以不包含 Spec。这里的文件形式属于具体工具约定,长期有效的原则是把“为什么、做什么、怎么做、如何执行、如何证明”分开。
从可观察行为写起
需求应描述用户、调用方、运维人员或下游系统能观察到的行为。只要调用方不依赖某项内部选择,它通常属于 Design,而不是 Behavior Spec。
| 模糊写法 | 为什么无法验收 | 可测试的改写 |
|---|---|---|
| “取消接口要快” | 没有阈值、负载和测量位置 | “在约定 Fixture、50 requests/s 下,网关测得 API p95 延迟 MUST 小于 250 ms。” |
| “使用乐观锁” | 在说明行为前指定机制 | “两个并发取消请求 MUST 只产生一次状态转换和一条取消事件。” |
| “妥善处理错误” | 没有错误分类和调用方契约 | “不可取消状态 MUST 返回 409 order_not_cancellable,且订单不得变化。” |
| “只有订单所有者能取消” | 未定义是否泄漏资源存在性 | “非订单所有者 MUST 收到与未知订单相同的 404 order_not_found。” |
| “支持重试” | 未定义重放语义 | “重复请求已成功取消的订单 MUST 返回取消后的状态,且不得重复发送事件。” |
如果文档显式采用 BCP 14,MUST、SHOULD 与 MAY 可以清晰表达不同要求等级;BCP 14 由 RFC 2119 和 RFC 8174 共同定义,并规定只有全大写形式具有特殊含义。应谨慎使用这些词。大写不能让模糊要求自动变得可度量,也不能把个人设计偏好包装成强制需求。
完整案例:安全取消订单
本次变更为已有服务增加 POST /v1/orders/{id}/cancel。取消订单看起来很小,却会迫使 Spec 明确身份、状态、重试、并发请求、事件和向后兼容。
用 proposal.md 锁定范围
Proposal 应短到足以在实现前完成评审。它负责说明问题和边界。
# Proposal: add-order-cancellation
## Why
未发货订单目前只能由客服取消。
系统需要一个有明确状态与权限语义的用户自助取消入口。
## What Changes
- 为订单所有者增加需登录的取消操作。
- 成功请求的重试保持幂等。
- 一次状态转换只发送一条取消事件。
- 保持已有订单查询响应不变。
## Non-Goals
- 退回已结算款项。
- 取消已履约或已发货订单。
- 增加管理员取消能力。
- 重构整个订单状态机。
## Impact
- HTTP API、订单 Repository、事件 Outbox、审计日志和客户端 SDK。
非目标可以阻止“看起来合理但未经授权”的范围扩张。它还能告诉评审者:新发现的依赖何时需要先修订 Spec,而不是在实现中临场决定。
用 spec.md 定义行为契约
每项需求都应保持单一、具名,并配套场景。Given/When/Then 能把初始状态、事件和可观察结果分开。Cucumber Gherkin 官方参考还强调,Then 应验证系统输出,而不是隐藏在内部的实现细节。
## ADDED Requirements
### Requirement: 订单所有者可以取消符合条件的订单
服务 SHALL 允许已登录的订单所有者取消当前状态为 PENDING 的订单。
#### Scenario: 首次取消成功
- **GIVEN** 订单 `o-42` 属于调用方 `u-7`,状态为 PENDING
- **WHEN** `u-7` 请求取消 `o-42`
- **THEN** 响应状态码为 200
- **AND** 响应中的订单状态为 CANCELLED
- **AND** 恰好有一条取消事件可被观察到
#### Scenario: 重试已成功的取消
- **GIVEN** 订单 `o-42` 已被一次成功请求取消
- **WHEN** 所有者 `u-7` 再次请求取消
- **THEN** 返回 200,订单状态仍为 CANCELLED
- **AND** 不再发送新的取消事件
### Requirement: 取消接口不得泄漏他人订单
服务 SHALL NOT 暴露某订单是否属于其他用户。
#### Scenario: 调用方不是订单所有者
- **GIVEN** 订单 `o-42` 属于 `u-7`
- **WHEN** 调用方 `u-9` 请求取消 `o-42`
- **THEN** 返回 `404 order_not_found`
- **AND** 订单和事件流均保持不变
### Requirement: 拒绝不允许取消的状态
履约开始后,服务 SHALL 拒绝取消。
#### Scenario: 订单已经履约
- **GIVEN** 订单 `o-42` 状态为 FULFILLED
- **WHEN** 所有者请求取消
- **THEN** 返回 `409 order_not_cancellable`
- **AND** 订单和事件流均保持不变
这段文字本身还不是可执行测试。Gherkin 只有在场景映射到 Step Definition 或其他确定性检查后才可执行。即使不用 Cucumber,这种结构也能帮助评审者发现状态遗漏,并让实现测试引用同一批场景 ID。
单独定义接口契约
自然语言不能替代 Schema。HTTP 变更应在 OpenAPI 或其他机器可读接口中定义 Method、Path、认证、请求、成功响应、错误结构、兼容策略和幂等语义。
| 契约项 | 决策 |
|---|---|
| Operation | POST /v1/orders/{orderId}/cancel |
| Authentication | 复用已有 Bearer Token 中间件 |
| Success | 200,返回订单 ID、当前状态与版本号 |
| 未知或他人订单 | 404,稳定错误码 order_not_found |
| 不可取消状态 | 409,稳定错误码 order_not_cancellable |
| Retry | 已取消订单返回 200,不重复发送事件 |
| Concurrency | 条件更新只成功一次,失败方读取已接受状态 |
| Compatibility | 现有字段和订单查询行为保持不变 |
OpenAPI Specification定义了与语言无关的 HTTP API 描述,让人和程序无需检查源码就能理解服务能力。Spec 应引用仓库中唯一的接口文件和验证命令,而不是在正文里复制一份会漂移的 Schema。
在 design.md 中记录机制与取舍
Design 解释实现将如何满足行为契约:
# Design
## Decisions
1. Repository 使用当前 Version 作为 Compare-and-Swap 条件,
原子执行 PENDING -> CANCELLED。
2. 取消事件与状态转换在同一事务中写入 Outbox。
3. 未知订单与他人订单使用相同外部错误;
内部审计记录保留两者差异。
4. 重试读取已取消状态并直接返回,不追加第二条事件。
## Alternatives
- 不采用分布式锁:数据库条件更新可以用更小的故障面保证目标不变量。
- 不直接发布 Broker:否则数据库提交成功时,消息发布仍可能失败。
## Risks and Mitigations
- 热点订单竞争 -> 有界重试与并发测试。
- Outbox 积压 -> 事件年龄与投递延迟告警。
- 客户端重试风暴 -> 网关限流与幂等响应。
## Migration and Rollback
- 启用接口前先增加向后兼容的存储字段。
- 通过租户 Allowlist 灰度。
- 关闭路由时不回滚已经接受的取消记录。
此时,“使用乐观锁”不再是无来源偏好,而是由业务不变量推导出的设计决策。如果另一种方案能交付相同的外部行为和运行证据,它也可以成立。
让质量约束可以复测
非功能需求必须带测量契约。只有阈值,没有实验条件,结果不可复现。
| 维度 | 不完整写法 | 可审查写法 |
|---|---|---|
| 性能 | “p95 小于 250 ms” | 负载形态、Fixture、预热、并发、观测位置、分位算法、样本量 |
| 可靠性 | “不能重复发事件” | 事件身份、重试计划、崩溃点、观测窗口 |
| 安全 | “接口必须安全” | 角色矩阵、拒绝场景、响应等价性、审计要求 |
| 兼容性 | “不得破坏兼容” | 对比的 Schema、客户端、Fixture 与兼容检查器 |
| 可观测性 | “增加指标” | 指标名、单位、Label、负责人、告警条件、基数上限 |
| 回滚 | “支持回滚” | 触发条件、命令或开关、状态兼容、负责人、演练证据 |
不要发明通用延迟门槛。阈值只有结合系统 SLO 和代表性负载才有意义。同样,“只产生一条事件”需要事件身份和观察窗口,不能只靠 Unit Test 里的 Mock 证明。
安全验收应属于本次变更,而不是上线前追加的通用清单。NIST SSDF 1.1把安全软件开发组织为准备组织、保护软件、生产安全软件和响应漏洞四组实践。Feature Spec 无需复制整个框架,但应把相关安全需求映射到具体控制与证据。
把场景变成可运行的 Go 证据
下面的 Domain 函数只实现内存中的决策边界。它不能证明数据库原子性、HTTP 错误映射、Outbox 投递或认证中间件;这些能力必须由 Repository、Handler 与 Integration Test 分别验证。
package cancellation
import "errors"
type Status string
const (
StatusPending Status = "PENDING"
StatusCancelled Status = "CANCELLED"
StatusFulfilled Status = "FULFILLED"
)
var (
ErrUnauthenticated = errors.New("unauthenticated")
ErrNotFound = errors.New("order_not_found")
ErrNotCancellable = errors.New("order_not_cancellable")
)
type Order struct {
ID string
OwnerID string
Status Status
Version int
}
type Result struct {
Order Order
Changed bool
}
func Cancel(order Order, actorID string) (Result, error) {
if actorID == "" {
return Result{}, ErrUnauthenticated
}
if actorID != order.OwnerID {
return Result{}, ErrNotFound
}
switch order.Status {
case StatusCancelled:
return Result{Order: order, Changed: false}, nil
case StatusPending:
order.Status = StatusCancelled
order.Version++
return Result{Order: order, Changed: true}, nil
default:
return Result{}, ErrNotCancellable
}
}
表驱动测试让每个 Case 都能回指一个场景。测试通过只证明当前代码边界中的行为;下一节的证据矩阵会阻止团队把这个局部结果误认为端到端完成。
package cancellation
import (
"errors"
"testing"
)
func TestCancel(t *testing.T) {
tests := []struct {
name string
order Order
actorID string
wantStatus Status
wantVersion int
wantChanged bool
wantErr error
}{
{
name: "AC-1 owner cancels pending order",
order: Order{ID: "o-42", OwnerID: "u-7", Status: StatusPending, Version: 3},
actorID: "u-7",
wantStatus: StatusCancelled,
wantVersion: 4,
wantChanged: true,
},
{
name: "AC-2 retry returns accepted state",
order: Order{ID: "o-42", OwnerID: "u-7", Status: StatusCancelled, Version: 4},
actorID: "u-7",
wantStatus: StatusCancelled,
wantVersion: 4,
wantChanged: false,
},
{
name: "AC-3 foreign caller cannot discover order",
order: Order{ID: "o-42", OwnerID: "u-7", Status: StatusPending, Version: 3},
actorID: "u-9",
wantErr: ErrNotFound,
},
{
name: "AC-4 fulfilled order is ineligible",
order: Order{ID: "o-42", OwnerID: "u-7", Status: StatusFulfilled, Version: 3},
actorID: "u-7",
wantErr: ErrNotCancellable,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := Cancel(tt.order, tt.actorID)
if !errors.Is(err, tt.wantErr) {
t.Fatalf("error = %v, want %v", err, tt.wantErr)
}
if tt.wantErr != nil {
return
}
if got.Order.Status != tt.wantStatus ||
got.Order.Version != tt.wantVersion ||
got.Changed != tt.wantChanged {
t.Fatalf("result = %+v", got)
}
})
}
}
预期结果:
ok example.com/specdemo/cancellation
建立需求到证据的追踪矩阵
追踪关系可以防止“测试全绿”掩盖仍未验证的需求。为需求和场景分配稳定 ID,再明确证据类型和门禁。
| 需求 | 场景 | 证据 | 门禁 |
|---|---|---|---|
ORD-CANCEL-1 |
所有者取消待处理订单 | Domain Test + HTTP Contract Test | CI 必须通过 |
ORD-CANCEL-1 |
重试保持幂等 | Handler Test + 事件数量断言 | CI 必须通过 |
ORD-CANCEL-2 |
隐藏他人订单 | 权限 Integration Test | CI 必须通过 |
ORD-CANCEL-3 |
拒绝已履约订单 | Domain 与 API Test | CI 必须通过 |
ORD-CANCEL-4 |
两个并发请求 | 数据库竞争测试 + Outbox 断言 | 灰度前必须通过 |
ORD-CANCEL-5 |
p95 延迟预算 | 带版本的压测报告 | 扩量前必须通过 |
ORD-CANCEL-6 |
路由可关闭 | Staging 回滚演练 | 灰度前必须通过 |
矩阵的作用是暴露证据缺口,而不是默认缺失项已经成功。Unit Test 不能证明数据库竞争,Schema Linter 不能证明权限正确,AI Review 也不能替代独立执行的测试。
对于风险更高的 Agent 工作流,Agent Harness 评测指南采用相同原则:先定义轨迹、权限、结果和证据,再相信完成声明。
把 Tasks 写成可验证交付切片
任务应按依赖顺序拆分,并在每个切片中同时交付测试。不要采用“先写完所有 Model,再写 Handler,最后统一补测试”的横向分层计划,否则证据会被拖到末尾才出现。
## 1. Domain 状态转换
- [ ] 1.1 实现 PENDING -> CANCELLED 与幂等重试;
用 AC-1、AC-2、AC-4 表驱动测试验证。
## 2. 持久化与事件
- [ ] 2.1 增加原子条件更新与事务 Outbox;
用两个并发请求和唯一 Event ID 验证 AC-4。
## 3. HTTP 契约与权限
- [ ] 3.1 增加 OpenAPI Operation 与生成的 Contract Fixture;
验证成功响应、稳定错误码与兼容性。
- [ ] 3.2 接入已有认证与归属校验;
验证 AC-3,且不暴露订单是否存在。
## 4. 发布
- [ ] 4.1 增加指标、告警负责人和租户 Allowlist;
验证 Staging Dashboard 与回滚演练。
复选框只表示进度,不是证据。任务文本必须写出评审者可以检查的产物或命令。
实现前先过一次 Spec Review Gate
让 Agent 在写代码前先批判 Spec。Review 输出应该是问题和矛盾,而不是静默“润色”需求。
按以下十项检查:
- Identity:每个角色、资源和外部依赖是否有稳定名称?
- State:合法状态转换和终态是否明确?
- Error:非法输入、拒绝、超时和依赖故障是否都有可观察行为?
- Concurrency:请求竞争、重复、迟到或崩溃恢复时会发生什么?
- Data:哪些字段要存储、记录、发送、保留、脱敏或删除?
- Compatibility:哪些客户端、Schema、事件和迁移必须继续工作?
- Measurement:每个延迟、质量或可靠性阈值在哪里观测?
- Verification:每个
MUST是否能追踪到测试、分析、演示或检查? - Rollback:能否关闭或回滚变更,而不破坏已经接受的状态?
- Open Questions:任何未决问题是否会改变行为、设计或任务顺序?如果会,先停止并解决。
Agent 可以帮助发现遗漏,但产品和系统负责人必须做出决定。流畅的草稿不等于已经批准的需求。
在实现过程中控制变更
当聊天里的临时决定绕过版本控制,Spec 就会失效。应像管理代码一样管理需求变化:
- 行为改变时,先更新行为契约再实现。
- 在同一次 Review 中查看 Spec Diff 与 Code Diff。
- 对有意偏离记录原因、负责人和到期条件。
- 重新运行所有受影响场景,而不只是新 Happy Path。
- 只有实现证据齐全后,才归档或合并已接受的 Delta。
- 让运行时配置和应急开关可追踪到具体发布版本。
OpenSpec 使用活动变更保存 Delta Spec,主规格描述当前已经接受的系统行为。当前 spec-driven Schema 区分 ADDED、MODIFIED、REMOVED 与 RENAMED,其中修改已有需求时必须提供完整更新后的需求块。具体产品机制以 OpenSpec Schema 参考为准。
七类常见失败
Spec 只是把工单复述了一遍
“增加订单取消”只说出了功能名,没有定义允许状态、调用方、错误、重试和证据。应补上任何实现者原本只能猜测的决定。
Spec 指定代码,却没有定义行为
“创建带 Mutex 的 CancellationService”仍可能交付错误的用户结果。把可替换机制放入 Design,把必须保持的不变量写进 Spec。
只有 Happy Path,却宣称覆盖完整
一个成功案例无法覆盖权限、空状态、重复请求、并发、依赖故障、兼容与回滚。应从状态模型和故障模型生成场景。
生成测试只是复述生成代码
Agent 可能用同一项错误假设同时生成实现和测试。评审者必须用需求核对 Expected Outcome,使用独立 Fixture,并对安全与关键业务逻辑保留人工评审。AI Code Review 流水线进一步解释了如何把生成与审查证据分开。
指标阈值没有工作负载
“p95 < 250 ms”如果缺少请求分布、并发、环境、预热、样本量与测量边界,就无法复现。
Tasks 偷渡产品决策
如果 Task 写着“增加管理员强制取消”,但没有任何需求授权它,实现已经越过批准范围。此时应修订 Spec 或删除任务。
文档大到没人能提出异议
应按可独立评审的行为拆分,而不是按页数机械拆分。小改动可能只需一项需求和四个场景;跨服务迁移则可能需要多个 Capability Spec 与详细 Design。
哪些改动不值得写完整 Spec
规格深度应与风险和不确定性匹配。
| 变更 | 最小有效工件 |
|---|---|
| 错别字或机械改名 | Task、Diff 与定向检查 |
| 行为不变的局部重构 | 范围、不变量、测试、无行为变化声明 |
| 用户可见功能 | 行为需求、场景、接口契约、灰度方案 |
| 数据迁移 | 源/目标 Schema、不变量、对账、回滚 |
| 认证或授权 | 角色矩阵、拒绝场景、审计、威胁评审、回滚 |
| 跨服务协议 | 版本、兼容、失败语义、可观测性 |
| 不可逆或受监管操作 | 审批、证据留存、恢复、独立评审 |
目标不是写最多的文档,而是用最小契约让有后果的假设变得可见、可测试。
常见问题
AI 编程 Spec 应该包含哪些内容?
至少包括用户可见结果、范围与非目标、输入输出和状态契约、权限与失败行为、可度量质量约束、验收场景、灰度与回滚条件,以及需求到证据的映射。只有实现安全或评审确实依赖某项设计时,才补充 Design 细节。
Coding Spec 应该写多细?
凡是省略后可能改变行为、兼容性、安全、数据完整性、可靠性或验收结果的决定都应写清。不要规定可替换的实现细节。如果两名合格工程师能选择不同内部实现并通过同一组场景,该内容通常应放在 Design。
Given、When、Then 场景就是可执行测试吗?
不是。它们是结构化示例,只有映射到 Step Definition、表驱动测试、Contract Test 或其他确定性验证器后才可执行。让 Then 聚焦外部可观察结果,避免测试无谓冻结内部实现。
Spec 和 Prompt 有什么区别?
Prompt 发起一次模型交互;Spec 则作为经过评审、版本化的契约,跨工具、会话、Commit 和 Release 持续存在。实现 Prompt 应引用已批准的 Spec 和当前 Task,而不应在隐蔽的聊天记录里重新定义必要行为。
团队如何防止 Spec 漂移?
要求行为变化先修改 Spec,再修改代码;评审两类 Diff;使用稳定需求 ID;把每项需求追踪到证据;记录临时偏离;合并前对齐最终契约。当测试或实现没有需求来源,或需求没有任何证据时,漂移就已经显现。
权威来源与延伸阅读
- ISO/IEC/IEEE 29148:2018 需求工程标准:规定需求工程过程与信息项;现行版本仍有效,同时已有修订版在研。
- BCP 14:RFC 2119 与 RFC 8174:规范性关键词的精确定义和大小写规则。
- Cucumber Gherkin 官方参考:Scenario、Given/When/Then 语义与可观察结果。
- OpenAPI Specification:机器可读 HTTP 接口契约。
- NIST SP 800-218 SSDF 1.1:安全软件开发实践及证据边界。
- OpenSpec
spec-drivenSchema:当前 Proposal、Delta Spec、Design 与 Task 工件契约。 - Spec Coding 核心方法
- OpenSpec 教程
- AI Code Review 流水线