8.0
热点
AI SCORE
技术实践2026-08-02 00:38
AI时代文档成为代码的运行手册
dev.to · AI#AI工程#文档#最佳实践
Editor brief · 编辑速览
源代码说WHAT，文档说WHY；AI需要完整的系统运行手册才能理解架构选择和权衡，文档质量成为AI工程关键。
Founder 日志 #8——为什么 AI 在理解你的软件之前，会先阅读文档
“几十年来，源代码一直是终极事实来源。在 AI Engineering 时代，文档正逐渐成为赋予源代码意义的操作手册。”
软件工程中最古老的原则之一是：
“源代码是终极事实来源。”
代码定义了软件实际执行的行为。
文档可能会过时。
图表可能不准确。
规范可能逐渐偏离实现。
当冲突发生时，工程师会相信代码。
这项原则一直很好地服务着我们的行业。
但 AI 带来了一种新的视角。
不是因为源代码变得不再重要。
而是因为仅靠源代码已经不够了。
现代 AI 模型在阅读源代码方面表现得非常出色。
它们可以解释函数。
提出优化建议。
然而，它们经常难以回答一个更棘手的问题：
这个系统为什么存在？
源代码告诉 AI 软件做了什么。
为什么选择这种架构。
为什么选择一个数据库而不是另一个。
为什么接受某项特定的权衡。
为什么某个模块绝不能依赖另一个模块。
为什么一个看似低效的实现被有意保留下来。
意图很少被编码在代码中。
意图存在于其他地方。
好的文档不只是操作说明。
它还承载着工程知识。
想想成熟的工程团队通常会维护哪些文档：
架构决策记录（Architecture Decision Records，ADRs）
部署流程
工程宪章
这些文档共同描述的不只是工程师构建了什么，还包括工程师如何思考。
当 AI 参与软件开发时，这一区别会变得越来越重要。
面对复杂项目，一种常见做法是提供更长的 prompt。
最终，prompt 开始包含：
架构摘要
部署说明
这时，一件有趣的事情发生了。
prompt 开始模仿文档。
与其编写越来越庞大的 prompt，也许我们更应该改进那些 AI 可以持续引用的工程文档。
结构良好的文档，其扩展能力远胜于不断膨胀的对话。
传统上，文档是为人类编写的。
工程师偶尔会阅读它。
新团队成员会在入职期间查阅它。
几个月后，其中的大部分内容就会被遗忘。
AI 改变了这种局面。
AI Agent 可以持续查阅工程文档。
每一份设计提案。
每一次实现。
文档不再是被动的。
它会成为主动运转的工程基础设施。
设想两个软件项目。
第一个代码仓库包含：
AI 必须自行推断其他一切信息。
第二个代码仓库包含：
参考架构（Reference Architecture）
工程宪章（Engineering Constitution）
文档标准（Documentation Standards）
架构决策记录（Architecture Decision Records）
现在，AI 在开始每项任务时，依靠的是工程上下文，而不是主观假设。
两者之间的差异非常深远。
AI 的智能水平可能完全相同。
但它们所处的工程环境并不相同。
想象这样一个函数：
func ProcessPayment() {}
它的实现可能在技术上完全正确。
但代码无法回答以下问题：
为什么付款需要异步处理？
为什么必须保证幂等性？
为什么优先选择队列，而不是直接执行？
为什么重试逻辑被限制为三次？
为什么这个服务绝不能直接访问客户数据？
这些决策都属于工程知识。
缺少这些知识，AI 在修改代码时就可能无意中违背系统的设计原则。
不应该把文档当成一种编写一次便无人问津的项目产物。
相反，它应该与软件共同演进。
每一个架构决策。
每一次工作流改进。
每一项工程标准。
这些变化都应该成为项目共享知识的一部分。
能够让人类工程师受益的动态文档，同样也会让 AI 受益。
NAEOS 的基础理念之一，就是文档绝非事后才考虑的附属品。
它是运行时环境的一部分。
参考架构定义系统边界。
工程宪章定义不可妥协的原则。
策略定义组织规则。
标准定义一致性。
决策记录保留历史上下文。
它们共同构建出一种工程环境，让 AI 能够清晰地开展工作，而不是依靠猜测。
目标不是取代人类判断。
目标是让人类和 AI 都能访问同一套工程知识。
基础设施是每个系统都依赖的东西。
数据库是基础设施。
网络是基础设施。
身份服务是基础设施。
在 AI 时代，文档也正在加入这一行列。
并不是因为文档可以执行代码。
而是因为它会影响代码如何被设计、审查、生成和维护。
工程知识正在进入实际运行过程。
文档回答了一个重要问题：
接下来的问题同样重要：
哪些知识最重要？
在下一篇文章中，我们将探讨：为什么上下文对 AI 质量的影响，往往大于模型规模、基准测试分数或参数量。
因为在软件工程中，正确的上下文总能胜过单纯的智能水平。
如果你只能为当前项目改进一种工程文档，你会选择哪一种？
架构文档。
我很想知道，哪类文档为你的团队带来了最大的价值。
如需采取进一步行动，你可以考虑屏蔽此人和/或举报滥用行为。