06 - 文档体系设计
1. 定位
文档体系是项目的结构化知识库，为 AI 和人提供可检索、可消费的项目上下文。
设计理念三层递进：
- Context Engineering — 文档是 AI 的上下文燃料，结构决定检索效率。每类文档有固定骨架，AI 无需理解全文即可定位关键信息
- Spec-Driven — 先定义再实现。spec 在实现后继续维护（Spec-anchored），而非用完即弃
- Knowledge Accumulation — 决策、调研、踩坑持续沉淀为可复用知识资产，通过 /checkpoint 统一路由归档
2. 知识模型
AI 在不同任务下需要不同知识切片。7 种场景覆盖完整开发周期：
| # | AI 场景 | 需要的知识 | 来源文档 | 加载策略 |
|---|---|---|---|---|
| 1 | 开始会话 | 项目身份 + 规则 + 当前状态 | CLAUDE.md + HANDOFF.md | 自动加载 |
| 2 | 实现功能 | 需求意图 + 功能现状 + 约束 | spec + features + approved-deps | 按需加载 |
| 3 | 技术决策 | 过去决策及理由 + 调研结论 | adr/ + research/ | 按需检索 |
| 4 | 规划实施 | 架构全貌 + 已有方案 | CLAUDE.md + plans/ | 按需加载 |
| 5 | 调试问题 | 历史踩坑模式 | troubleshooting/ | 按症状 grep |
| 6 | 对接外部 | 协议细节 + 接口约束 | api/ | 按需加载 |
| 7 | 了解变化 | 近期变更摘要 | CHANGELOG.md | 按需加载 |
3. 目录结构
project/
├── CLAUDE.md # [自动加载] 项目身份 + 架构 + 规则
├── HANDOFF.md # [自动加载] 会话状态（覆写制）
├── CHANGELOG.md # 变更留痕（里程碑级）
│
└── docs/
├── README.md # 知识索引（所有文档的导航入口）
│
│ ── 契约层（定义"建什么、怎么建"）──
├── spec.md # 产品需求规格 ← /spec
├── prd.md # 工程规格（字段级） ← /prd
├── product-spec.md # 产品结构契约 ← /product-design
├── design-spec.md # 设计规范契约 ← /product-design
│
│ ── 状态层（反映当前状态，持续更新）──
├── features.md # 功能全景清单 ← /features
├── approved-deps.md # 依赖白名单 ← /takeover
│
│ ── 知识层（持续累积，可检索复用）──
├── plans/ # 技术方案 & 阶段计划
│ ├── README.md # 索引（含状态标记）
│ └── {slug}.md # ← /plan, /checkpoint
│
├── adr/ # 架构决策记录
│ ├── README.md # 索引
│ └── {NNN}-{slug}.md # ← /checkpoint
│
├── research/ # 技术调研
│ ├── README.md # 索引（按领域分类）
│ └── {YYYY-MM-DD}-{slug}.md # ← /tech-research, /checkpoint
│
├── troubleshooting/ # 踩坑知识库
│ ├── README.md # 索引（按领域分类）
│ └── {YYYY-MM-DD}-{slug}.md # ← /debug, /checkpoint
│
├── api/ # 外部系统对接文档
│ └── {service}.md # 手动或 AI 辅助
│
└── archive/ # 归档（历史版本、早期方案）
# AI 不主动加载，仅按需查阅三层说明
| 层 | 职责 | 特征 | 文档 |
|---|---|---|---|
| 契约层 | 定义"建什么、怎么建" | Spec-anchored 持续维护（见下方"契约层组织方式"） | spec, prd, product-spec, design-spec |
| 状态层 | 反映项目当前状态 | 活文档，频繁更新 | features, approved-deps |
| 知识层 | 沉淀项目知识资产 | 持续累积，有索引，可检索复用 | plans, adr, research, troubleshooting, api |
| 归档 | 保留历史版本 | AI 不主动加载，仅按需查阅 | archive/ |
契约层组织方式
默认每类契约一份根文件（spec.md、prd.md），适合大多数项目。但当项目天然有多份并列契约（如内容站的多个独立规范：内容管线、设计系统、分发策略），可用 specs/ 目录组织，每份规范补 Status/Date 元数据头部。判断标准：如果几份文档各自独立演进、互不取代，就是并列关系，用目录；如果是同一份规范拆分过大，走"文件→目录升级制"。
编号体系的语义约束
当产品契约文档采用 docs/design/NN-名.md 编号组织（适用于 ≥6 份并列契约的场景），编号段必须绑定层级语义而非创建顺序：
| 编号段 | 层级 | 典型文档 |
|---|---|---|
| 01-02 | L0 宪法层 | spec, constitution |
| 03-05 | L1 产品契约层 | product-spec, user-flows, design-spec |
| 06-08 | L2 工程规格层 | prd, features, sitemap |
| 09-11 | L3 实施规格层 | tech-stack, ops-spec, test-spec |
编号 reserved 占位不复用：如果跳过某编号（如 011 reserved 计划新功能），后续新增从下一个空号起（如 013），不复用 011。此规则避免"中段插入引起后续顺移"的脆弱性。
实证：prompt-hub 项目用此规则组织 11 篇编号契约 + 12 份 ADR，跨 6 个月迭代未发生编号顺移。
子目录存在标准
每个子目录的存在理由：会持续累积多个文件，且需要索引来组织。不满足此标准的一律为根目录单文件。
archive/ 归档目录
docs/archive/ 存放被取代的历史文档：spec 早期版本、废弃的方案、会话存档等。
归档标准：文档已被新版本完全取代，但保留有追溯价值（如理解决策演变过程）。如果无追溯价值，直接删除（历史在 git 中）。
archive/ 不需要 README 索引，AI 不主动加载此目录。
Frontmatter 契约
所有 docs/ 下文档建议有 yaml frontmatter 元数据，AI 召回精度与文档治理能力强依赖此元数据：
| 字段 | 必选 | 取值 |
|---|---|---|
type | ✅ | spec / prd / adr / plan / research / troubleshooting / design-doc / ... |
version | 推荐 | v0.1 起；patch / minor / major 见 §7 |
status | ✅ | draft / active / ratified / superseded / pre-code |
audience | 推荐 | [human] / [ai] / [human, ai] / [ai, claude-design]（外部 AI 工具） |
author | 推荐 | human（人主笔，AI 禁起草） / co（共创） / ai（AI 主笔人审） |
description | ✅ | 一句话摘要，AI 召回的核心依据 |
related | 可选 | wikilink 列表 [[文件名]] |
description 字段是 AI 召回精度的最大杠杆——写得越具体可区分，召回准确率越高。反例：description: 项目文档 → 召回不准；正例：description: 手动 AI 编程仪表盘的工程契约——数据模型/状态机/升级回滚/Boundaries/安全字段。
author 字段约束行为：标 author: human 的文档（如 spec / constitution）AI 不得擅自起草，可建议修订但必须人审拍板。
文件→目录升级制
任何单文件超过 500 行时，升级为同名目录：
docs/prd.md (< 500 行) → 保持单文件
docs/prd.md (> 500 行) → 升级：
docs/prd/
├── README.md ← 概述 + 索引
├── {module-a}.md ← 按模块拆分
└── {module-b}.md拆分维度：按 AI 的工作上下文，不按文档结构（overview、tech-stack）。具体维度取决于文档类型：
- spec（产品规格）→ 按业务模块（device、auth、mission）
- prd（技术方案）→ 按技术域（database、adapter、websocket、alert）
- 判断标准：AI 处理某个任务时，会自然加载哪一块？那就是拆分边界
例外条款 — 强引用图谱场景
当文档主要内容是「实体间强引用关系图谱」（mermaid 关系图 + 关键关系约束表 + 跨实体状态机）时，500 行阈值不适用——拆分会破坏 AI「一次性载入全部 schema」的工作上下文。
典型场景：PRD §数据模型有 ≥8 个实体且通过 mermaid graph 互相引用、共享 enum 词汇表、约束跨实体定义。此时即便超 1000 行也应保持单文件。
判断口诀：拆分后 AI 是否需要并行加载多个子文件才能理解一处约束？是 → 不拆。
实证：prompt-hub 06-prd.md 1166 行单文件，§数据模型 11 个实体（Modifier / Composition / Macro / Scene / Phase / AlignmentPhrase / SOP / UsageRecord 等）通过 mermaid 三轴关系图互相约束，拆分会让 AI 失去整体 schema 视图。
Pre-code 阶段例外
项目处于 pre-code（0 LOC 或未通过 M0 技术验证）阶段时，部分文档的字面要求不可达，允许降级形态：
| 文档 | 降级形态 | 升级触发 |
|---|---|---|
tech-stack.md | status: pending-adr stub（物理约束清单 + 待决策矩阵 + 升 v1.0 条件） | 所有核心 ADR Accepted |
CLAUDE.md 关键命令 | TBD 占位 + 回填时机说明 | 首次依赖安装成功 |
prd / ops-spec / test-spec 中的数字 | 标 🎯 目标态（见 25-文档体系演化机制 §4） | 首次实测，升 📊 基线 |
constitution.md 链接 ADR | 首版 ratified 时允许无 ADR | 首次修订必须补 ADR |
强行让 pre-code 阶段满足"建仓后"才合理的字面要求，会写出违反"手写而非自动生成"原则的伪规则。详细降级规范见 25-文档体系演化机制 §3。
4. 格式契约
每类文档的固定骨架，确保 AI 可预测地解析。
4.1 ADR（架构决策记录）
docs/adr/{NNN}-{slug}.md，三位编号递增：
# ADR-{NNN}: {决策标题}
Status: Accepted | Superseded by ADR-{NNN}
Date: YYYY-MM-DD
## 背景
[什么问题触发了决策，1-3 句]
## 决策
[做了什么决定，1-2 句]
## 备选方案
- {方案 A} — 未选，因为 {原因}
- {方案 B} — 未选，因为 {原因}
## 影响
[正面和负面后果]触发条件（任一满足）：技术栈选择、架构模式变更、关键数据模型设计、推翻过去方案。
核心价值：记录"为什么没选别的"——防止 AI 重新建议已否决方案。
不需要 ADR：日常编码决策、UI 组件选择、命名风格。
4.2 Troubleshooting（踩坑知识库）
docs/troubleshooting/{YYYY-MM-DD}-{slug}.md：
# {问题简述}
Date: YYYY-MM-DD
Tags: {领域标签，如 flutter, mqtt, map, deploy}
## 症状
[看到了什么现象]
## 根因
[实际原因是什么]
## 解法
[怎么修的]
## 防御
[怎么防复发——加了什么规则/测试/约束]归档门槛（三问法，任一为是）：定位花了 30+ 分钟？根因不在报错直接指向？同类问题可能复发？
索引 README.md 按领域分类（Flutter / API / Database / Deploy 等），不按时间排序。AI 调试时 grep tags 定位相关经验。
4.3 Plans（技术方案 & 阶段计划）
docs/plans/{slug}.md，语义化命名：
# {方案名称}
Status: draft | approved | active | paused | done | superseded by [{替代方案}](./{slug}.md)
Progress: 3/8
Date: YYYY-MM-DD
Feature: USR-02 ← 可选，关联 features.md
## 目标
[这个方案要解决什么]
## 任务清单
- [x] 已完成的步骤 (`涉及的文件`)
- [ ] 待完成的步骤
## 关键决策
[重大选型摘要，详细理由链接到 adr/]进度追踪：Progress 行由 /checkpoint 自动统计 - [x] 数量更新。Feature 字段可选，关联 features.md 的功能 ID，plan 完成时提示同步功能状态。
粒度门槛：跨多个会话的实施方案才独立成文档；单会话内的执行清单放 HANDOFF.md Session Tasks。临时任务未完成项 > 5 且需跨会话时，/checkpoint 建议升级为正式 plan。
状态流转：draft → approved → active → done（正常路径）。active → superseded（被新方案替代，标注替代者链接）。active → paused（暂时搁置，记录原因）。draft 和 approved 为可选前置状态——需要审批流程的项目使用，小项目可直接从 active 开始。
4.4 Research（技术调研）
docs/research/{YYYY-MM-DD}-{slug}.md：
# {调研主题}
Date: YYYY-MM-DD
Tags: {领域标签}
## 结论
[一句话结论，放最前面——AI 快速提取用]
## 背景
[为什么要调研]
## 详细分析
[对比、评估、数据]
## 参考
[来源链接]结论前置：AI 加载调研文档时，读第一段就能判断是否需要继续深入。
4.5 依赖白名单
docs/approved-deps.md：
# 依赖白名单
引入新依赖前必须检查此列表。不在列表中的依赖需要评估后添加。
## 核心框架
- next — React 全栈框架
- typescript — 类型系统
## 禁止使用
- moment.js — 用 date-fns 替代
- lodash（整包）— 用原生方法或 lodash-es 子模块5. 知识沉淀机制
/checkpoint 作为统一沉淀出口
对话是知识产生的地方，/checkpoint 是知识持久化的统一收口点。执行时：
- 知识提取 — 回顾对话，识别值得持久化的内容，列出归档清单
- 进度更新 — 扫描活跃 plan，勾选已完成任务，更新 Progress 行；plan 全部完成时提示更新 features.md
- 知识归档 — 确认后将各类知识路由到正确位置（plans/、adr/、research/、troubleshooting/ 等）
- HANDOFF 覆写 — 完全覆写为当前状态（含 Active Plan 引用 + Session Tasks 清单），历史在 git 中
- 统一提交 — git commit 所有变更
详见 /checkpoint Skill 和 22-项目知识沉淀机制。
即时归档
/tech-research 和 /debug 执行过程中仍可直接产出 research/ 和 troubleshooting/ 文件。/checkpoint 是补充性兜底——捕获自由对话中产生、未通过专门 Skill 归档的知识。两者不冲突，同一内容不重复归档。
检索协议
在项目 CLAUDE.md 中写入：
## 知识检索规则
- 技术调研前先搜索 docs/research/（避免重复调研）
- 调试问题前先搜索 docs/troubleshooting/（避免重复踩坑）
- 技术决策前先搜索 docs/adr/（避免重复评估）
- 新增依赖前先检查 docs/approved-deps.md（避免引入禁用包）
- 检索方式：grep tags 或 title 关键词规模控制
- 每个目录不超过 50 个文件，超过时按年份归档子目录
- 单个记录不超过 200 行，超过说明应该拆分或简化
6. 交叉引用
文档间通过相对路径互相引用，形成知识网络：
- Plan → ADR：
详见 ADR-003（实证：tools 项目 ADR-003 选择 Flutter，文件在该项目仓内） - ADR → Research：
基于 Flutter 地图调研（实证：tools 项目 research/2026-03-09-flutter-map，文件在该项目仓内） - Troubleshooting → Plan：
出现在 P1a 阶段实施过程中（实证：tools 项目 plans/p1a-outside-in，文件在该项目仓内） - CLAUDE.md → 契约文档：
产品规格见 docs/spec.md
交叉引用不强制，但鼓励在上下文相关时添加。
7. 生命周期
| 文档 | 创建时机 | 消费场景 | 退役方式 |
|---|---|---|---|
| spec.md | /spec 产出 | 实现功能时引用 | 原地更新（Spec-anchored） |
| prd.md | /prd 产出 | 实现复杂功能时 | 原地更新 |
| plans/ | /plan 或 /checkpoint | 执行期间引用 | done 或 superseded（不删除） |
| adr/ | /checkpoint 或手动 | 做类似决策时检索 | superseded（不删除） |
| research/ | /tech-research 或 /checkpoint | 决策/选型时引用 | 长期保留，标注时效性 |
| troubleshooting/ | /debug 或 /checkpoint | 调试时 grep | 长期保留 |
| features.md | /features | 每次会话参考 | 持续更新 |
| approved-deps | /takeover 初始化 | 加依赖时检查 | 持续更新 |
| CHANGELOG | 功能/里程碑完成时 | 了解近期变化 | 持续追加 |
| HANDOFF.md | /checkpoint 覆写 | 下次会话恢复 | 每次覆写，历史在 git |
| archive/ | 文档被新版取代时 | 追溯决策演变 | 长期保留，不主动加载 |
8. 文档自动化
通过 CLAUDE.md 驱动
在 CLAUDE.md 中加入规则：
## 文档规则
- 新增模块/目录时更新 CLAUDE.md 的"架构"章节
- 新增开发命令时更新 CLAUDE.md 的"命令"章节
- 新增依赖时更新 docs/approved-deps.md
- 重大架构决策时创建 docs/adr/ADR-xxx.md通过 /doc Skill 触发
代码变更后运行 /doc，AI 自动检查哪些文档需要更新。详见 02-Skills技能体系。
通过 CHANGELOG.md 留痕
里程碑级变更摘要，不是 commit 级别：
## YYYY-MM-DD
- feat: {功能描述}
- fix: {修复描述}
- refactor: {重构描述}9. 现有项目迁移
已有文档的项目采用本体系时，按以下步骤迁移：
- 盘点 — 列出全项目的文档（包括 output/、根目录等非 docs/ 位置），按三层分类（契约/状态/知识），识别历史版本
- 创建骨架 — 建
docs/及子目录（plans/、adr/、research/、troubleshooting/、api/、archive/），各子目录创建 README 索引 - 迁移文件 —
git mv保留历史，知识层文件统一英文 slug 命名，research 文件加日期前缀（日期从git log --diff-filter=A推断） - 归档历史 — 被取代的旧版本（含 Word/PDF 等二进制格式的历史迭代）移入
docs/archive/（可保留原目录结构，如archive/github/） - 元数据规范化 — 为所有 plans 补 Status/Progress/Date 头部，specs 补 Status/Date。这是迁移中工作量最大的步骤，但不补元数据则 plans 的追踪价值大打折扣
- 补建缺失文件 — 创建 docs/README.md（三层索引）、features.md（从已有功能提炼）、approved-deps.md（从 package.json 提炼）、CHANGELOG.md（从 git log 提炼里程碑）
- 更新引用 — CLAUDE.md 路径 + 架构树 + 文档目录树 + 知识检索规则 + 文档维护规则；HANDOFF.md 路径引用
- 拆分超大文件 — 超过 500 行的文档按"文件→目录升级制"拆分
注意事项：
- 迁移是纯结构调整，不修改文档内容，风险低
- CLAUDE.md 和 HANDOFF.md 的路径更新必须与文件迁移同步，否则 AI 下次会话找不到文档
- plans/ 用英文 slug 命名（终端路径友好），文档内容保持原语言
- 目录名映射：项目中常见的
decisions/应迁移为adr/，散落在其他位置的 SQL 迁移脚本归入项目原有的sql/目录而非留在 docs/
实测案例
| # | 项目 | 特征 | 存量文档 | 关键发现 |
|---|---|---|---|---|
| 1 | xiaoxi | IoT 应用，Flutter + MQTT | ~10 份 | 拆分维度从"按业务模块"修正为"按 AI 工作上下文"；检索协议补 approved-deps |
| 2 | jianfen | 中小项目 | ~5 份 | 盘点范围扩展至全项目（非 docs/ 位置）；归档覆盖二进制格式 |
| 3 | skillnav | 内容站，Next.js + 运营密集型 | 46 份 | Plans 状态枚举需 draft/approved 前置态；元数据规范化是最大工作量；契约层可用 specs/ 目录组织并列规范 |
10. 文档站点发布（推荐）
当项目需要对外展示文档时，推荐采用 Git 集成 + 静态站点生成器 的方式：
| 要素 | 推荐选项 | 说明 |
|---|---|---|
| 站点生成器 | VitePress / Nextra / Starlight | Markdown 原生支持，零配置上手 |
| 托管平台 | Cloudflare Pages / Vercel / Netlify | 均支持 Git 集成，推送即部署 |
| 部署触发 | Git 集成（自动） | 优先于手动 CLI 部署 |
关键原则：源文件留在仓库内（docs/ 唯一真相源）；推送即发布；中文路径转英文 slug。
何时需要：面向团队/外部的文档、超过 5 篇需要导航搜索、需要密码保护。个人小项目 docs/ + GitHub 浏览即可。
11. 与其他子系统的关系
文档维护按三分法切分：确定性校验交机器，语义判断交 Skill，内容创作与裁决归人。
CLAUDE.md：文档体系的入口，AI 的主要知识来源
Hooks + CI：承担文档治理的确定性子集——死链 / frontmatter schema /
索引一致 / 编号连续 / 计数与状态一致性 / 版本指针
（由 doc-governance 组件执行，pre-commit + CI 双挂载）
Skills：承担语义判断子集——/docaudit（该不该写 ADR、架构描述是否
过期、文档边界是否漂移）；/checkpoint 统一知识沉淀
人：承担内容创作与裁决——规则条文、spec/constitution 主笔、bump 拍板
MCP：不直接参与（文档是本地文件操作）修订说明（2026-07-02，随上游方法论 v1.4 同拍）：旧版断言「Hooks 不直接参与文档维护（文档更新不是确定性操作）」是过度概括（盲区 1，P0）——本仓 pre-commit 已在拦截确定性文档违规，docaudit 中的索引一致 / 编号连续 / 断链 / frontmatter 完整性检查全是纯确定性操作。三分法与上游 v1.4 §10 的 doc-governance 组件形态互为表里，详见
docs/methodology-v1.4-proposal.md§3。
关联文档：01-CLAUDE.md 设计 | 02-Skills 技能体系 | 16-功能清单体系 | 22-项目知识沉淀机制 | 23-产品设计契约 | 25-文档体系演化机制