程序员愿意为 AI 写文档，却不愿为同事写
目录
一个有趣的悖论
Mark Dominus在他的博客 The Universe of Discourse 上写了一篇短文 Programmers will document for Claude, but not for each other，标题本身就点出了一个耐人寻味的现象：
我不断看到程序员们抱怨：人们愿意为 Claude 写详细的 CLAUDE.md 和 PROJECT.md 文件，却不愿意为自己的同事写这些。
这个现象确实讽刺。程序员们多年来对项目文档爱答不理——README 写得敷衍，设计文档懒得更新，交接笔记能省则省。但当 AI 成了文档的"读者"时，大家突然变得勤快了。
Mark 的做法：从丢弃到保留
Mark 本人在使用 Claude 时养成了一些有意思的习惯。
首先，他让 Claude 维护一份"交接文档"（handoff document）。每次 Claude 会话结束时，这份文档会记录：计划做什么、已经做了什么、以及其他相关信息。下一个 Claude 会话开始时，读取这份文档就能快速进入状态。
一开始，Mark 在项目结束后就把这些交接文档扔掉了。后来他灵光一现——为什么要扔掉呢？把它提交到 git 仓库里不就行了？将来有人用 git grep 翻看历史，说不定就能找到有用的信息。
再后来，他进一步改进了做法：项目结束时，不再直接提交交接文档，而是让 Claude 从头写一份结构化的项目摘要——不是零散的笔记，而是对整个项目的高层次概述，包括解决了什么问题、做了哪些改动。
他会仔细审阅这些摘要，必要时进行编辑，然后才提交。毕竟签名是他的，工资也是发到他的银行账户上，所以仓库里的任何内容都必须是他仔细读过并理解的——就像 Claude 是一个由他管理的人类程序员一样。
Claude 的写作水平
Mark 提到，Claude 的摘要质量和他自己写的差不多，可能稍好一点，也可能稍差一点。但关键是：Claude 写只要 10 秒，而他亲自动手需要一个小时。而且审阅的时间远远不到一个小时。
不过也有有趣的小插曲。有一次 Claude 参考了之前的一份报告来写新报告，而之前那份报告的末尾有一段 Mark 自己加的文字：
Claude abstracted these notes from our discussions of the issue. Mark Dominus has read, reviewed, edited, and approved these notes.
结果新报告里也出现了一模一样的段落。好消息是，等 Mark 发现时，这段话恰好是真实的——他确实审阅过。后来他在 CLAUDE.md 里加了一句话，告诉 Claude 不要再这样做。
我的思考
这个现象之所以有趣，是因为它揭示了关于文档本质的几个真相：
文档的真正障碍不是"没时间"，而是"没动机"
为 AI 写文档之所以容易，是因为反馈是即时的——你写了 CLAUDE.md，Claude 马上就能理解你的项目上下文，给你更好的回答。而为同事写文档的反馈周期长得多，甚至可能永远得不到反馈。人很难对延迟的、不确定的回报产生动力。
AI 降低了"表达成本"
让 Claude 代笔写一份项目摘要只要 10 秒，而自己写需要 1 小时。这意味着文档的瓶颈从"写"转移到了"审"。当写作成本趋近于零时，唯一剩下的门槛就是你是否愿意花时间阅读和确认——而这比从零开始写要轻松得多。
为 AI 写的文档，最终服务的还是人
Mark 的做法说明了一个巧妙的闭环：你为 Claude 写的交接文档和项目摘要，最终被提交到 git 仓库里，成为团队的知识资产。未来的同事——或者未来的你——可以通过 git grep 找到这些信息。AI 在这个过程中扮演的角色更像是一个"文档代笔者"：你说你想表达什么，它帮你写出来，你审核确认后入库。
也许这就是 AI 改善文档文化的隐秘路径：不是说服程序员"文档很重要"，而是让他们在为 AI 服务的过程中，自然而然地为人类同事也留下了文档。
Mark 的建议
Mark 在文章最后给出了两条实用建议：
- 如果你让 Claude 写了笔记，项目结束后把它提交到仓库里。
- 让 Claude 写一份项目摘要，然后提交到仓库。