程序员和文档，大概是这个世界上最冷漠的“室友”。
代码在 Git 仓库里日更夜更，文档在 Confluence 或 Notion 里独自吃灰。代码跑得飞快，文档永远停留在上个版本——甚至上上个版本。
老实讲，谁有空去同步那些没人看的东西？
但有意思的是，AI 的出现，竟然强行修补了这段破裂的关系。
为了能让 AI 乖乖干活，程序员们不得不把那些吃灰的文档，重新搬回代码仓库。这不只是工具的变迁，更像是一场工程师工作流的各种“打脸”现场。
那些年我们欠下的“文档债”
“代码就是最好的文档。”
这句话你是不是听了无数遍？甚至你自己就是这句格言的信徒。
但这往往是个谎言。正如素材中那句中国谚语所说：“好记性不如烂笔头。” 代码能告诉你怎么做，但永远不会告诉你为什么这么做。
以前，我们有一万个理由不写文档，或者把文档扔到外部系统里：
- 版本不同步：Git 管代码，Confluence 管文档，两边各过各的，谁也不理谁。
- 维护太麻烦：API 改一行，文档要改三页，复制粘贴能点到鼠标手抽筋。
- 审批流断裂：代码合并了，文档还在等 PM 审批，甚至根本没人想起来要更新。
结果就是，项目跑得越久，文档就越像一本“上古天书”，除了作者没人能看懂，连作者自己过了一年也得抓瞎。
现在，AI 来了，它不吃这一套。
AI 不读“天书”，它只要“说明书”
AI Agent 正在改变游戏规则，而且改得很粗暴。
如果你想让 AI 帮你写代码、改 Bug，它得先懂你的项目。你把代码扔给它，它确实能读懂逻辑，但它读不懂你的“意图”，更读不懂那些藏在代码背后的业务逻辑和架构决策。
素材里提到一个观点特别扎心：工程师的工作重心正在“左移”。
以前我们写机器码，后来写 C，再后来写高级语言，现在呢？我们甚至不需要写代码，而是直接写“规范”和“指南”。
就像我们不需要审查编译器生成的机器码一样，未来我们可能也不需要审查 LLM 生成的代码，只要它遵守了规范和指南。
这意味着什么？意味着文档变成了真正的“代码”。
AI Agent 解决了一个最让人头疼的问题：陈旧文档。
以前大家不写文档的理由是“代码改了文档没改，不如不写”。现在？AI 可以自动帮你对齐。它能检查 PR（Pull Request）里的代码变动，然后自动提醒你：“嘿，这部分逻辑变了，文档是不是也得改改？”
甚至，你可以直接下指令：“看看 API 和文档，找出过时的部分。”
这哪里是工具，简直是请了个免费的文档保姆。
仓库才是文档的“最终归宿”
把文档移回 Repo（代码仓库），这听起来像是复古，其实是进化。
素材作者列举了一堆好处，但我个人觉得最狠的一点是：利用 Git 的版本控制能力。
当文档和代码住在一起时，奇迹发生了：
- 搜索一体化：用
grep或rg搜代码时，顺便把文档也搜了。 - 测试文档化：Python 的 doctest 直接把文档当测试用例跑，文档写错了测试就挂，看你还敢不敢乱写。
- 审批同步化：代码改了，文档必须跟着改，不然 PR 过不去。
这不仅仅是方便，这是一种强制约束。
评论里有位老哥说得更直白：“最大的赢家不是 AI，而是 PR 终于不能在没有更新文档的情况下落地了。”
这就好比把零食锁在了健身房里，你想吃？得先练练。
有意思的是，素材里还提到了一个细节：AI Agent 提交的 Commit 里，Markdown 文件的比例大幅上升。
为什么？因为大家在给 AI 写“规则文件”（.mdc files）。但作者一针见血地指出：这 80% 的规则文件，本来就该是文档。
以前懒得写，现在为了 AI 能懂，不得不写。这算不算一种“技术赎罪”？
这事儿十年前就该干了？
当然，这事儿也不是没人喷。
评论区里有人直接开怼：“这难道不是 10 年前的最佳实践吗？GitHub Pages 2008 年就出了。”
确实，把文档放进 Repo 并不是什么新发明。但为什么以前推不动？
因为人性是懒惰的。
如果没有 AI 这个“刚需用户”逼着你把上下文整理清楚，大部分项目依然会是“代码如山倒，文档如抽丝”。
还有一个更讽刺的评论：“开发者直到有了 AI 这个‘伪用户’来索要上下文，才发现原来自己一直需要文档。”
以前 PM 催文档，你说忙；现在 AI 催文档，你不敢不写——毕竟 PM 骂你你能顶嘴，AI 骂你（或者说 AI 瞎写代码），你修 Bug 能修到哭。
不过，也不是所有人都买账。
有人就担心，Markdown 这种纯文本格式，在大组织里协作起来简直是灾难。没有 Confluence 那种所见即所得的编辑器，让非技术人员去改 Markdown？简直是让他们去解方程。
这确实是个问题。素材里也承认，对于活跃的协作编辑，Google Docs 依然是无敌的。但一旦文档定稿，“Copy as Markdown” 扔进 Repo，或许才是它最好的归宿。
写在最后
AI 正在倒逼工程师变得“更专业”。
它逼着我们写测试，逼着我们写注释，现在又逼着我们把文档整理好。
这听起来有点累，但仔细想想，这不就是我们一直向往的“工程化”吗？
或许未来，程序员真的会变成“文档工程师”。我们的核心技能不再是写 for 循环，而是写好那份能让 AI 和人类都读懂的“说明书”。
至于那些还在把文档扔在角落吃灰的朋友，听我一句劝：赶紧搬回 Repo 吧，AI 的眼睛可是雪亮的。
【glm-5锐评】：程序员为了偷懒让AI干活，不得不勤奋地写文档喂给AI，这大概是科技圈最大的“回旋镖”。
参考链接：
https://www.dein.fr/posts/2026-03-13-its-time-to-move-your-docs-in-the-repo