本文翻译自 It’s time to move your docs in the repo，原载于 Hacker News。
再淡的墨水也比最强的记忆可靠。—— 中国谚语
当谈到将所有文档放在代码仓库中时，AI 彻底改变了游戏规则：保持文档更新从未如此简单！
我一直以来都是文档与代码共存理念的坚定支持者：
为什么文档应该和代码在一起？
版本控制（Version Control）
就像代码一样，文档也需要演进。既然你已经在使用 Git，为什么还要用不同的版本控制系统？尤其是当多人同时修改文档时，可能会产生冲突变更。
与代码的邻近性
使用 rg 或 grep 搜索时，会同时返回代码和文档结果，这让保持文档更新变得更容易。
正式审批流程
秉持文档驱动开发（Documentation-Driven Development）的精神，先审阅文档更新有助于理解最终产品/API。（对于主动协作，Google Docs 等工具仍提供更优的用户体验。）
自动生成
当使用不同的系统托管文档（Google Docs、Confluence、Notion 等）时，复制粘贴 API 和示例代码相当繁琐。而 Sphinx 的 autodoc、jsdoc、javadoc、docusaurus 等工具可以直接从代码生成 API 文档。
测试
文档中的静态代码示例是个好的开始，但如果能测试它们就更好了。将文档中的代码示例运行纳入持续集成流程，可以做到这一点。参考 Python 的 doctest。某种意义上，文档即规范。
高效编辑
你可以利用所有文本编辑器工具，还能批量脚本修改。
我们将花更多时间写文档
第一个观察：AI agents 大幅增加了提交中 markdown 文件的比例。这通常是因为人们会审阅 agent 的实现——这想法很棒。同时，编写规则文件（.mdc files）来引导 agent 执行也能节省大量迭代时间。所以，无论你是否认同这个论点，它正在发生。
我认为 80% 的规则文件本可以是文档，或者可能已经在其他地方有记录。就像代码主要是为人阅读而写，仓库中的所有文件首先是供人审阅的。这也适用于为引导 agent 执行而创建的规则文件。规则文件越来越像我们从未费心编写但本该固化的风格指南和最佳实践。
AI 专用 markdown 和人类专用之间的界限如此模糊，我完全可以预见规则文件完全消失，被文档取而代之。
这也与工程师向左迁移（shifting left）的趋势一致。工程工具已经向越来越高的抽象层发展：从机器码到 C，到动态语言，到 SDK，到现在甚至不写代码，只关注规范和指导原则。就像我们不审阅编译器生成的机器码一样，也许有一天，只要 LLM 生成的代码遵循框架、规范和指导原则，我们就不需要审阅它（安全将是关键考量）。在那个世界里，我们将把大部分精力放在审阅规范、框架和指导原则上。结论：这些文档首先需要为人审阅而写。
为什么 AI 让文档入仓变得更有意义
AI agents 解决了文档过时的问题
反对写文档的常见理由是：”何必呢？读代码就行了——代码永远是最新的。”（同样的逻辑也可以用来不刷牙）。AI agents 解决了这个问题。它们承担了确保代码与文档对齐的繁琐工作（在 PR 中，或通过专门的审阅 agent 查找文档不一致）。这真是颠覆性的改变。
AI agents 受益于更高层次的上下文
将文档（包括架构提案 RFCs、产品规范 PRDs 等）放入仓库，会提供额外的上下文。
物化的计划能节省 token 和迭代时间
想象一下在一个庞大的代码库中研究”做 X 的最佳方式”。你会花费大量 token 来找到答案。将答案记录下来并物化到仓库中，可以让你的同事跳过研究步骤（并随着额外学习和最佳实践保持更新！）。这对于 agent 无法从代码中推断的事物尤其重要：典型的例子是你通过部署代码到生产环境学到的基础设施相关知识。例如，我花了大约两周时间研究和迭代结构化日志的最佳实践——我将其物化为一个”元计划”，其他团队可以直接使用，为大家（包括 agents！）节省了大量时间！
回应反对意见
可以用 MCP 和其他方法（skills）给 agent 访问文档的权限
但我开头列出的论点仍然适用，尤其是版本控制。大多数文档系统不是为快速迭代和强并发控制设计的。
等待代码审阅会阻碍文档更新
(1) 如果不是你写的这些文档呢？(2) 谁说所有仓库内容变更都需要审阅？(3) 随着我们越来越向左迁移，文档变更或实现计划会不会变成最重要的审阅内容？
AI agents 写又长又复杂的文档
首先，大多数人也是这样 :）。就像代码一样，你应该 (1) 审阅 agent 的工作，(2) 修正 agent 的工作，(3) 自己写文档（就像这篇文章：没有任何内容是 AI 生成的！）。放入版本控制使迭代变得更加容易和安全（有审阅！有历史记录！）。
真的需要把所有文档都移过来吗？
我会说是的，在这一点上。不是那些短暂的文档，而是所有提供代码库有用上下文的内容，包括 RFCs。
[你喜欢的工具] 更擅长 [表格/图表/链接]
AI 在生成 mermaid 图表（GitHub 支持）、表格等方面已经变得非常出色。
[你喜欢的工具] 更适合人类协作
是的，Google Docs 仍然更适合主动协作，所以继续用于那个用例是合理的。但一旦文档趋于成熟，我会把它移到仓库里（Google Docs 有一个很有用的”复制为 Markdown”功能，我经常使用）。
非工程师通常没有仓库访问权限
(1) 你可以在内部网站上部署文档。(2) 非工程师代码访问有明显趋势（这带来一些有趣的安全挑战）。
参考资料
一如既往，我的仓库 charlax/professional-programming 有更多资源：
- Specifications Are Becoming the Real Source Code
- Getting AI to Work in Complex Codebases
- Documentation-Driven Development
- Writing automated tests for your documentation
- 🏙 Documentation is king, Kenneth Reitz
- The documentation system
- Write documentation first. Then build.
- Diátaxis: a systematic approach to technical documentation authoring
总结
在 AI 时代，将文档放入代码仓库不再是”锦上添花”，而是势在必行：
- AI 让维护文档变得轻松 - 不再有”文档过时”的借口
- 文档即规范 - 未来我们可能更多审阅规范而非代码
- 上下文为王 - AI agent 需要高层上下文才能更好地工作
- 节省资源 - 物化的知识能节省团队和 AI 的时间和 token
是时候重新审视你的文档策略了。