SpecCanon

Spec-Driven Development 框架 —— 让 AI 始终从准确的系统全景出发

Change specs are temporary; domain specs are canonical.

什么是 SpecCanon

SpecCanon 是一套面向 AI Coding Agent（如 Claude Code）的 Spec-Driven Development (SDD) 方法论框架。

核心理念：先文档后代码，人做判断题，AI 做填空题。

SpecCanon 的本质是一个文档状态机：每份 Spec 文档是一个状态节点，状态转移由人触发，AI 负责生成状态内容。通过持续维护 Domain Spec 作为系统行为的单一事实来源（Single Source of Truth），让 AI 在每次开发时都拥有准确的系统全景。

核心机制

三层文档体系

| 层级 | 文件 | 生命周期 | 职责 | |---|---|---|---| | 系统级 | domains/README.md | 持续更新 | 域间关系全景 | | 系统级 | domains/<domain>/domain_spec.md | 持续累积 | 系统当前行为（Canon） | | Change 级 | change-xxx/00_context~04_test_spec | 单次生命周期 | 本次变更做了什么 | | 项目级 | SKILL.md / AI_CHANGELOG.md | 持续累积 | 团队学到了什么 |

闭环演化

domain_spec.md（系统正典）
      │
      │ 新 Change 启动 → 读取系统现状
      ▼
  00_context → 01_requirement → 02_interface → 03_implementation → 04_test_spec
      │
      │ Change 完成 → 关键信息回填
      ▼
domain_spec.md（演化更新）

每次 Change 开发都从 Domain Spec 出发，完成后将变更归档回 Domain Spec，形成知识的持续累积。Domain Spec 越完善，后续开发的上下文越精准，AI 的产出质量越高。

人机分工

| 角色 | 职责 | 类比 | |---|---|---| | 🧑 人（研发工程师） | 决策、审阅、判断对不对 | 做判断题 | | 🤖 AI（Coding Agent） | 生成、补全、确保全不全 | 做填空题 |

安装

npm install -g spec-canon

或直接通过 npx 使用（无需全局安装）：

npx spec-canon --help

快速开始

我要开始一个新项目

→ 阅读 guide/04_new_project_sop.md，然后使用 spec-canon prompt guide 查看决策树

我要在已有项目中开发新需求

→ 先运行 spec-canon change start --goal ... 建立 active change（待命名状态），运行 ctx 后 AI 会建议 change 名，再用 change start -g <goal> -c <name> 确认命名；然后用 spec-canon change next 查看候选步骤

我要为已有项目引入 SDD

→ 阅读 guide/05_iterative_project_sop.md 的冷启动策略，然后使用 spec-canon prompt list --stage iterative

我要给已初始化项目补齐新版本骨架

→ 运行 spec-canon sync，只补缺失文件，不覆盖已有内容

常用命令

spec-canon init
spec-canon init --domain auth
spec-canon sync                    # 给已初始化项目安全补齐新骨架
spec-canon change start -g @docs/prd.md
spec-canon change status
spec-canon change next
spec-canon change -d /path/to/project status
spec-canon change clear
spec-canon prompt list
spec-canon prompt show <id>
spec-canon prompt guide

change next 会根据当前 active change 的文档进度输出候选步骤列表，默认采用宽松模式：保留 iface 和 domain-sync 候选，让用户自己决定 next。若确认没有接口变化或无需系统级归档，可通过 --no-contract-change、--no-system-change 收窄候选。

change 还支持父命令选项 -d, --dir <path> 指定目标项目目录，默认当前目录。由于 change next 已用 -d 表示 --domain，指定目录时请写在子命令前：spec-canon change -d /path/to/project next。

sync 会在项目内写入 spec-canon/.template-manifest.json，用于记录当前骨架状态，为后续更智能的升级能力预留基础。若有文件需要人工比对，CLI 会同时输出参考模板路径和建议的 code --diff / diff -u 命令，方便直接对照已安装包中的模板。

文档结构

ROADMAP.md                   ← CLI 演进计划（单一来源）
docs/
├── SOP.md                    ← 导航索引（入口）
├── guide/                    ← 方法论（一次性阅读）
│   ├── 00_introduction.md        SDD 框架综合介绍（对外发布用）
│   ├── 01_claude_md.md           CLAUDE.md 书写指南
│   ├── 02_spec_overview.md       三层文档体系总览
│   ├── 03_spec_documents.md      各文档详解
│   ├── 04_new_project_sop.md     新项目 SOP
│   ├── 05_iterative_project_sop.md  迭代项目 SOP
│   └── 06_domain_splitting.md       子域分拆规则
├── prompts/                  ← 提示词文件（CLI `spec-canon prompt` 数据源）
├── reference/                ← 速查表（随时查阅）
└── templates/                ← Spec 模板（7 个）

ROADMAP

见 ROADMAP.md。当前版本已支持安全补齐，后续版本会在 manifest 基础上逐步增加“只刷新未被修改的文件”和 --check 等能力。

为什么叫 SpecCanon

Canon（正典）——在 SpecCanon 体系中，domain_spec.md 是系统行为的权威来源。每次变更开发完成后，关键信息回填到 Domain Spec，使其成为持续演化的系统正典。

• Spec 驱动每一次变更
• Canon 保存系统的真相

Specs drive change; Canon preserves the system.

许可证

MIT