文档腐烂得太快了
# 文档腐烂得太快了
我最近越来越觉得，AI 开发里最容易被高估的东西不是模型能力，而是文档的新鲜程度。
文档这个东西很奇怪。你刚写完的时候，它像刚出炉的面包，热乎、完整、闻起来还有一点工程秩序的香味。过两周再看，它可能已经变成压缩饼干。过两个月，如果中间系统迭代频繁，那它基本就是考古现场：不是不能吃，但吃之前最好先确认一下年代。
更麻烦的是，AI 开发会把这个腐烂速度继续放大。
以前一个功能改动，可能要开会、排期、写代码、review、测试、上线。文档虽然也会过期，但好歹还有一点缓冲时间。现在 Coding Agent 一晚上能改十几个文件，顺手调三处配置，再把一个原本“未来再说”的重构今天就说了。系统在加速，文档如果还按原来的节奏维护，就会很快从“知识”变成“旧知识”。
旧知识有时候比不知道更危险。
不知道的时候，人至少会查。旧知识会让人产生一种虚假的踏实感：这里写着呢，应该是这样。然后你顺着文档一路走下去，最后发现线上早就不是这回事。
# 文档为什么会腐烂
文档腐烂不是因为大家懒。懒当然也有，但不是主因。
真正的问题是：文档通常是系统某个状态的投影，而系统本身一直在变。
代码变了，接口变了，部署方式变了，配置默认值变了，服务边界变了，甚至团队理解也变了。文档如果没有跟着这些变化一起更新，它就会慢慢偏离事实。
偏离一开始很小。一个参数名不对，一个 path 没更新，一个环境变量说明少了一行。然后偏离会叠加。最后读文档的人会进入一种很熟悉的工程体验：
这句话的杀伤力很大。它说明文档已经从帮助系统变成了干扰系统。
# AI 让文档半衰期变短
AI 开发带来的核心变化之一，是修改成本下降了。
一个人以前可能一天只敢动一个模块。现在有 Agent 帮忙读代码、补测试、批量改调用点，改动可以很快扩散到多个层次：业务逻辑、接口定义、部署配置、CI 流程、观测指标。
这当然是好事。但副作用是，系统状态变化更频繁了。
当系统变化更频繁，文档的半衰期就会变短。以前一篇设计文档可能能活半年，现在可能一个迭代就开始泛黄。尤其是那些写得很具体的操作文档，腐烂速度最快：
- 某个命令怎么跑。
- 某个接口返回什么字段。
- 某个配置在哪个文件。
- 某个服务依赖谁。
- 某个环境怎么部署。
这些内容如果不和代码、测试、运行时绑定，基本都是临时食品。放久了就别太信。
# 不要让 README 假装自己是生产环境
我不是反对 README。README 很有用，尤其是告诉新人这个项目是什么、为什么存在、怎么开始。
但 README 不应该假装自己是生产环境。生产环境有自己的事实来源：代码、commit、镜像、Pod、Service、Route、日志、指标、告警、trace。
如果 README 写“这个服务依赖 Redis”，但运行时里它其实已经依赖了 Redis、Kafka 和一个没人敢删的内部 HTTP 服务，那应该相信谁？
当然相信运行时。
文档最好的位置不是站在事实前面替事实发言，而是站在事实旁边解释它：
这四个东西不要互相冒充。
# 好文档应该靠近事实
AI 时代的文档，我觉得应该有几个原则。
第一，文档要短。越长越容易腐烂。长文档不是不能写，但长文档必须解释长期稳定的东西，比如架构原则、设计取舍、业务边界。不要把一堆随时会变的命令和参数堆成一座纪念碑。
第二，文档要链接事实。不要复制代码里的配置，不要手抄接口字段，不要把 kubectl 输出粘进文档然后假装它会永远年轻。能链接 repo 就链接 repo，能链接 OpenAPI 就链接 OpenAPI，能链接 dashboard 就链接 dashboard。
第三，文档要能被验证。比如开发环境启动文档，最好能对应一个脚本。接口说明最好能对应测试或 schema。部署说明最好能对应 CI/CD 配置。只靠人眼维护的文档，在 AI 加速开发之后会很吃力。
第四，文档要承认自己会过期。可以写清楚：
这比写一堆自信但没人验证的话更有价值。
# Agent 需要的不是大文档，而是路标
Coding Agent 其实不需要你把所有细节写成散文。它更需要路标。
比如：
这类信息不长，但它能把 Agent 带到正确的事实源。它知道该去哪里看代码，哪里看接口，哪里看运行时对象，哪里看设计背景。
这比一篇过期的“完整操作手册”更适合 AI 开发。
完整操作手册的问题是，它看起来很完整，所以读者会放松警惕。路标不假装自己是地图，它只负责把你带到地图旁边。
# 文档的新职责
所以我觉得文档不会消失，但职责会变化。
文档不应该再承担“描述系统当前完整状态”的主要责任。这个责任应该交给代码、测试和运行时。
文档更应该解释这些东西：
- 为什么系统是这样设计的。
- 哪些边界不能随便动。
- 哪些历史包袱还没还。
- 哪些行为是业务约束，不是技术偶然。
- 出问题时应该从哪些事实源开始查。
换句话说，文档要少写“现在是什么”，多写“为什么是这样”和“去哪里验证现在是什么”。
这会让文档更耐用。
# 腐烂不可避免，但可以控速
文档一定会腐烂。这不是道德问题，是物理问题。
只要系统在动，文档就有滞后。AI 让系统动得更快，所以腐烂也更快。我们能做的不是幻想文档永远新鲜，而是控制腐烂速度。
我的倾向是：
- 把易变内容放进代码、schema、测试、CI 和运行时标注。
- 把稳定意图放进文档。
- 给文档加验证入口，而不是手写所有细节。
- 让 Agent 和人都从事实源开始，而不是从传说开始。
文档还是要写。但不要让它一个人扛住系统事实。
系统已经跑起来了，就让系统自己说话。文档站旁边，负责解释；不要站中间，负责扮演现实。