文档不是记录，而是协作接口

本文是《管理复盘》中「上下文」这条线的展开。

写文档不是把自己知道的事情倒出来。真正有用的文档，要让没参与过前情的人也能很快知道：这件事为什么要做、现在准备怎么做、我需要在哪个地方参与判断。

所以我更愿意把文档当成协作接口。它不是存档，不是汇报材料，也不是为了显得做了很多思考；它的任务是把问题、结论和下一步交接清楚。

到了 AI 时代，文档更像 context、memory 和证据

这件事在 AI 协作里变得更直白了。人可以靠一次聊天补齐遗漏的前情，也能模糊地记得“当时为什么这么决定”；Agent 做不到。它拿到什么上下文，就只能基于什么上下文工作。上下文里没有边界，它就会猜；没有旧决定，它就会重复讨论；没有证据，它就会把推测写得很像事实。

一份好文档因此至少承担三种角色：

• Context： 给后来的人或 Agent 一份足够小、但能开始工作的上下文。问题、范围、当前状态和下一步要清楚，别把无关的历史全塞进去。
• Memory： 记录已经做过的关键判断。尤其是“为什么不选另一个方案”“哪些限制是暂时的”，否则换一个人、换一次会话，就会把已经解决的问题重新讨论一遍。
• Evidence： 区分事实、推测和结论，并留下数据、实验、代码或反馈的出处。没有证据的文档很容易在转述几次之后变成一句谁也无法核对的“大家都认为”。

多人交接和多 Agent 协作，本质上是同一个问题：原来知道上下文的人不在场了，接手者需要在有限时间里恢复正确的判断。区别只是前者的接手者是同事，后者可能是另一个模型、另一个会话，或者一个负责不同子任务的 Agent。

所以，别把文档写成“给熟人看的提示”。对人有效的隐含前提，到了 Agent 那里会直接变成缺失信息；而给 Agent 准备的明确输入、状态和证据，反过来也会让人的交接顺得多。好的文档不是把上下文无限变长，而是把真正会影响下一步的内容留下来。

下面是一套我自己会先套上的基础结构。它不是所有文档都必须完整照搬，但比从一页空白开始靠谱得多。

先给结论，再讲故事

很多文档一开始铺了很长的背景，读到第三屏还不知道作者想干什么。读者打开一篇方案时，最先想知道的其实是三件事：

1. 这篇文档在解决什么问题？
2. 你建议怎么处理？
3. 希望我看完之后做什么？

这三件事写不清，后面再完整的材料也很难被有效阅读。可以在开头直接放一段摘要：问题是什么、推荐方案是什么、还需要谁确认什么。背景和过程并不是不要写，而是放到结论之后，留给需要理解的人继续读。

比如不要写：

最近我们在某个方向上遇到了一些问题，经过一段时间的讨论和调研，发现有不少优化空间。

不如直接写：

当前发布链路需要人工重复核对三个环境，平均一次发布要花约二十分钟，也容易漏掉配置。建议先把校验收敛为一条自动检查；本周需要确认它是否覆盖两类特殊发布场景。

前者只有情绪和过程，后者给出了问题、影响、方案和需要讨论的点。

一份方案文档，通常写这几部分

1. 背景：只交代理解问题所必需的事实

背景不是项目编年史。写清楚发生了什么、为什么现在需要处理、受影响的是谁即可。

如果背景里有数据、用户反馈或故障现象，尽量给来源和时间范围；如果只是推测，就标成推测。事实和判断混在一起，是后续讨论最容易跑偏的原因之一。

2. 目标：把“想做好”变成可以判断的结果

目标要回答：做完以后，什么会不一样？

一个比较实用的写法是同时给出目标和非目标。例如：

• 目标：把常规发布前的人工核对改为自动校验，并能明确指出失败项。
• 非目标：这次不重做整个发布平台，也不处理需要人工审批的例外流程。

非目标很重要。它能防止每个人都把自己关心的问题顺手塞进来，最后把一个能做的小项目写成无法启动的大工程。

3. 方案：解释怎么做，以及为什么这么做

方案不必一开始就写到实现细节。先把核心路径说清楚：输入是什么、经过哪些关键步骤、输出或变化是什么。流程复杂时，一张图或一张表通常比几段大文字更有效。

然后补上真正影响判断的细节：

• 有哪些可选方案，为什么推荐这一种；
• 依赖什么前提，风险在哪里；
• 哪些地方还没确认，需要先验证；
• 接口、数据结构、状态变化或异常路径是否会影响其他人。

不需要为了“看起来专业”把所有技术细节都塞进去。评审方案时，重点是帮助人做取舍；实施时，才需要把边界、接口和验收条件写细。

4. 计划：把事情拆到可以开始

计划不是把所有工作列成几十行待办。只要能说明主要阶段、依赖关系和完成标准就够了。

计划里最值得写的是不确定性：什么事情卡住会影响后续，什么时候需要重新评估，而不是假装每个日期都已经确定。

5. 附录：把细节放在需要它的地方

参考链接、术语解释、完整数据、替代方案的展开、较长的调研过程，都可以放在附录。附录不是垃圾场，它的作用是让正文保持可读，同时让需要追问的人找得到依据。

如果一项决定后来被改掉了，可以补一条简短的变更记录：改了什么、为什么改、对谁有影响。没有必要把每一次措辞润色都记下来。

重点和细节，怎么平衡

写文档最常见的两种问题刚好相反：一种是只有大话，读完不知道怎么做；另一种是细节太多，读者找不到重点。

我的判断标准很简单：先写给需要做决定的人看，再写给需要落地的人看。

前者需要结论、取舍、风险和请求；后者才需要接口、流程、状态机、数据结构和具体步骤。把两类信息分层，读者就可以按自己的需要往下读。

一些写作习惯也会直接影响可读性：

• 少用默认大家都懂的缩写和黑话；必须用时，第一次出现就解释。
• 代码请用代码块，不要截成图片。代码需要复制、搜索和比对。
• 图和表只在它们能更快说明关系时使用；一张没有结论的架构图，通常只是更大的装饰。
• 加粗用来标结论和风险，不要每段都加重点。全是重点，就没有重点。
• 写完后删掉不推动问题、方案或决定的段落。很多“铺垫”删掉以后，文章反而更诚实。

写完之后，用三个问题检查

发出之前，找一个没有参与前序讨论的人看一眼，或者自己隔一会儿再读，回答三个问题：

1. 我能不能在一分钟内说出这篇文档要解决的问题？
2. 我知不知道推荐的下一步是什么，以及为什么？
3. 如果要参与，我知道该在哪个点提出意见或开始行动吗？

三个问题里有一个答不上来，通常不是再补一段背景就能解决，而是结构还没有把重点摆对。

文档的好坏不取决于它有多少页，也不取决于标题有多像模板。它最终要完成的事很朴素：让人少猜一点，多做一点正确的事。