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 辅助

三层说明

层	职责	特征	文档
契约层	定义"建什么、怎么建"	项目级各一份，Spec-anchored 持续维护	spec, prd, product-spec, design-spec
状态层	反映项目当前状态	活文档，频繁更新	features, approved-deps
知识层	沉淀项目知识资产	持续累积，有索引，可检索复用	plans, adr, research, troubleshooting, api

子目录存在标准

每个子目录的存在理由：会持续累积多个文件，且需要索引来组织。不满足此标准的一律为根目录单文件。

文件→目录升级制

任何单文件超过 500 行时，升级为同名目录：

docs/prd.md (< 500 行)          →  保持单文件
docs/prd.md (> 500 行)          →  升级：
                                    docs/prd/
                                    ├── README.md       ← 概述 + 索引
                                    ├── {module-a}.md   ← 按模块拆分
                                    └── {module-b}.md

拆分维度：按业务模块/领域（device、auth、mission），不按文档结构（overview、tech-stack）。AI 按模块聚焦工作，拆分应匹配 AI 的上下文加载粒度。

4. 格式契约

每类文档的固定骨架，确保 AI 可预测地解析。

4.1 ADR（架构决策记录）

docs/adr/{NNN}-{slug}.md，三位编号递增：

markdown

# 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：

markdown

# {问题简述}
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，语义化命名：

markdown

# {方案名称}
Status: 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。

状态流转：active → done（正常完成）或 active → superseded（被新方案替代，标注替代者链接）。active → paused（暂时搁置，记录原因）。

4.4 Research（技术调研）

docs/research/{YYYY-MM-DD}-{slug}.md：

markdown

# {调研主题}
Date: YYYY-MM-DD
Tags: {领域标签}

## 结论
[一句话结论，放最前面——AI 快速提取用]

## 背景
[为什么要调研]

## 详细分析
[对比、评估、数据]

## 参考
[来源链接]

结论前置：AI 加载调研文档时，读第一段就能判断是否需要继续深入。

4.5 依赖白名单

docs/approved-deps.md：

markdown

# 依赖白名单

引入新依赖前必须检查此列表。不在列表中的依赖需要评估后添加。

## 核心框架
- 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 中写入：

markdown

## 知识检索规则
- 技术调研前先搜索 docs/research/（避免重复调研）
- 调试问题前先搜索 docs/troubleshooting/（避免重复踩坑）
- 技术决策前先搜索 docs/adr/（避免重复评估）
- 检索方式：grep tags 或 title 关键词

规模控制

每个目录不超过 50 个文件，超过时按年份归档子目录
单个记录不超过 200 行，超过说明应该拆分或简化

6. 交叉引用

文档间通过相对路径互相引用，形成知识网络：

Plan → ADR：详见 [ADR-003](../adr/003-why-flutter.md)
ADR → Research：基于 [Flutter 地图调研](../research/2026-03-09-flutter-map.md)
Troubleshooting → Plan：出现在 [P1a 阶段](../plans/p1a-outside-in.md) 实施过程中
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

8. 文档自动化

通过 CLAUDE.md 驱动

在 CLAUDE.md 中加入规则：

markdown

## 文档规则
- 新增模块/目录时更新 CLAUDE.md 的"架构"章节
- 新增开发命令时更新 CLAUDE.md 的"命令"章节
- 新增依赖时更新 docs/approved-deps.md
- 重大架构决策时创建 docs/adr/ADR-xxx.md

通过 /doc Skill 触发

代码变更后运行 /doc，AI 自动检查哪些文档需要更新。详见 02-Skills技能体系。

通过 CHANGELOG.md 留痕

里程碑级变更摘要，不是 commit 级别：

markdown

## YYYY-MM-DD
- feat: {功能描述}
- fix: {修复描述}
- refactor: {重构描述}

9. 文档站点发布（推荐）

当项目需要对外展示文档时，推荐采用 Git 集成 + 静态站点生成器 的方式：

要素	推荐选项	说明
站点生成器	VitePress / Nextra / Starlight	Markdown 原生支持，零配置上手
托管平台	Cloudflare Pages / Vercel / Netlify	均支持 Git 集成，推送即部署
部署触发	Git 集成（自动）	优先于手动 CLI 部署

关键原则：源文件留在仓库内（docs/ 唯一真相源）；推送即发布；中文路径转英文 slug。

何时需要：面向团队/外部的文档、超过 5 篇需要导航搜索、需要密码保护。个人小项目 docs/ + GitHub 浏览即可。

10. 与其他子系统的关系

CLAUDE.md：文档体系的入口，AI 的主要知识来源
Skills：/checkpoint 统一知识沉淀，/doc 驱动文档检查更新
Hooks：不直接参与文档维护（文档更新不是确定性操作）
MCP：不直接参与（文档是本地文件操作）

关联文档：01-CLAUDE.md 设计 | 02-Skills 技能体系 | 16-功能清单体系 | 22-项目知识沉淀机制 | 23-产品设计契约

06 - 文档体系设计 ​

1. 定位 ​

2. 知识模型 ​

3. 目录结构 ​

三层说明 ​

子目录存在标准 ​

文件→目录升级制 ​

4. 格式契约 ​

4.1 ADR（架构决策记录） ​

4.2 Troubleshooting（踩坑知识库） ​

4.3 Plans（技术方案 & 阶段计划） ​

4.4 Research（技术调研） ​

4.5 依赖白名单 ​

5. 知识沉淀机制 ​

/checkpoint 作为统一沉淀出口 ​

即时归档 ​

检索协议 ​

规模控制 ​

6. 交叉引用 ​

7. 生命周期 ​

8. 文档自动化 ​

通过 CLAUDE.md 驱动 ​

通过 /doc Skill 触发 ​

通过 CHANGELOG.md 留痕 ​

9. 文档站点发布（推荐） ​

10. 与其他子系统的关系 ​

06 - 文档体系设计

1. 定位

2. 知识模型

3. 目录结构

三层说明

子目录存在标准

文件→目录升级制

4. 格式契约

4.1 ADR（架构决策记录）

4.2 Troubleshooting（踩坑知识库）

4.3 Plans（技术方案 & 阶段计划）

4.4 Research（技术调研）

4.5 依赖白名单

5. 知识沉淀机制

/checkpoint 作为统一沉淀出口

即时归档

检索协议

规模控制

6. 交叉引用

7. 生命周期

8. 文档自动化

通过 CLAUDE.md 驱动

通过 /doc Skill 触发

通过 CHANGELOG.md 留痕

9. 文档站点发布（推荐）

10. 与其他子系统的关系