上一篇文章聊了 vibe coding 里文档管理的重要性，很多朋友留言说道理都懂，但具体怎么落地？今天就把我在自己项目里实际跑通的方案分享出来，不讲理论，直接说做法。
先说背景
我手上有一个 AI 内容生成平台，PHP 后端 + Python Agent 服务 + Vue 前端，三个项目协作。功能模块十几个：知识库、工作流引擎、关键词管理、文章同步、调研报告……典型的"功能不少、上下文很重"的项目。
从去年开始大量用 AI 写代码之后，最先崩的不是代码质量，而是沟通效率。每次开新会话，都要花大量时间重新解释项目背景。改一个模块，AI 经常误伤另一个模块。更头疼的是，我自己过两周回来看，有些决策的原因都想不起来了。
折腾了几个月，最后沉淀出一套文档管理方案。不复杂，但确实好用。核心就两个概念：真相文档和历史文档。
真相文档 vs 历史文档：这个区分是关键
这是整套方案里最重要的一个认知。
真相文档描述的是"系统现在是什么样的"。每个功能只有一份，随着功能演进持续更新，永远反映最新状态。
历史文档描述的是"某次发生了什么变化"。记录需求背景、方案选型、开发过程。写完就归档，不再改。
为什么要这么分？因为 AI 不会自己判断一份文档是不是过期了。
你把一份三个月前的设计文档丢给它，它会当成现状来理解。人看到旧文档可能会想"这段是不是过时了"，AI 不会，它会老老实实地按照文档内容来生成代码。如果文档是旧的，生成出来的代码就会呈现一种很典型的问题：局部正确，整体错误。
所以必须让 AI 有一个明确的规则：默认只读真相文档来理解系统现状，历史文档只在需要追溯"为什么这样设计"时才去翻。
目录结构：三跳到达任意细节
我的文档全部放在 data/docs/ 目录下，按模块划分子目录。结构长这样：
data/docs/
├── INDEX.md # 全局导航
├── 文档规范.md # 文档管理规范本身
│
├── knowledge/ # 知识库模块
│ ├── README.md # 模块入口（功能清单+概述）
│ ├── 品牌知识库.md # 功能真相文档
│ ├── 文档知识库.md # 功能真相文档
│ ├── 向量搜索.md # 功能真相文档
│ └── _changelog/ # 历史归档
│ └── 2026-04_向量化改造.md
│
├── workflow/ # 工作流模块
│ ├── README.md
│ ├── 新版工作流.md
│ ├── 生成规则.md
│ └── _changelog/
│ └── ...
│
└── ...其他模块同样结构
设计思路很简单：三跳到达任意功能细节。
- 第一跳：
INDEX.md→ 找到模块 - 第二跳：模块
README.md→ 找到功能 - 第三跳：功能真相文档 → 看到完整细节
AI 工具拿到 INDEX.md 就能快速定位到任何一个功能的文档。人也一样，不用在一堆文件里翻来翻去。
还有一个小细节：历史文档统一放在 _changelog/ 目录下，用下划线前缀。这样在文件列表里它会自动排到最后，跟真相文档在视觉上就分开了。
真相文档长什么样
拿我项目里的知识库模块举个例子。模块 README.md 长这样：
# 知识库模块
## 概述
知识库是平台的核心模块，包含两套独立的知识库系统...
## 功能清单
| 功能 | 文档 | 状态 | 最后更新 |
|------|------|------|---------|
| 品牌知识库 | [品牌知识库.md](品牌知识库.md) | Active | 2026-04 |
| 文档知识库 | [文档知识库.md](文档知识库.md) | Active | 2026-04 |
| 向量搜索 | [向量搜索.md](向量搜索.md) | Active | 2026-04 |
## 对应代码
- 控制器：KnowledgeController.php
- 服务：KnowledgeVectorService.php、AliKnowledgeBaseService.php
- 模型：KnowledgeBaseModel.php、KnowledgeVectorModel.php
## 模块依赖
- 被 workflow 模块依赖（工作流检索知识库）
- 被 agent 模块依赖（Python Agent 调用 PHP API 检索）
- 依赖阿里云 DashScope、DashVector、百炼
注意几个点：
- 功能清单是一张表，一眼就能看到这个模块有什么、每个功能什么状态、最后什么时候更新的
- 对应代码路径写清楚，AI 看到就知道该改哪些文件
- 模块依赖关系写清楚，改这个模块的时候知道会影响谁
然后每个功能的真相文档，模板也很固定：
# 功能名称
> 最后更新: 2026-04 | 对应代码: app/art/service/xxx.php
## 功能说明
（做什么，一两段话）
## 核心流程
（主要业务/技术流程）
## API / 接口
（对外暴露的接口）
## 关键设计
（重要的技术决策）
## 已知限制
（当前版本的限制和待改进项）
这个模板不是为了好看，是为了让 AI 每次读到的信息结构一致。结构一致，它的理解就稳定；结构混乱，它的输出就飘忽。
CLAUDE.md：AI 的总入口
如果你用 Claude Code 或者类似的 AI 编程工具，项目根目录的 CLAUDE.md 就是 AI 进入项目时第一个读到的文件。
我在 CLAUDE.md 里放了这些内容：
- 项目是什么、技术栈是什么
- 目录结构怎么划分
- 常用开发命令
- 架构概述（控制器、服务、模型各在哪）
- 编码规范和行为准则
- 文档管理规范的入口指引
最后一条很关键。CLAUDE.md 里我写了一句：
项目文档统一存放在 data/docs/ 目录下，当涉及到查看/修改/新增文档时，首先阅读 data/docs/文档规范.md 文件。
这样 AI 在需要了解任何模块时，就会自动走 INDEX.md → README.md → 功能文档 这条路径，而不是在代码里瞎翻。
操作流程：新增、改版、废弃
光有结构还不够，还得有操作规范，不然时间一长文档又会跟代码脱节。
我定了三种场景的操作流程：
新增功能：
- 先在
_changelog/里写开发过程文档（需求背景、方案选型） - 功能完成后，在模块目录下新建真相文档
- 在模块 README.md 功能清单里加一行
- 检查其他文档是否需要联动更新
- 如果是新模块，更新 INDEX.md
改版功能：
- 大改动时先把当前真相文档快照存入
_changelog/ - 在
_changelog/里写本次改版过程 - 直接修改真相文档，更新为最新状态
- 更新 README.md 里的"最后更新"时间
废弃功能：
- README.md 里把状态改成 Deprecated
- 真相文档移入
_changelog/ - 检查其他文档里对该功能的引用
这套流程看起来步骤不少，但实际操作起来很快。而且最大的好处是：真相文档永远是对的。不用猜，不用翻 git log，打开就是当前状态。
实际效果
跑了几个月下来，几个明显的变化：
AI 的输出质量稳定了很多。 以前经常出现"改了 A 模块，把 B 模块的约束打破了"的情况，现在因为模块依赖关系写得清楚，AI 在改代码前会先看依赖，误伤明显减少。
新功能接入速度快了。 比如我最近在做多平台文章同步，每接入一个新平台，AI 只要读一下适配器规范文档和已有平台的真相文档，就能快速上手。不用每次从头解释"什么是适配器、怎么处理图片、怎么管理 Cookie"。
历史决策不再丢失。 为什么放弃某个方案、为什么两个版本并存、为什么某个功能暂时不做——这些都在 _changelog/ 里。不用再靠记忆，也不用翻几百条聊天记录。
我自己回来也能快速恢复上下文。 隔两周没碰某个模块，打开 README.md 看一眼功能清单和状态，30 秒就知道现在什么情况。
几个容易踩的坑
1. 不要追求完美再开始。 我一开始也想把所有模块的文档一次性补齐，后来发现根本不现实。正确的做法是：哪个模块正在开发，就先把哪个模块的文档建起来。慢慢覆盖。
2. 真相文档要短。 一个功能的真相文档，理想状态是一屏到两屏能看完。太长了 AI 也消化不好，人也不愿意读。细节放代码注释里，文档只写"是什么、怎么用、有什么限制"。
3. 历史文档不要纠结格式。 历史文档的价值在于"记录了"，不在于"写得漂亮"。开发过程中随手记，完事了丢进 _changelog/，就够了。
4. 文档更新要跟代码提交绑定。 改了功能不更新文档，等于没改。我现在的习惯是：代码改完，先更新文档，再提交。把文档更新当成开发流程的一部分，而不是事后补的作业。
5. _changelog/ 目录下的文件命名带日期。 比如 2026-04_知识库向量化改造.md。时间一长文件会很多，带日期方便排序和查找。
总结
这套方案说白了就三件事：
- 分清真相和历史——真相文档永远反映当前状态，历史文档只记录变化过程
- 三层导航结构——INDEX → 模块 README → 功能文档，AI 和人都能快速定位
- 操作流程固定——新增、改版、废弃各有标准动作，确保文档不会跟代码脱节
不需要什么特殊工具，就是 Markdown 文件 + 目录约定。任何项目都能直接用。
如果你也在用 AI 写代码，但总觉得效率没有想象中高，不妨先看看自己的文档管理。很多时候，不是 AI 不够聪明，是你给它的上下文不够好。而好的上下文，从来都不是靠临时组织的，是靠日常沉淀的。
