按路径掌握 Spec-First 开发

当一个改动可能以多种合理方式失败时，就值得先写 Spec。典型场景包括客户数据、资金、权限、公开 API、数据库迁移、后台任务、发布开关，以及 AI 生成代码。简单文案修改可以只用清单；退款流程、schema 迁移、合作方接口、通知偏好模型和队列消费者，都应该先有一条书面决策路径。

最快的判断方法是：如果评审者即使通过 PR，仍可能对“期望行为”有不同理解，那就先写规格。Spec 不需要提前决定所有实现细节，但必须写清行为、边界、负责人，以及什么证据能证明这次变更可以发布。

退款流程适合作为第一份练习，因为失败模式很具体。模糊 ticket 只会写“允许用户退款订单”；可评审 Spec 会决定退款窗口、重复请求处理、支付渠道超时状态、客服 override、事件发送、审计日志，以及什么上线指标应该触发暂停。

Spec-First 版本仍然可以很短：已捕获款项 90 天内可退款；同一个 idempotency key 重复请求返回同一个 refund id；支付渠道超时进入 pending confirmation；如果 15 分钟内重复退款尝试超过阈值，就暂停发布。这样产品、研发、QA、支持和 AI 编码工具都能在同一个边界内工作。

# 退款工作流验收切片

Given 一笔 90 天内的已捕获款项
When 使用新的 idempotency key 发起退款
Then 创建一条 refund 记录，发送一次 refund_requested 事件，
并写入包含 actor、charge_id、refund_id 和 reason 的审计日志。

Given 同一个请求用相同 idempotency key 重放
When 服务再次收到请求
Then 返回已有 refund_id，并且不再发送第二次事件。

使用 AI 编码工具时，先贴规格，再要求写代码。边界要清楚到模型可以被评审：允许修改哪些文件，哪些行为不在范围内，哪些测试算作证据，如果规格不清楚时应该先提问还是自行假设。

请把下面的 Spec 作为唯一事实来源。

规则：
- 不要实现非目标之外的行为。
- 只修改 Allowed files 中列出的文件。
- 如果需求有歧义，先提问，不要直接实现。
- 每条验收标准都要有测试。
- 最后返回变更文件、测试命令和证据摘要。

Spec：
[粘贴已评审的规格]

第一次推行时，不要要求团队一次性改掉所有流程。先选择一个真实但风险可控的需求，把 ticket 里原本最容易口头沟通的部分写成 Spec：目标、非目标、验收标准、边界情况和证据。评审时只问三个问题：行为是否清楚，失败路径是否可测试，合并前需要什么证据。

完成一次后，把最终 Spec、PR、测试结果和上线观察记录放在一起复盘。保留真正帮到评审的字段，删掉没人维护的字段。Spec-First 的重点不是多写文档，而是让团队在实现前先做出可检查的工程决定。