夜雨聆风
为什么先写 Spec
自然语言需求经常混合目标、方案和偏好。Agent 若直接实现，会用默认假设填空。Spec 的价值是把“你以为它懂”变成可审查的 Source of Truth。
Spec Kit 与 OpenSpec 都体现了同一方向：让需求、设计和任务作为版本化工件，而不是消失在聊天记录中。流程可以轻量，工件不能缺关键约束。
最小四件套
specs/checkout-discount/
├── proposal.md # 为什么做、范围和非目标
├── requirements.md # SHALL + Scenario
├── design.md # 技术决策、数据流、风险
├── tasks.md # 可执行、可验证任务
└── readiness.md # 阶段准入/退出结论EARS + Scenario 双写法
EARS 用于稳定地表达规则；Given-When-Then 用于确认可观察行为。
### R-01 优惠码过期
系统 SHALL 在结算请求处理开始时验证优惠码的 expires_at。
当 expires_at 小于或等于当前 UTC 时间时，系统 SHALL 返回 422。
Scenario: 过期优惠码不可使用
Given 优惠码 expires_at 为 2026-07-13T10:00:00Z
When 用户于 2026-07-14T10:00:00Z 提交结算
Then 返回 code=COUPON_EXPIRED
And 不创建折扣记录每个关键 SHALL 至少覆盖：正常路径、边界/异常路径、不可变约束（例如“不创建记录”）。
需求就绪检查
进入设计前至少检查：
- •是否有明确的业务目标、范围与非目标？
- •是否给出输入、输出、错误语义和边界条件？
- •是否明确兼容性、权限、性能或审计约束？
- •是否能把每条 SHALL 映射到验证方式？
- •未决问题是否被标记为 BLOCKED，而不是由开发者猜测？
配套工程的 check_requirements.py 会检查 Requirements 是否包含 SHALL 与 Scenario；它不能判断业务是否正确，却能阻止“空壳文档”继续流转。
模板不是官样文章
模板应该降低遗漏，不是增加表单负担。好的模板用字段逼出关键决策：
## Design Decision
- 选择：在 DiscountService 的边界层校验过期。
- 原因：所有入口都经过该服务，避免 Controller 重复判断。
- 不选：在前端拦截；因为不能作为可信业务约束。
- 风险：时钟来源不一致。
- 验证：固定 Clock 的单元测试 + API 集成测试。Spec 的演进规则
需求变更时先变更 Spec，再变更实现；否则会出现“代码已经做了、文档之后补”的漂移。对于紧急修复，允许先处置风险，但应在合并前补齐变更说明与回归 Scenario。
深入：从模糊需求到可实现 Spec 的完整示例
假设原始需求是：“过期优惠码不能再用，最好给用户一个提示。”它同时遗漏了时钟、边界、错误码、数据副作用和兼容性。以下是一个完整的分解过程。
# Proposal：拒绝过期优惠码
## 目标
避免订单在优惠码已失效后仍获得折扣。
## 范围
- 在服务端应用优惠码前校验到期时间。
- 返回稳定的领域错误码。
## 非目标
- 不修改营销后台的创建/延期流程。
- 不增加宽限期，也不处理多优惠码叠加。
## 开放问题
- 历史数据缺少 `expires_at` 时由谁决定迁移或拒绝策略？Owner：营销域负责人。# Requirements：checkout-discount
## R-01 过期校验
系统 SHALL 在应用优惠码之前，以 UTC 比较 `expires_at` 与当前时间。
### Scenario：恰好到期
Given `expires_at` 等于当前 UTC 时间
When 客户提交结算请求
Then 系统返回 HTTP 422 和 `code=COUPON_EXPIRED`
And 不创建折扣记录
And 订单金额保持未折扣状态
## R-02 输入完整性
系统 SHALL 拒绝没有时区信息的 `expires_at`，并记录可诊断原因。注意其中的 And：它把“不可产生副作用”变成验收内容。很多 Agent 只会验证响应码，却遗漏写入、事件或缓存是否已经发生。
设计文档应回答的六个问题
- •边界在哪里？ 哪个服务是唯一可信的校验点？
- •数据从哪里来？ 时间字段的时区、精度、空值和版本如何处理？
- •失败如何表达？ 错误码、日志、用户文案和重试语义分别是什么？
- •副作用如何控制？ 何时事务开始，失败前哪些写入绝不能发生？
- •如何验证？ 每条 Requirement 映射到单元、集成或端到端证据。
- •怎么回滚？ 是否有 Feature Flag、兼容层、迁移回退或观察窗口？
## D-02：时钟与事务边界
- 决策：在 `DiscountService.apply` 的事务开始前执行 UTC 校验。
- 原因：所有 API 与批处理入口都会经过该服务，避免入口之间语义漂移。
- 失败语义：过期时返回 `COUPON_EXPIRED`，不创建折扣记录、不发出折扣事件。
- 风险：调用方传入 naive datetime。
- 缓解：领域对象构造或 `_as_utc` 显式拒绝；测试覆盖。
- 回滚：该变更无数据库 Schema 修改，可通过 Feature Flag 关闭调用路径。自动检查能做什么，不能做什么
check_requirements.py 能检查文档是否有 SHALL、Scenario、Given/When/Then 和 Requirement 标题；它不能判断“HTTP 422 是否真的是正确业务选择”。因此使用两层策略：脚本保证结构完整，角色评审保证语义正确。不要因有脚本就取消业务评审，也不要因为需要人评审就放弃结构化检查。
Spec 变更的版本纪律
当实现发现需求无法满足时，不能悄悄修改代码并在 PR 描述里解释。应新建变更记录：说明旧 Requirement、提议的新语义、受影响测试、批准人和迁移策略。对于紧急修复，至少在合并前补齐该记录；否则下一个 Agent 会根据旧 Spec 把“修复”重新改坏。
非功能需求：最容易被 Agent 默认忽略的部分
只写功能行为，常会得到“演示能跑、生产不可用”的实现。对每个变更，显式判断是否涉及性能、可用性、安全、隐私、可观测性、兼容性和成本；不适用也要写出理由。
## NFR：checkout-discount
### NFR-01 可观测性
系统 SHALL 在拒绝过期优惠码时记录结构化事件，字段包含 `coupon_id_hash`、
`reason=COUPON_EXPIRED` 与 `request_id`；不得记录原始客户数据。
### NFR-02 兼容性
现有客户端收到的错误响应 SHALL 保持 HTTP 422，新增字段只能向后兼容。
### NFR-03 性能
优惠码校验 SHALL 不新增远程同步调用；服务端额外 P95 延迟预算不超过 5ms。对应的验证不一定都是单元测试：可观测性需要日志契约测试或集成检查；兼容性需要 OpenAPI/契约 diff；性能需要基准或压测。把验证方式写在 Spec 中，避免到上线前才发现“没有人测过”。
Spec Kit 与 OpenSpec：借鉴流程，不绑定工具
Spec Kit 的公开工作流强调先建立项目原则，再按 specify → plan → tasks → implement 逐步细化，并提供 clarify、analyze、checklist 等质量辅助；OpenSpec 的实践强调以 change 目录保存 proposal、specs、design、tasks，并允许在变更过程中迭代这些工件。两者共同点是把意图和证据版本化，而非要求团队照搬命令或目录名称。
AGENTS.md | |||
proposal.md | |||
specs/ | |||
design.mdtasks.md | |||
选择框架前先问：团队是否需要强阶段门、是否已有 Issue/PR 体系、是否跨仓库、哪些工件是合规必需。工具应适配流程，不应反过来让团队为工具填表。
本讲练习
打开 specs/checkout-discount/。从 R-01 找到对应设计、任务、测试和验证证据，完成一次手工追踪。
小结
Spec 不是瀑布式负担，而是人和 Agent 的共享语义层。没有可验证 Spec，多角色协作只是在传递不同版本的猜测。
