spec-best-practices

命名

主规范文件始终命名为 SPEC.md，没有例外。不能命名为 feature.spec.md，也不能命名为 SPEC-feature.md。

从 SPEC.md 目录链接的辅助文档可以使用描述性名称（例如 commands.spec.md），但前提是根目录存在 SPEC.md，且其中链接到了这些文档。

放置位置

规范文件与其描述的代码放在一起：项目范围使用根目录下的 SPEC.md，应用范围使用 apps/foo/SPEC.md，包范围使用 packages/bar/SPEC.md。

• 避免使用 spec/、docs/specs/ 和 docs/plans/ 目录。优先使用与代码放在一起的 SPEC.md 文件。
• 计划文档是临时的。将持久有效的决策纳入相关 SPEC.md，然后删除计划文档。
• 规范内容较长时，添加目录，链接到相邻的辅助文件（如 ./commands.spec.md）。辅助文件与 SPEC.md 放在一起，而不是放在子目录中。

内容

规范采用自由格式的 Markdown。没有固定模板、YAML 前置元数据或必需的章节顺序。以下内容必须包含在内：

问题与解决方案 —— 说明此系统／功能存在的原因和背景。先阐述问题。

领域模型 —— 类型、关系、数据流。对于追溯性规范，应从检查过的代码中推导。

带有 REQ-* ID 的需求 —— 每项行为需求都必须有稳定的标识符。格式为 REQ-{DOMAIN}-{NNN}（例如 REQ-AUTH-001）。只追加，绝不重新编号。每项需求都必须可测试、可追溯。

不变量 —— 必须始终成立的条件。

非目标 —— 明确的范围边界。说明本规范有意不涵盖的内容。

验收标准 —— 使用 Markdown 清单，而非散文：

- [ ] Auth endpoint returns JWT with tier claim
- [ ] Rate limiter rejects >100 req/min per IP

风险标签（条件性）—— 当存在高风险事项（架构迁移、身份验证变更、公共 API 合约、基础设施变更）或 ADF PLAN 门禁要求审批时，标记这些事项。

测试可追溯性（条件性）—— REQ-* 到测试文件及行号的映射。在 TDD 期间或之后添加，不在初始编写时添加。

编写规则

以证据为依据：编写规范内容前先阅读代码。不要臆造行为、签名或文件路径。对于追溯性规范，应根据实际实现推导需求。

根据检查机制校准断言强度：绝对化用语（“无法表示”“不能”“结构上可捕获”“任何回归都会触发检查”）必须与检查实际能够证明的内容相符。如果审查者能在 60 秒内构造出反例（注释中的诱饵、字符串字面量、被遮蔽的绑定、计算得出的路径），则 SPEC 的断言过强。应加强检查、缩小断言范围（例如，“可阻止字面量 spawn 回归；注释／字符串／绑定遮蔽情况由配套测试覆盖”），或将差距记录为待解决事项。以证据为依据的保守措辞，胜过容易引发反复拒绝的强硬措辞。

追溯性规范同样重要：记录现有行为是有效且值得提倡的做法。阅读实现，从实际行为中提取需求，将不一致之处记录为待解决事项（而不是默默略过），并将可追溯性映射到现有测试。

修改政策：除非用户明确要求，否则不要编辑规范。发现规范与实现不一致时，应立即指出。绝不默默容忍或修复这种不一致——由用户决定更新规范还是代码。

规范与计划：规范描述是什么以及为什么；计划描述如何以及何时。计划是临时的。将持久有效的决策纳入规范，然后删除计划文档。

生命周期

创建（SPEC 门禁）：门禁要求请参阅 CLAUDE.md 中的 ADF SPEC 门禁。确定文件放置位置，读取现有文件并找出缺漏（或在正确的同目录路径下创建文件），确保包含所有必需元素。

维护：行为发生变化时更新规范；追加新的 REQ-* ID，切勿重新编号；编写测试时添加测试可追溯性；当规范和实现同时出现在上下文中时，交叉核对二者并指出偏差。

退役：移除某项功能时，删除或归档其 SPEC.md。不要留下描述已删除行为的过时规范。