「这块业务之前是怎么定的？」「你去问 XX 吧。」 「文档里应该有写吧？」「有，但找不到了。」
类似的对话出现得越多，越能说明一件事：团队不是没写文档，而是这些文档没沉下来。
一、为什么写了那么多文档，却没沉淀下来
在团队协作中，「文档失效」常见的有两种模式。
模式 A：所有东西都堆在个人笔记软件里。 团队不知道你在哪儿写、写了什么；人员变动那一天，全部带走，团队的知识瞬间清零。
模式 B：所有东西都直接写进项目 README 或公司 Wiki。 个人灵光一现的小笔记进不来；跨团队的高维结论又被困在某个项目目录里。项目归档时，文档跟着一起入土。
这两种模式的根因其实是同一个 ------ 没分层。
文档不是越多越好，而是要让每一份文档「落到该落的位置」。受众错了，再好的内容也是噪音；生命周期错了，再认真的文字也活不过下一个季度。
二、四层模型一图看懂
| 层级 | 名称 | 主要受众 | 生命周期 | 变更节奏 |
|---|---|---|---|---|
| ④ | 企业层 | 全公司员工 / 跨职能岗位 | 多年 | 极慢、强约束 |
| ③ | 团队层 | 团队内 + 上下游协作方 | 项目周期级 | 中等 |
| ② | 项目层 | 项目协作者 + AI 编程助手 | 与代码同寿命 | 跟着代码走 |
| ① | 个人层 | 未来的自己 + 公网读者 | 短到极长 | 极快、可丢弃 |
越往上：受众越广 / 抽象度越高 / 变更越慎重。越往下：节奏越快 / 探索性越强 / 私密性越高。
每升一层，知识都要经过三个动作：脱敏 → 泛化 → 抽象。这是后面会反复出现的关键词。
三、第一层：个人文档
定位：你大脑的外存，是其他所有层的原料仓库。
主要受众：未来的自己（大部分时候）+ 公网读者（当你愿意外化时）。
典型内容：
- 学习笔记（读完一本书、一篇文章、一篇技术文档）
- 踩坑日志（环境问题、依赖冲突、奇怪 bug 的复盘）
- 工具配置（编辑器、命令行、git 的个性化设置）
- 想法草稿（写到一半的博客、未成形的方法论）
- 可外化版本：脱敏后发到掘金、个人博客、技术公众号
工具推荐：
| 工具 | 适合人群 | 优势 |
|---|---|---|
| 飞书云文档（个人空间） | 公司已在用飞书 | 与团队层无缝过渡 |
| 腾讯文档 / WPS 文档（个人） | 跨设备、习惯国产办公套件 | 启动快、模板多、移动端友好 |
| Obsidian | 喜欢本地优先 + Markdown | 双向链接、插件丰富、零厂商绑定 |
| VS Code + Markdown + Git | 程序员、想自己掌控版本 | 历史可追溯、对 AI 友好 |
| 语雀（个人空间） | 喜欢富文本 + 自带博客发布 | 自带技术博客发布能力（备选） |
反模式：
- 写得太精致：草稿就是草稿，别花两小时排版，那是消耗精力
- 永远不外化：知识在你脑子和硬盘里，不算资产
- 试图分类完美：放心地建一个「待整理」目录，每周再翻一次就好
示例：
某次本地启动失败，定位到是 Node 版本和某个底层依赖二进制不兼容。先在个人笔记里写一段排查记录（带公司项目名、内部 npm 源）；一周后整理成《Node 22 升级踩坑：一类被忽略的二进制兼容问题》发到掘金，去掉公司项目名、只保留通用现象与解法。这一步「脱敏 + 外化」就是个人层走向公网的标准动作。
给自己定一条低门槛规则：每月把一篇笔记脱敏成博客发出来。外化是给自己加复利的最简单方式，也是面试、跳槽、个人品牌的弹药库。
四、第二层：项目文档
定位：和代码同生命周期的「工程上下文」，是项目本身的一部分。
主要受众：项目的所有协作者（含未来加入的人、AI 编程助手、做代码评审的同事）。
典型内容：
- 项目 README、快速开始
- 架构决策记录、技术方案文档
- 模块边界与依赖规则
- 部署与持续集成流程
- 调试、性能、安全检查清单
- 给 AI 编程助手看的上下文（如
AGENTS.md、CLAUDE.md、.cursor/rules）
工具推荐：
| 工具 | 适合场景 | 优势 |
|---|---|---|
| Markdown + Git | 中小型项目 | 与代码同仓、走合并请求评审 |
| VitePress / Rspress / Docusaurus | 需要可读性更好的文档站 | 美观、可搜索、可发布 |
| MkDocs | Python 生态 | 主题成熟、上手快 |
| Storybook + MDX | 组件库 | 文档与示例一体 |
这一层为什么不优先推荐飞书 / Confluence：写在外部平台的文档，第一次和代码同步还行，几轮迭代之后就会开始漂移；新人加入项目时找不齐；AI 编程助手也更难直接读到真正的工程上下文。
关键原则：
- 靠近代码：项目层文档放在项目仓库里，和代码一起走合并请求、一起评审
- 可执行：能用一行命令启动的文档站，远胜散落在各处的 markdown 文件
- 对 AI 友好 ：维护一份精简的
AGENTS.md（控制在 80 行内），让 AI 编程助手也能高质量消费
反模式：
- 把项目文档全写进外部协作平台：和代码必然漂移，新协作者找不齐
- README 写成产品宣传：项目层文档要服务的是协作者，过度包装反而让真正有用的信息被淹没
- 文档与代码不同步：每次合并请求必须自问「这次改动要不要更新文档」
示例：
一个前端工程化迁移项目，把「模块迁移决策框架」沉淀成项目仓库内的一份 markdown 文档，规定改动文件数超过阈值时必须先做业务分析。任何协作者（或 AI 编程助手）发起迁移前，提交前钩子会强制提示读这份文档。文档不再依赖自觉，而是嵌入了工作流。
五、第三层：团队文档
定位：跨人、跨职能协作时的「共识载体」。
主要受众：本团队全员、上下游协作方（产品 / 设计 / 测试 / 数据）、评审参与者。
典型内容：
- 业务名词表、领域词典
- 接口契约、接口评审记录
- 需求文档、技术方案文档
- 团队周报、OKR、复盘记录
- 排班、值班、协作流程
工具推荐：
| 工具 | 优势 | 适合 |
|---|---|---|
| 飞书文档 + 飞书 Wiki | 评论、@提及、审批一体；中文体验好 | 已在使用飞书办公套件的团队 |
| 腾讯文档 / WPS 文档 | 协作权限灵活、办公生态成熟 | 与上下游已在使用同生态 |
| 钉钉文档 | 已在钉钉生态 | 钉钉重度用户 |
| 语雀（团队空间） | 富文本 + 知识库结构清晰 | 偏内容沉淀的团队（备选） |
| Confluence | 老牌、企业集成多 | 外企或规模化工程组织 |
为什么不是项目层的简单扩展 ：团队层的特征是「业务可读 + 多方共识」。让产品同学打开代码仓库看 Markdown 文件是不现实的；让前端同学进飞书查某个组件的参数说明又是低效的。受众决定载体。
关键操作：从项目层「外化」到团队层
不是简单复制粘贴，而是要做三件事：
- 脱代码细节：去掉文件路径、类名、配置项
- 加业务语境：补上为什么这么做、对业务的影响
- 加决策痕迹：谁拍板、什么时候、有哪些备选方案被否决
示例：
团队决定为新业务引入服务端渲染方案，在项目仓库有一份完整的技术方案文档（含具体接口、缓存策略与代码示例）；同步外化一份《SSR 渲染策略 v2》到飞书，加上「为什么不直接全部走客户端渲染」「对 SEO 的预期影响」「对运维成本的影响」三段，方便业务方和测试同学评审。同一份决策，在项目层是技术细节，在团队层是业务对齐。
反模式：
- 团队层变成「飞书版 README」：信息密度低、对工程师没价值、对产品同学又太技术
- 评审记录不沉淀：飞书评论 + 会议结论散落各处，过段时间没人记得「为什么不做 A 方案」
- 个人感受混入团队文档：团队层是共识，不是个人意见汇总
六、第四层：企业文档
定位：跨团队、跨业务线、跨时间的「长期资产」。
主要受众：全公司员工（不仅是工程师，也包括产品、设计、测试、运营等）、新员工入职培训、合规与安全相关岗位。
典型内容：
- 技术战略、架构白皮书
- 安全、合规、隐私规范
- 公司级编码规范、设计系统
- 全员手册、新员工指南
- 跨团队基础设施使用说明（持续集成、监控、鉴权、灰度、网关）
- 故障复盘记录与典型案例库
工具推荐：
| 工具 | 适合 |
|---|---|
| 飞书知识库（多空间 + 权限分级） | 已在使用飞书办公套件的公司 |
| 腾讯文档 / WPS 文档（企业版） | 已在腾讯 / WPS 办公生态的公司 |
| 钉钉文档（企业版） | 已在钉钉生态的公司 |
| Confluence | 外企或规模较大、流程成熟的工程组织 |
关键原则：
- 强治理：必须有负责人 + 定期回顾机制，否则时间一长就会出现大量「幽灵文档」
- 可发现：从入职第一天起就能搜得到，而不是「问了好几个人才知道在哪」
- 稳定地址：链接一旦发布尽量不动，因为它会被无数 Wiki、邮件、即时通讯消息引用
反模式：
- 把团队层强行升级到企业层：大多数团队约定不需要全公司知道
- 没有负责人就发布：新员工误以为它仍是当前规范，而老员工早已知道它已经过时
- 文档平台频繁更换：迁移成本远大于工具升级的收益
示例：
一次大规模线上故障复盘后，把根因（CDN 缓存策略与上游接口缓存策略冲突）抽象成《缓存层级治理规范》进入企业层，并配套 lint 规则和上线检查清单。该故障的具体细节 留在团队层复盘文档，事件回顾留在项目层变更日志。同一个事件，在三层都有「投影」，但内容形态完全不同。
七、知识如何在四层之间流动
不是所有文档都要走到第四层，但有效的沉淀都遵循一条向上的路径：
三个关键动词：
- 脱敏（个人 → 公网）：去掉公司名、项目代号、客户信息、内部接口
- 泛化（项目 → 团队）：从一个具体代码改动，变成一类问题的解决思路
- 抽象（团队 → 企业）：从一个团队的最佳实践，变成跨团队的规范
反过来，企业层对下游有约束作用 ------ 团队、项目、个人都应在企业层规范下行动。这是双向流动，不是单向搬运。
八、工具推荐汇总（一张表收藏）
| 层级 | 首选 | 备选 | 不推荐 |
|---|---|---|---|
| ① 个人 | 飞书云文档 / 腾讯文档 / WPS 文档 / Obsidian | 语雀 / VS Code + Markdown + Git | 强协作平台（杀鸡用牛刀）；含敏感信息时也不推荐放在无治理的纯个人笔记中（有外泄风险） |
| ② 项目 | Markdown + Git + 文档站（VitePress / Rspress） | MkDocs / Storybook | 飞书 / Confluence（与代码必然漂移） |
| ③ 团队 | 飞书文档 + 飞书 Wiki | 腾讯文档 / WPS 文档 / 钉钉文档 / 语雀 / Confluence | 代码仓库的 README（产品同学进不来） |
| ④ 企业 | 飞书知识库 / 腾讯文档（企业版）/ Confluence | WPS 文档 / 钉钉文档（企业版） | 个人笔记软件（无治理 + 有信息泄漏风险） |
九、常见陷阱与对策
「我们没有四层，只有飞书」 飞书虽然可以承载一部分项目层文档，特别是配合飞书 CLI 这类工具，AI 编程助手也能读到飞书内容。但项目层文档放在代码仓库里仍然是更稳的选择：和代码同 PR 评审、同生命周期、可被任意 AI 编程工具一致地读取。不是非此即彼，而是分清主次。
「分层太复杂了，团队学不会」 不需要全员学，团队里有 1 到 2 个「文档架构师」即可。其他人按习惯写，他们负责搬家和把关。
「我写了很多个人笔记但从不外化」 给自己定个低门槛规则：每月至少把一篇笔记脱敏成博客发出来。外化就是复利。
「我们企业层文档没人维护」 现实是大多数团队没有专人做定期巡检，强行推一套巡检流程也很难持续。更可行的做法是把维护从「定期巡检」转为「按需触发」：
- 文档显眼处标注负责人 和最近一次确认时间，让阅读者一眼看出可信度，自己判断是否要再确认一遍
- 使用即维护：当有人在文档评论区提出疑问，或在合并请求里发现规范已经过时，就顺手更新一下，而不是攒到「下次复盘」再说
- 接受文档会过时这件事，不强求每一篇都「新鲜」 ------ 让被引用的频次决定维护投入
「AI 时代了还需要写文档吗？」 更需要。AI 是上下文消费者，文档质量直接决定 AI 输出质量。AGENTS.md、CLAUDE.md、Cursor Rules 本质就是为 AI 写的项目层文档。写好文档 = 给 AI 更好的提示词。
十、结语：让文档长出复利
知识沉淀的本质不是「写文档」，而是让经验在正确的层 × 正确的载体 × 正确的受众之间流动。
四层模型不是教条，而是一把尺子 ------ 下次你准备打开编辑器之前，先问自己三个问题：
- 这段内容，受众是谁？
- 它需要活多久？
- 它应该住在哪一层？
答对了，知识就会长出复利；答错了，再多的文字也只是数字垃圾。
你所在的团队是怎么处理「文档 vs 代码仓库 Wiki」这种拉锯的？欢迎在评论区聊聊踩过的坑。如果这篇文章对你有帮助，欢迎点赞、收藏、关注。