直接回答

一份 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。这里的文件形式属于具体工具约定,长期有效的原则是把“为什么、做什么、怎么做、如何执行、如何证明”分开。

flowchart LR A["问题与范围"] --> B["可观察需求"] B --> C["设计决策"] B --> D["验收场景"] C --> E["可审查任务"] D --> E E --> F["代码与测试"] F --> G["发布证据"] G -->|"行为变化"| B

从可观察行为写起

需求应描述用户、调用方、运维人员或下游系统能观察到的行为。只要调用方不依赖某项内部选择,它通常属于 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 应短到足以在实现前完成评审。它负责说明问题和边界。

markdown
# Proposal: add-order-cancellation

## Why

未发货订单目前只能由客服取消。
系统需要一个有明确状态与权限语义的用户自助取消入口。

## What Changes

- 为订单所有者增加需登录的取消操作。
- 成功请求的重试保持幂等。
- 一次状态转换只发送一条取消事件。
- 保持已有订单查询响应不变。

## Non-Goals

- 退回已结算款项。
- 取消已履约或已发货订单。
- 增加管理员取消能力。
- 重构整个订单状态机。

## Impact

- HTTP API、订单 Repository、事件 Outbox、审计日志和客户端 SDK。

非目标可以阻止“看起来合理但未经授权”的范围扩张。它还能告诉评审者:新发现的依赖何时需要先修订 Spec,而不是在实现中临场决定。

用 spec.md 定义行为契约

每项需求都应保持单一、具名,并配套场景。Given/When/Then 能把初始状态、事件和可观察结果分开。Cucumber Gherkin 官方参考还强调,Then 应验证系统输出,而不是隐藏在内部的实现细节。

markdown
## 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 解释实现将如何满足行为契约:

markdown
# 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 分别验证。

go
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 都能回指一个场景。测试通过只证明当前代码边界中的行为;下一节的证据矩阵会阻止团队把这个局部结果误认为端到端完成。

go
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)
			}
		})
	}
}

预期结果:

text
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,最后统一补测试”的横向分层计划,否则证据会被拖到末尾才出现。

markdown
## 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 输出应该是问题和矛盾,而不是静默“润色”需求。

按以下十项检查:

  1. Identity:每个角色、资源和外部依赖是否有稳定名称?
  2. State:合法状态转换和终态是否明确?
  3. Error:非法输入、拒绝、超时和依赖故障是否都有可观察行为?
  4. Concurrency:请求竞争、重复、迟到或崩溃恢复时会发生什么?
  5. Data:哪些字段要存储、记录、发送、保留、脱敏或删除?
  6. Compatibility:哪些客户端、Schema、事件和迁移必须继续工作?
  7. Measurement:每个延迟、质量或可靠性阈值在哪里观测?
  8. Verification:每个 MUST 是否能追踪到测试、分析、演示或检查?
  9. Rollback:能否关闭或回滚变更,而不破坏已经接受的状态?
  10. Open Questions:任何未决问题是否会改变行为、设计或任务顺序?如果会,先停止并解决。

Agent 可以帮助发现遗漏,但产品和系统负责人必须做出决定。流畅的草稿不等于已经批准的需求。

在实现过程中控制变更

当聊天里的临时决定绕过版本控制,Spec 就会失效。应像管理代码一样管理需求变化:

  1. 行为改变时,先更新行为契约再实现。
  2. 在同一次 Review 中查看 Spec Diff 与 Code Diff。
  3. 对有意偏离记录原因、负责人和到期条件。
  4. 重新运行所有受影响场景,而不只是新 Happy Path。
  5. 只有实现证据齐全后,才归档或合并已接受的 Delta。
  6. 让运行时配置和应急开关可追踪到具体发布版本。

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;把每项需求追踪到证据;记录临时偏离;合并前对齐最终契约。当测试或实现没有需求来源,或需求没有任何证据时,漂移就已经显现。

权威来源与延伸阅读