程序员与向以 AI 为中心的文档编写方式的转变

以 AI 为中心的文档编写方式的兴起

软件开发人员正越来越多地投入时间来创建详细的文档——例如 CLAUDE.md 和 PROJECT.md 文件——专门用于指导 AI 编程代理（AI coding agents）。这种转变之所以发生，是因为 AI 代理能为高质量的上下文提供即时且切实的回报，而为人类同事编写的文档往往因为缺乏阅读量和反馈而被视为一种低投资回报率（low-ROI）的活动。

使用 AI 来记录 AI

AI 代理不仅可以被用来消费文档，还可以被用来生成文档，从而创建一个项目知识管理的自我维持循环。维护此类知识的有效策略包括：

• 交接文档： 使用 AI 来维护一份包含计划、已完成任务和相关信息的运行日志，以便在不同的 AI 会话之间保持状态。
• 项目摘要： 在项目结束时，要求 AI 生成一份关于所解决问题和所做更改的高层级、结构化概述。随后，人类可以对该摘要进行审查，并将其提交到仓库中作为永久的历史记录。
• 迭代优化： 使用 AI 生成的摘要作为基准，这比从头开始编写一份全面的文档需要的时间要少得多，便于进行审查和编辑。

为什么程序员更倾向于为 AI 而非人类编写文档

行业从业者强调了几个心理和技术层面的原因，解释了为什么为 AI 编写文档比为人类编写文档更具吸引力：

保证的阅读量与即时反馈

AI 代理被视为终极的 "RTFM"（Read The F***ing Manual）用户。与那些可能会跳过文档并在会议中提问的人类同事不同，AI 代理会系统地处理提供的上下文以改进其输出。

"Claude 是愿意阅读其他文档以理解我的意图的... 当我被要求为人类编写文档时，我必须付出四倍的努力，因为其中 3/4 的工作量在于让受众跟上进度... 然后他们还是不看文档，还是在会议上要求我解释一遍。"

较低的散文写作门槛

为 AI 编写内容时，对风格、格式和社会判断的要求较低。开发人员可以提供原始的、口述的或非结构化的信息，因为他们知道 AI 可以提取出其中的含义，而不会对文字质量进行评判。

"给 Claude 的文本只有一个要求——意图和含义必须存在... 我扔给他的文字质量低于我向任何其他人类展示的水平。"

绩效指标的转变

随着组织推动开发人员转向代理式编程（agentic coding），为 AI 提供有效运行所需的必要上下文的能力，正成为一项关键绩效指标。文档编写正从一种 """thankless task"""（无功无德的任务）转变为维持生产力和保住工作的必要手段。

风险与反论点

虽然 AI 生成的文档增加了内容的容量，但它也带来了新的挑战：

• 文档腐烂： 生成海量文档的便捷性可能导致 """write-only"""（只写不读）文档的出现，这些文档会迅速变得陈旧和过时。一些开发人员认为，代码应该保持为唯一的真理来源（single source of truth），而文档应在需要时动态生成。
• "Chatbot" 未来： 有一种担忧，即程序员的角色正在从解决问题转向仅仅是提示（prompting）和管理 AI 代理，这可能会导致人类员工在深度技术理解力方面的下降。
• 历史噪声： 为每个功能都过度生成设计文档，可能会创建一个过于庞大而无法使用的历史存档，导致人们在工作完成后倾向于删除它们。