程序员愿为 Claude 写文档，却不愿为同事写

背景

近期在开发者社区（如 Hacker News）中，出现了一种普遍且令人沮丧的现象：许多程序员愿意花费大量精力编写详细的 CLAUDE.md 或 PROJECT.md 文件，以便让 AI 助手 Claude 更好地理解和执行任务；然而，对于同样需要这些上下文信息的同事或未来的自己，他们却缺乏同样的动力去维护这些文档。

这种“双重标准”引发了关于技术债务、协作效率以及人机协作本质的讨论。Mark Dominus（陶敏修）作为资深 Perl 程序员和技术作家，针对这一现象分享了他的实践经历与反思。

核心内容

Mark Dominus 首先描述了他自己在大型项目中利用 Claude 进行“交接”（handoff）的工作流。由于 Claude 会话具有上下文限制或中断风险，他习惯让 Claude 维护一份交接文档，记录计划做什么、已完成什么以及其他 pertinent（相关）信息。当关闭一个 Claude 会话时，他会启动下一个 Claude 实例读取该文件以快速上手，随后由新的 Claude 更新文档供下一个实例使用。

起初，Dominus 在每次项目结束时都会丢弃这些交接文档。但在目睹了社区中关于“程序员不愿为同事写文档”的抱怨后，他产生了一个想法：既然保留这些文件毫无成本，为何不将其提交到代码仓库中？未来的开发者可以通过 git grep 搜索并从中获取有价值的信息。

随后，他优化了这一流程。在项目结束时，他不再仅仅保留运行笔记，而是要求 Claude 从头撰写一份详细但宏观的项目总结，阐述所解决的问题及所做的更改。Dominus 会像审核人类程序员的工作一样，仔细审查并编辑这些总结，确认无误后才提交。他认为，既然代码提交代表了他的签名和薪资所得，那么进入仓库的任何内容都必须经过他的仔细审阅和理解。

令人惊讶的是，Claude 生成的解释几乎不需要太多编辑。其最新的项目总结质量与他亲自撰写相差无几，甚至有时更好。撰写过程仅需十秒，而审查过程也远少于一小时。

Dominus 还分享了一个有趣的“事故”：在一次审查中，他发现 Claude 复制了之前报告中的一段特定文字，那是他之前手动添加的声明：“# Approved-by Claude 从我们的讨论中抽象了这些笔记。Mark Dominus 已阅读、审查、编辑并批准了这些笔记。” 虽然这次内容属实无需删除，但他随即指示 Claude 在 CLAUDE.md 中增加指令，禁止其再次复制此类元数据段落。

关键要点

• 打破文档偏见：程序员往往对 AI 极其慷慨，愿意提供详尽的上下文文件（如 CLAUDE.md），却对同事吝啬同样的信息。Dominus 建议将 AI 生成的文档视为团队资产，提交至代码仓库供他人查阅。
• 自动化项目总结：在项目结束时，利用 AI 生成一份结构化的、高层级的项目总结（涵盖问题背景、解决方案和变更细节），而非仅保留零散的运行笔记。
• 人机协作的审核机制：AI 生成的文档质量已接近人类水平，但开发者仍需扮演“编辑”和“审核者”的角色。这不仅是质量控制，更是开发者确认自己理解项目全貌的过程。
• 提示词工程的重要性：AI 可能会产生幻觉或不当复制（如错误地添加批准签名），开发者需要通过迭代提示词（如在 CLAUDE.md 中明确指令）来规范 AI 的行为。
• 低成本的长期收益：提交这些文档几乎零成本，但可能为未来的开发者（包括未来的自己）提供巨大的便利，帮助其通过版本控制工具快速理解历史决策。

意义与影响

这一实践揭示了 AI 时代软件开发工作流的一个潜在范式转变：AI 不仅是编码助手，更是知识管理的协作者。

1. 缓解技术债务：传统上，文档维护被视为低优先级任务，导致项目后期文档缺失。将文档生成自动化并嵌入开发流程，可以显著降低知识流失的风险。
2. 重新定义“同行评审”：在 AI 辅助编程中，同行评审的对象从“代码”扩展到了“上下文与决策逻辑”。开发者对 AI 生成文档的审核，实际上是对项目架构和设计决策的最终确认。
3. 促进团队知识共享：如果开发者能像对待 AI 一样对待同事，或者利用 AI 生成的高质量文档作为团队沟通的桥梁，可能会缩小“为 AI 写文档”与“为同事写文档”之间的鸿沟。
4. 对开发者的警示：Dominus 的经历提醒我们，虽然 AI 能高效生成内容，但人类开发者必须保持批判性思维，确保进入版本库的内容准确、合规且经过深思熟虑。AI 是高效的起草者，但人类仍是最终的把关者。