SpecCanon 是 SDD 方法论的 CLI 工具与操作手册。把文档变成 AI 可依赖的系统上下文，让 AI Coding Agent 的产出质量显著提升。
用 AI 写代码已经不新鲜了，但用 AI 写出"对的代码"仍然困难。
AI 只看到当前文件，不了解系统全局，生成的代码与已有模块冲突。
口头描述需求后 AI 开始编码，过程中意图逐渐偏离原始目标。
上次踩过的坑没有留痕，下次换一个 session 又犯同样的错。
改了签到模块的接口，没有意识到积分模块也在调用。
| 维度 | 没有 SDD | 有 SDD |
|---|---|---|
| AI 的上下文 | 当前文件 + 口头描述 | 结构化的系统全景 + 变更链 |
| 变更意图 | 容易在对话中漂移 | 锚定在 01_requirement.md |
| 历史经验 | 散落在聊天记录和个人记忆 | 沉淀在 SKILL.md 和 domain_spec |
| 跨模块影响 | 靠人脑记忆 | 域间关系图自动追踪 |
| 新人上手 | 读代码 + 问老人 | 读 domain_spec 即可了解现状 |
SDD 通过持续维护一套结构化的 Spec 文档体系来弥合知识断层。
需求取舍、架构选型由人负责；在明确约束下填充由 AI 负责。
| 角色 | 职责 | 类比 |
|---|---|---|
| 人（工程师） | 决策、审阅、判断对不对 | 做判断题 |
| AI（Agent） | 生成、补全、确保全不全 | 做填空题 |
每份 Spec 是一个状态节点，开发过程就是状态转移。文档即进度。
domain_spec.md
是系统行为的长期真相（正典），不是一次性的需求稿。每次变更完成后关键信息回填，使其持续演化。
各有不同的生命周期和职责，形成知识持续累积的闭环。
始终反映系统的当前行为，是 AI 生成上下文时的首要参考。
domains/README.md — 域间关系全景domain_spec.md — 业务域的长期真相5 份文档组成严格的依赖链，后者建立在前者的上下文之上。
00_context — 系统现状快照01_requirement — 需求规格与验收标准02_interface — 接口契约03_implementation — 实施计划04_test_spec — 测试策略跨越所有变更持续沉淀，让团队越来越聪明。
SKILL.md — 团队经验库，避免重复犯错AI_CHANGELOG.md — 技术决策留痕先对齐现状，再定义目标，再落实施工，再验证结果，最后回填知识。
不是所有任务都需要走完整流程。根据规模裁剪最小文档集，消除"文档负担"。
| 任务规模 | 最小文档集 | 归档回填 |
|---|---|---|
| 小 Bugfix | 仅 AI_CHANGELOG（追加一条） | 不回填 |
| 小需求 | 01_requirement（精简版）+ AI_CHANGELOG | 仅回填新增接口/规则 |
| 中等需求 | 01 + 02_interface + AI_CHANGELOG | 回填接口 + 业务规则 |
| 复杂需求 | 完整 00 → 01 → 02 → 03 → 04 + AI_CHANGELOG | 完整回填 + 检查跨域依赖 |
如果是，需要 00_context。复杂模块的改动不能跳过上下文。
如果是，需要 02_interface。接口契约是前后端的唯一真相。
如果是，需要归档回填 domain_spec。不回填，知识会消散。
spec-canon 帮你标准化执行 SDD 流程：初始化目录、管理变更、获取标准提示词。
# 初始化 SDD 目录结构 spec-canon init --domain auth spec-canon sync # 补齐新版本骨架 # 管理当前 change spec-canon change start -g @docs/prd.md spec-canon change status spec-canon change next # 提示词系统 spec-canon prompt list spec-canon prompt show req spec-canon prompt guide
# 1. 安装并初始化 npm install -g spec-canon # → 全局安装 spec-canon CLI spec-canon init --domain checkin # → 创建 spec-canon/ 目录树 + checkin 域骨架 # 2. 建立 active change，开始首个变更 # 新项目跳过 ctx，直接命名 change spec-canon change start -g @docs/prd.md -c feat-001-checkin # → 创建 active change 并确认命名为 feat-001-checkin spec-canon change next --type feat # → 列出当前候选 next prompts（feat 类型裁剪） spec-canon prompt show req # → 输出 req 提示词（自动替换 {{CHANGE}} 等变量） # → 将输出的提示词喂给 AI，生成 01_requirement.md # → 人工审阅 AC，Sign-off # 3. 依次生成设计文档 spec-canon prompt show iface # → 输出接口设计提示词，喂给 AI 生成 02_interface.md spec-canon prompt show impl-spec # → 输出实施计划提示词，喂给 AI 生成 03_implementation.md spec-canon prompt show test-spec # → 输出测试策略提示词，喂给 AI 生成 04_test_spec.md # 4. 编码执行 spec-canon prompt show impl # → 输出分步编码提示词，AI 按 03 中的步骤逐步实现 # 5. 审查 + 归档 spec-canon prompt show review # → 输出代码审查提示词，AI 审查改动并生成 AI_CHANGELOG 条目 spec-canon prompt show domain-sync # → 输出域回填提示词，AI 将关键信息回填到 domain_spec spec-canon change clear # → 清除当前 active change，准备下一个变更
# 路径 A：懒加载（推荐） # 第一个触碰某域的变更"顺手"创建 domain_spec spec-canon init # → 创建 spec-canon/ 目录树（已有文件不覆盖） spec-canon change start -g "修复认证模块重复登录导致的 session 异常" # → 创建 active change（待命名状态） spec-canon change next --type fix # → 列出 fix 类型的候选 next prompts spec-canon prompt show ctx # → AI 从 goal 出发扫描代码库并生成 00_context，建议 change 名 spec-canon change start -g "修复认证模块重复登录导致的 session 异常" -c fix-001-dup-session # → 确认命名后继续后续步骤；变更完成后归档时，创建首份 domain_spec # 路径 B：批量基线（有 1-2 天空档时） spec-canon prompt show domain-identify # → 输出域识别提示词，扫描代码库 spec-canon prompt show domain-setup # → 输出域目录创建提示词 spec-canon prompt show domain-base -d checkin # → 输出基线提示词，逐域生成 domain_spec
# CLI 新版本新增了模板或目录约定时 spec-canon sync # sync 的默认策略： # ✓ 只补缺失文件，不覆盖已有文件 # ✓ 已有文件与模板不同时，保留现状并提示人工比对 # ✓ 写入 .template-manifest.json
# 小 Bugfix → 直接修复 + AI_CHANGELOG # （无需提示词，修完后让 AI 追加 AI_CHANGELOG） # 中等需求 → 有接口变更时 spec-canon change start -g @docs/prd.md -c feat-003-bonus # → 创建 active change 并确认命名 spec-canon change next # → 列出候选 next prompts spec-canon prompt show req # → 输出 req 提示词，生成 01_requirement.md spec-canon prompt show iface # → 输出 iface 提示词，生成 02_interface.md spec-canon prompt show impl # → 输出 impl 提示词，分步编码 spec-canon prompt show review # → 输出 review 提示词，审查改动 + 生成 AI_CHANGELOG # 复杂需求 → 完整流程 spec-canon change start -g @docs/prd-cross-domain.md # → 创建 active change（待命名状态） spec-canon change next --type feat # → 列出 feat 类型的候选 next prompts spec-canon prompt show ctx # → 输出 ctx 提示词，生成 00_context.md，AI 建议 change 名 spec-canon change start -g @docs/prd-cross-domain.md -c feat-004-cross-domain # → 确认 change 命名 spec-canon change next # → 列出当前候选 next prompts spec-canon prompt show req # → 输出 req 提示词，生成 01_requirement.md spec-canon prompt show iface # → 输出 iface 提示词，生成 02_interface.md spec-canon prompt show impl-spec # → 输出 impl-spec 提示词，生成 03_implementation.md spec-canon prompt show test-spec # → 输出 test-spec 提示词，生成 04_test_spec.md spec-canon prompt show impl # → 输出 impl 提示词，分步编码 spec-canon prompt show review # → 输出 review 提示词，审查改动 + 生成 AI_CHANGELOG spec-canon prompt show domain-sync # → 输出 domain-sync 提示词，自动发现受影响域并回填 domain_spec