每日AI深评|文档不是给人看的了

今天 Hacker News 上有一条很有意思的讨论：

“程序员愿意给 Claude 写文档，却不愿意给同事写文档。”

这句话听起来像个段子，但我觉得它背后不是段子，而是软件工程正在发生的一次很隐蔽的变化。

过去我们总说，文档是团队协作资产。

但现在，文档正在变成另一种东西：

文档不再只是写给人看的，而是写给 AI agent 吃的上下文。

这件事如果想明白了，你会发现很多公司接下来做 AI 编程、AI Agent、AI 自动化，真正的瓶颈可能不是模型不够强，而是公司自己没有给 AI 留下足够清晰的“可读取记忆”。

一、这个现象为什么刺痛程序员

原文作者 Mark Dominus 讲了一个很具体的做法。

他在做大项目时，会让 Claude 维护一份 handoff document，也就是交接文档：

这轮我们计划做什么，已经做了什么，还有哪些相关背景。

当一个 Claude 会话结束，他会让下一个 Claude 先读这份文档，再继续干活。更有意思的是，他后来意识到：

为什么要把这些交接文档扔掉？

把它们 commit 到 repo 里不就行了吗？

未来某个人，包括未来某个 AI，遇到同样问题时，可能刚好能用 git grep 搜到这些记录，理解当时到底发生了什么。

这就是这条讨论最有意思的地方。

它不是在说“程序员突然变勤快了”。

恰恰相反，它是在说：程序员终于遇到了一个真的会读文档、并且读完马上产生收益的读者。

这个读者，叫 Claude。

二、为什么人不读文档，AI 却会读

程序员不爱写文档，不是因为他们不知道文档重要。

大多数时候，是因为收益太滞后了。

你花一小时写一份架构说明，同事可能不看；

新人可能先来问你；

管理层可能只在事故复盘时才想起来“我们是不是该有文档”；

更糟糕的是，文档一旦没人维护，很快就会从资产变成负债。

HN 评论区里有人吐槽得很狠：很多 CLAUDE.md 和 PROJECT.md 本身就是 70% 完整、10% 间接、20% 错误的“非结构化垃圾”。

这话难听，但是真的。

文档最怕的不是没有，而是过期。

一个过期的 CLAUDE.md，会让 AI 幻觉出早就不存在的类、函数和架构。

这时它不是上下文资产，而是上下文毒药。

但即便如此，程序员还是愿意给 Claude 写。

原因很简单：

人类读文档的收益是不确定的；AI 读文档的收益是即时的。

你今天补一段项目约定，Claude 下一轮就可能少犯一个错。

你今天写清楚测试命令，Agent 明天就不会傻乎乎跑错脚本。

你今天把部署坑写进 AGENTS.md，未来十次自动修 bug 都可能少绕一圈。

这就是激励结构变了。

以前写文档像做公益。

现在写文档像给自己的 AI 员工做岗前培训。

三、真正变化：文档从“协作工具”变成“上下文基础设施”

我觉得大多数人看这个新闻，只会看到一个有趣的工程师梗。

但更大的变化是：软件工程里的很多文本资产，正在被重新定价。

README、接口说明、代码注释、测试说明、架构决策记录、commit message、PR review、issue 讨论，过去这些东西都叫“文档”。

它们的价值取决于有没有人看。

但在 Agent 时代，它们的价值不再只取决于人看不看，而取决于机器能不能稳定读取、理解、调用。

这就像过去企业做数据化时，大家突然发现：

原来业务流程里那些没人关心的字段、表单、日志、编号规则，都是未来自动化的地基。

AI 编程也是一样。

当你让 Agent 接管越来越多工程任务时，公司里所有“隐性知识”都会变成问题：

• 这个 repo 为什么这么拆？
• 这个接口为什么不能改？
• 这个测试为什么偶尔失败？
• 这个客户的特殊逻辑为什么写死在这里？
• 这个部署命令为什么不能直接跑？

过去这些答案藏在人脑里。

现在 AI 问不到人脑，只能读上下文。

所谓 Agent-ready codebase，本质上不是代码写得多漂亮，而是这个系统有没有把关键知识显性化。

没有显性知识，Agent 再强也只能猜。

而猜，就是 bug 的开始。

四、文档会不会变成新的技术债？会，而且更危险

这里也不能只讲乐观面。

给 AI 写文档，不等于文档天然有价值。

相反，Agent 时代的烂文档，杀伤力可能比以前更大。

以前一份烂文档，人看了可能会怀疑：这玩意是不是过期了？

AI 不一定会怀疑。

它可能会一本正经地把错的东西执行下去。

这也是 HN 评论区争议最大的地方：

“Slop in, slop out.”

垃圾上下文进去，垃圾结果出来。

所以，未来团队的文档能力，不只是“写得多”，而是三件事：

第一，文档要短。

不是把所有聊天记录都塞进去，而是提炼真正影响决策的约定。

第二，文档要结构化。

比如项目目标、不可变约束、常用命令、已知坑、测试方式、部署流程、关键业务规则，这些应该有固定位置。

第三，文档要可维护。

每次重大变更后，让 Agent 自己生成 summary，但人必须 review。

原文作者有一句话很关键：他会认真审阅 Claude 写的项目总结，因为最终是他签名 commit，是他拿工资负责。

这点特别重要。

AI 可以写总结，但责任不能交给 AI。

未来优秀工程师的工作，不是亲手写每一行文档，而是设计一套让 AI 生成、人类校准、repo 留痕的知识更新机制。

说白了，文档也要进入 CI/CD。

五、这对创业公司尤其重要

大公司有流程，有文档系统，有新人培训，虽然很多也很烂，但至少有组织惯性。

创业公司最危险。

因为创业公司早期全靠人脑缓存。

创始人知道客户为什么要这个功能；

早期工程师知道某段代码为什么不能动；

运营知道某个字段为什么这么命名；

但这些东西通常不会被写下来。

以前这样也能跑，因为人少，喊一声就行。

但一旦你想用 AI Agent 提效，问题就来了。

Agent 不在你们的饭桌上，不在飞书群的潜台词里，也不知道某个客户三个月前提过什么奇怪要求。

它只能读取你给它的上下文。

所以我越来越觉得，AI 时代创业公司的基础设施，不只是代码、数据、流程，还有一层很容易被忽略的东西：知识资产。

不是那种写在 PPT 里的“企业知识库”，而是嵌在工作流里的、能被 Agent 读取和执行的知识资产。

比如：

• 每个 repo 的 AGENTS.md / CLAUDE.md
• 每次项目结束后的 project summary
• 每个核心模块的设计决策记录
• 每类客户需求的业务规则说明
• 每次线上事故后的修复记录和禁止事项

这些东西平时看起来不性感。

但当你开始用 Agent 干活，它们会直接决定 AI 的上限。

同一个 Claude，放进两个公司，表现可能完全不同。

不是模型不同，而是上下文不同。

六、我自己的判断

我现在越来越不相信“AI 会让文档消失”这种说法。

恰恰相反，AI 会让好文档变得更值钱。

只不过文档的形态会变。

它不再是没人打开的 80 页 Confluence，也不再是为了 ISO 审计补出来的流程文档。

它会更像代码库里的操作系统说明书：短、硬、可验证、持续更新。

未来一个团队有没有 AI Native 能力，不是看它买了多少 AI 工具，也不是看它员工每天开多少个 Agent。

要看一个更朴素的问题：

当一个新 Agent 进入你的项目，它能不能在十分钟内读懂这个系统的边界、约定和坑。

如果不能，那你不是缺 AI 工具。

你是缺给 AI 工作的地基。

结尾

今天这条新闻最反常识的地方在于：

程序员不是突然爱上了写文档。

他们只是终于遇到了一个会认真读文档的同事。

这个同事不抱怨、不跳槽、不嫌你啰嗦，还能在下一秒把文档转化成代码产出。

所以，文档的春天可能不是被人类带来的。

是被 AI 带来的。

一句话总结：

以前不写文档，最多坑同事。

以后不写文档，是直接降低你所有 AI Agent 的智商。