【AI风向】程序员宁给Claude写文档也不给同事写：HN热帖揭示AI如何重塑代码协作

一篇博客引发109分105条评论的热议：程序员为AI写文档的热情远超为人写文档，这背后是整个软件开发协作模式的深层变革。

事件回顾

6月5日，Hacker News上一篇文章《Programmers will document for Claude, but not for each other》迅速登上热榜，获得109个点数、105条评论。文章作者Mark Dominus（知名程序员博主）指出了一个令人深思的现象：

那些多年来拒绝为同事写文档的开发者，现在正热情地为Claude（Anthropic的AI编程助手）编写详细的使用说明和工作流程文档。

这种现象不是一两个人的奇怪选择，而是在整个开发者社区中普遍出现。HN评论区里，大量开发者现身说法，承认自己确实在"只给AI写文档"。

"我多年来写了大量文档，人类总是来问我文档里已经回答了的问题，但他们从来不看，"评论者ang_cire写道。"Claude不一样——它真的会读。"

为什么程序员"区别对待"

1. AI真的会读文档

这是最核心的原因。多位HN评论者指出了一个残酷的事实：人类同事几乎从不阅读文档，而是直接跑来问问题。但LLM不同——它会逐字处理你提供的每一段说明文字。

"Claude A) 阅读文档 B) 需要文档 C) 能快速写文档——这三条你的同事一条都做不到，至少不是稳定做到，"评论者empath75总结道。

2. 给AI写文档的"门槛"更低

另一个有趣的发现是：给AI写的文档不需要漂亮的格式、清晰的结构或优美的文风。评论者kuboble指出："给Claude写的文本只有一个要求——意图和含义必须传达。不需要结构，不需要风格，不需要排版，不需要深入思考。"

这意味着那些"不会写文档"的工程师（通常以此为借口逃避文档工作）突然发现，给AI写一段随性的文字说明就够了——这比写人类可读的正式文档容易得多。

3. 投资回报不同

"浪费token显然比浪费员工时间更糟糕，"评论者loglog的话一针见血。当AI编程助手用token来计量成本时，清晰的文档能直接节省token消耗——这是一个可量化的ROI。而给人类同事写文档的回报则是间接的、难以衡量的。

4. Claude永远不会抱怨

多个评论提到，人类同事对文档要求很高——格式不对、不够详细、不是他们想要的风格——但Claude从不抱怨。它默默读完你给的任何东西，然后尽力工作。

▲ 程序员为AI写文档 vs 为人写文档：结构化的力量

这不是孤例：AI正在重塑开发者行为

这个现象只是AI改变开发者行为模式的冰山一角。在同一个HN讨论日，另一篇文章《Did Claude Increase Bugs in Rsync?》也引起了关注（61分55评）。作者对rsync项目进行了统计分析，试图回答"Claude辅助的代码提交是否引入了更多bug"。

这反映出一个更大的趋势：开发者正在围绕AI工具重新定义自己的工作习惯。包括：

• 为AI写专门的"工作指南"（而非面向人类的README）
• 调整代码注释风格使其更适合LLM解析
• 创建AI专属的prompt库和skill文件
• 用token效率作为代码/文档质量的衡量标准

正如评论者Pxtl所说："我们发现软件现有的API列表式文档对AI来说不够好，我们需要提供'如何使用这个软件解决常见问题'的指南。"

对AI创业者的启示

▲ AI正在重塑知识管理：给AI的文档取代了落灰的团队Wiki

启示1：AI-native文档是新兴市场

如果你的产品面向开发者，仅提供传统的API文档已经不够了。你需要为AI Agent提供专门的"使用手册"——结构化的、面向LLM的文档，让AI能直接理解如何在你的平台上操作。这正在成为一个新的产品设计维度。

OpenClaw和Hermes Agent社区已经出现了大量"skill开发指南"类的文档——它们不是写给人类看的使用手册，而是写给AI Agent看的工作说明书。这种"AI-native文档"的需求将快速增长。

启示2：团队协作工具需要"AI可读层"

现有的团队协作工具（Jira、Confluence、Notion）设计之初是面向人类可读的。但未来的协作工具需要支持双层文档——一层给人类看（带格式、视觉元素），一层给AI看（结构化、语义化）。

评论者jerf分享了一个实操案例："我已经'滥用'这个现象好几次了，把那些我们多年没写的文档都补齐了——代码文档、部署文档、概览文档、架构文档……"这意味着AI工具可以成为推动组织知识管理的杠杆。

启示3：一人公司的效率武器

对于一人公司和独立开发者，这个现象是巨大的利好。你不需要一个团队来消化和维护文档——只需要把知识写给AI Agent，它就能在你需要时调用。一人公司的"组织记忆"现在可以由AI来承载。

评论者samuelknight总结道："我很早就学会不要写长邮件，因为人们根本不读。LLM正相反——它会关注你prompt中的每一个词。"

风险提示

当然，这种现象也有其阴暗面：

1. AI文档可能是"高质量垃圾"：评论者cyanydeez警告，给AI写的文档往往"70%完整、10%间接、20%错误"，这种非结构化的"slop"积累起来对团队知识管理是灾难。
2. 团队生产力 ≠ 个人生产力：评论者dude250711指出，Claude提升的是你的个人生产力，但不一定提升团队生产力。如果每个人都把自己的知识塞进AI而不与团队共享，最终会形成知识孤岛。
3. 依赖AI的文档可能随模型过时：写给Claude的文档在不同模型间的可迁移性存疑。

行动建议

1. 建立"AI文档"与"人类文档"的双轨制：核心知识库面向人类，操作指南面向AI
2. 用AI倒逼文档文化：如果团队不肯写文档，至少让他们为AI写——这是一个低摩擦的起点
3. 投资AI-native开发工具：关注那些支持"AI可读文档"的新一代开发平台
4. 一人公司优先：把工作流、业务逻辑、客户信息写成AI Agent可读的skill文件

本文由AI辅助创作，经人工审核编辑发布