文档书写规范

本文件受项目宪法 §7 管辖；修改须按宪法 §7 随评审流程走。唯一权威来源，任何 Spec 不得另立规则。

Spec 文档模板

每份 Spec 至少包含以下章节（不适用的章节删除，不留 "N/A"）：

  1. 概述：背景、目标、范围（含明确"不做的事"）
  2. 需求：用户故事按 P1/P2/P3 排序，每条附 Why this priority 与 Independent Test（P1 单独做完必须是能运行的 MVP）；功能需求 FR-XXX 编号，每条可独立测试，并把砍掉的范围写进 FR（如"支持 X（v1）不支持 Y"）；澄清标记 [NEEDS CLARIFICATION] 不超过 3 个，优先级 scope > security > UX > technical（技术选型不是澄清项，属 plan 阶段）
  3. 验收标准：SC-XXX 编号，四条硬标准——可量化（带数字）、技术无关（不提框架/语言/数据库/工具）、用户视角（不懂技术的 PM 可直接验收）、可验证；边界条件（断网、超时、非法输入）写入 Edge Cases
  4. 假设：只写合理默认行为，不写技术选型
  5. 关键实体：仅涉及数据时填写；只写业务定义与关系，不写字段类型/索引/DDL
  6. 设计：描述用户可观察的业务流程与异常分支，不包含技术架构和代码结构
  7. API 与数据：描述业务交互的输入、输出及实体关系；具体接口路径、传输协议、字段类型及技术模型由 Plan 与 contracts 承接
  8. 提交前自查：全文搜技术栈名（命中即改）；搜 should/最好/考虑（命中即改）；每条 FR 能直接写成一条测试用例；每条 SC 可交由 PM 验收

文档文件命名

<主题>-spec-<序号>.md（如 auth-spec-001.md）；草稿加 -draft-<序号> 后缀；变更/选型提案加 -proposal-<序号> 后缀。

模块/仓库命名

小写字母 + 短横线（如 lab-edu-core），避免私有缩写。

API 路径约定

/api/v1/<资源>/[<子资源>]；资源名使用小写复数，REST 风格但不强制。

开发工作流规范

plan 产物（plan.md）

  • 必须含：Summary / Technical Context / Constitution Check / Project Structure / Complexity Tracking / Phase 0/1 产物。
  • Technical Context：AI 推断选型 MUST 标 [INFERRED]；research.md 中每个决定必有 Decision / Rationale / Alternatives，且 Alternatives 至少 2 个并写明被否理由。
  • Constitution Check：机械检查表（原则 | 具体的 Gate 问题 | 通过/偏离/违反三档 | Evidence 指向文件路径）；设计前后各查一次；违反项入 Complexity Tracking，每项记录"试过的简单方案 + 至少 2 个被否更简方案"。
  • Project Structure 只保留 1 个选项并展开真实路径（出现 "Option 1/2/3" 视为不合格，打回）。
  • data-model.md：只写业务约束、验证规则与状态机，不出现 SQL DDL（CREATE/ALTER/DROP/INDEX/REFERENCES/DEFAULT）。
  • quickstart.md：每个场景含 Prerequisites / Steps / Expected output / Validation，命令可直接执行，预期输出可断言。
  • 不适用的节删除，不留 "N/A"。

tasks 产物（tasks.md）

  • 每条格式：- [ ] TXXX [P?] [USx?] 描述（含文件路径），缺一视为不合格（Setup/Foundational/Polish 阶段无 [Story] 标签）。
  • 颗粒度：一个文件 = 一条 task（跨文件 service 除外），一个 US 约 6~8 条；禁止 "加 import" / "加 docstring" 级原子 task；AI 拿到 task 无需再问问题。
  • 依赖：US 之间独立（删 US2 不影响 US1 跑通）；非并行 task 未标 depends on TXXX 视为不合格；跨 US 依赖只扩展不重构。
  • [P] 标记仅当"不同文件 + 无未完成依赖"；未标 [P] 的 task 至少有 1 个依赖。
  • Tests 段仅当 spec/宪法显式要求测试（TDD、覆盖率门禁等）时出现，并注明来源（per constitution / per spec FR-XXX）。
  • Final Phase 不超过 10 条，不得放入对其他 feature 也适用的项目级基建（监控、CI 等走单独 spec）。
  • 交付策略按团队规模选：1-2 人用 MVP First 或 Incremental；3+ 人可用 Parallel Team。

implement 阶段纪律

  • ① 实现启动前 MUST 加载全部设计文档（plan / tasks / data-model / contracts / research / 宪法 / quickstart），漏读视为违规。
  • ② 对既有配置文件（.gitignore / .dockerignore / README.md / .github/workflows/ 等）只检测后追加，追加处标注 [SPEC-KIT APPENDED 日期]，禁止整体重写覆盖。
  • ③ 每条任务完成立即标 [X] 并跑验证命令，失败标回 [ ] 并停止；禁止一次批量标记 3 条以上 [X]。
  • ④ 阶段顺序固定 Setup → Tests → Core → Integration → Polish，阶段间以真实可执行命令（build / 启动 / quickstart 场景）设门禁，命令失败必须 halt。
  • ⑤ 完成报告含四表：任务完成、Spec 符合度、宪法符合度、测试覆盖；缺项打回。
  • ⑥ 实现阶段发现的 spec 遗漏：禁止当场拍板，MUST 写 ADR（docs/adr/）+ 同步 spec amend + 修正 tasks.md 三处同步。

变更记录

2026-10-29 整稿评审通过后澄清 Spec 模板第 6、7 项，保留原章节并明确与 Plan/contracts 的职责分工；其他规则不变。批准依据见 docs/agents/ratification-record-001.md。