程序员会为 Claude 写文档，但不会为彼此写

为什么人们会“为 Claude 写文档”

• 开发者能立刻看到切实回报：当他们提供聚焦的上下文、规格说明和 CLAUDE.md 文件时，AI 输出会更好。
• Claude 会可靠地“读”完所有内容；而同事往往不会。这让为 AI 写作的投入回报率显得高得多。
• 为 Claude 写的文档只看信息含量，不看文风质量，所以人们愿意丢进去粗糙的笔记、口述内容和那些若是给人看会觉得丢脸的垃圾内容。
• 有人认为，开发者并不是在 为 Claude 写文档，而是在为自己以及任何使用 Claude 的人写；AI 只是终于保证了会有一个认真阅读的读者。

人类与 AI 使用文档的方式

• 很多人都提到，多年来认真写文档却被同事无视，结果还是被问同样的问题。
• 一些团队尝试强制“先读文档”的文化（比如问对方去哪里查过、把文档习惯与绩效评估挂钩），但效果褒贬不一。
• 还有几个人指出，大多数人根本不会看屏幕上的文字；很多公司属于“口头文化”。
• AI 因为能阅读大量杂乱的文档集、交叉参考 PR、工单、wiki 页面，并根据一个人当前的理解程度调整解释方式而受到称赞。

质量、漂移与维护

• 一个反复出现的抱怨是：CLAUDE.md 和 AI 生成的文档很快就会过时，甚至会误导未来的 AI 会话，连已删除的类和架构都会被“幻觉”出来。
• 有些人对此的反应是直接删除这类文件；另一些人则加入代理来维护少量“活文档”（概览、关键流程），并丢弃临时计划。
• 行内文档（例如 jsdoc 风格）和构建时文档提取被认为是让代码与文档保持一致的方法。
• 一个经验法则是：如果 LLM 不能从你的文档中推导出正确答案，那说明这些文档本身可能就不清楚或有错误。

新工作流与工具

• 人们描述了自定义“技能”和代理：并行代码审查员、无限 issue 生成器、检测漂移的文档代理，以及通过 Claude 维护的仓库概览。
• 规格说明、设计文档和决策文档正变得居于核心位置，既用于团队对齐，也用于驱动代理；有些人预见规格格式会演变成 AI 的事实标准“编程语言”。

热情与怀疑

• 乐观者报告了 4–8 倍的生产力提升，并认为由于规格和架构文档能直接提升实现速度，它们正在迎来复兴。
• 怀疑者警告说，LLM 的输出是非确定性的、部分错误的、冗长的，而且可能助长一种不太社交、由 AI 中介的协作方式。
• 还有人担心，大量由 AI 生成的文档堆会难以阅读、很快过时，并最终变得可有可无。