用途:在创建、评审或更新 SPEC.md、运行 /specout、进入 ADF SPEC gate 时使用,指导规范文档的写法。
命名与放置:主规范文件一律命名为 SPEC.md,不支持 feature.spec.md 或 SPEC-feature.md。规范与所描述的代码放在一起:项目范围用根目录 SPEC.md,应用范围用 apps/foo/SPEC.md,包范围用 packages/bar/SPEC.md。避免 spec/、docs/specs/、docs/plans/ 目录。计划文档是临时的,持久决策应并入对应 SPEC.md 并删除计划文档。规范过长时,可加 TOC 链接同目录的辅助文件(如 ./commands.spec.md),辅助文件放在 SPEC.md 旁边而非子目录。
内容:自由格式 Markdown,无固定模板、无 YAML frontmatter、无强制章节顺序,但必须包含:问题与方案(先说问题)、领域模型(类型、关系、数据流;追溯性规范从代码推导)、带 REQ-* ID 的需求(格式 REQ-{DOMAIN}-{NNN},只追加不重编号,可测试可追踪)、不变量、非目标(明确范围边界)、验收标准(用 Markdown 清单而非散文)。风险标签和测试追踪在条件满足时添加,测试追踪在 TDD 中或之后补充。
编写规则:基于证据,写前先读代码,不臆造行为、签名或路径;主张强度要与校验强度匹配,过度声称(如示例中可被评论、字符串字面量、遮蔽绑定、计算路径等反例在 60 秒内推翻)应改为收紧校验、收窄表述或记为待办;追溯性规范同样有效,从实际实现提取需求,把不一致记为待办而非静默遗漏。变更策略:未经用户明确指示不得修改规范;发现规范与实现漂移时立即提出,由用户决定改规范还是改代码。规范回答是什么和为什么,计划回答怎么做和何时做,计划是临时的。
生命周期:创建时进入 ADF SPEC gate,确定位置、读取现有文件并找出缺口、确保必需元素齐全;行为变化时更新规范,新增 REQ-* 只追加不重编号,测试写成后补测试追踪,同时出现规范与实现时交叉核对并暴露漂移;功能移除时删除或归档其 SPEC.md,不留描述已删除行为的过期规范。