用途:把设计文档的阶段计划升级为机器可验证的阶段契约(spec-kit 模式),每阶段一份 docs/design/stage-specs/S{N}.md,由 stage-gate 逐条执行。spec 是阶段契约(DoD/网格/边界),不是任务分解;任务分解交由 writing-plans。适用时机:阶段开工前(如「写 S{N} spec」「回填阶段 spec」「S2 定稿」);设计 §6 分阶段实施计划变更后,受影响阶段的 spec 需同步。
输入与结构:输入为设计文档 docs/design/intent-confirmation-domain-design.md(§6 阶段行 + 相关行为规范 + 契约)、模板 docs/design/stage-specs/README.md,以及 docs/decisions/、docs/tests/coverage-matrix.md 等既有资产。模板固定五节:DoD(机器可验证断言)、TDD 网格、产出物、边界(不做)、头部来源与开工日期,不得增删。
DoD 写作规则:每条须可被 stage-gate 直接执行——完整命令(如 npx vitest run)或可验证行为断言加承载它的测试文件路径;禁止散文式「完成 XX」;命令引用不复制门禁输出;计数给下限(如「≥N 条」)或预期总数;状态类断言逐条列出;嵌套子断言逐条拆开。TDD 网格按功能一行,含规范断言(标来源小节)、失败测试(文件名与契约用例清单)、实现、重构。产出物为可勾选的文件/模块/测试清单,并与 .handoff/ 的 actions 槽同步,仅引用 spec 路径不复制。边界节每条一行,明确排除项,来源为设计 §6 或阶段裁定(裁定→ADR→spec 引用)。
分工与限制:stage-gate 是 spec 的消费者,DoD 不可执行则 spec 返工;decision-log 负责 ADR,spec 只引用编号;project-handoff 负责 .handoff/ 结构与写命令参数面。完成标准包括五节齐全、DoD 可执行、TDD 网格先行、.handoff/ 已同步、DoD 变更由 ADR 记录。反模式含散文式断言、复制门禁输出、DoD 与网格脱节、缺失边界节、定稿后不回写 .handoff/。具体写命令参数以 project-handoff 为准,本资料未提供其参数细节。