AI Coding 真正的价值，不是写代码变快，而是把讨厌的文档变成了核心资产

这些年做软件开发和技术管理，我始终觉得写文档是团队里一件很尴尬的事。需求说明、系统设计、接口文档、测试用例，大家都知道应该写，可项目一忙起来，最容易被推迟的也是它。功能上线后再补，往往又有新的需求排进来；好不容易补齐，几轮修改之后，文档和代码可能已经对不上了。

以前我也习惯把这种情况看作开发效率与流程要求之间的矛盾。但最近使用 AI Coding 工具、思考 Context Driven Development（上下文驱动开发）时，我发现自己对文档的态度变了。过去总想着怎样少写一点，现在反而希望项目能把每次需求变化、方案选择和验证结果留下来。让我改变想法的，并不只是 AI 能够替人写文档，而是这些材料终于有机会在后续开发中被反复使用。

一、我们减少了文档，却没有消除理解系统的成本

2001 年的《敏捷软件开发宣言》提出，“可工作的软件高于详尽的文档”。它要纠正的是流程和文档过重、反而拖慢交付的问题，并没有说文档不重要。但在一些团队的实践中，这条原则逐渐被简化为“代码就是最好的文档”。只要命名清晰、结构合理，许多技术细节确实没有必要再写一遍。

问题在于，一个项目除了“如何实现”，还有“为什么这样实现”。系统运行几年后，某个字段为什么不能删除，某段判断为何只针对一个渠道，某个接口为何一直保留兼容逻辑，代码可以展示现状，却未必保存当年作出决定的原因。负责这部分业务的人如果已经离职，新接手的工程师只能翻提交记录、找旧工单，或者在测试环境反复验证。

我接触过长期运行的业务系统，因此很清楚，读懂程序的执行过程，有时只是维护工作的第一步。真正耗时间的是确认哪些规则可以改，哪些看似多余的代码承载着历史约束。过去这些知识往往散落在会议、聊天记录和个别同事的记忆里，文档一旦长期无人更新，团队就更加依赖口口相传。看上去省下了写文档的时间，后来却可能用更多时间重新调查同一件事。

二、AI 能解释代码，却不能凭空还原历史决策

AI Coding 已经明显降低了读代码的门槛。把代码仓库交给 Coding Agent，它可以梳理模块依赖、解释函数调用、找出实现某项功能的位置，也能整理出调用关系。我在日常开发中也越来越习惯先让 AI 帮我理解现有系统，再考虑怎样修改。

但“读懂当前逻辑”和“知道当初为什么这样设计”，是两回事。拿我熟悉的酒店预订业务举个例子：一个订单取消功能，可能根据销售渠道、房型、入住时间和付款方式执行不同退款规则。AI 可以列出所有条件分支，却不一定知道某条特殊规则来自酒店合同、支付渠道要求，还是过去的一次故障。假如原始记录不存在，它给出的解释只能是推断。

这种区别在 AI 时代甚至更值得警惕。因为 AI 很擅长把零散信息整理成一份结构完整、措辞确定的文档；如果没有明确标注哪些是已核实的业务事实、哪些只是从代码推测的原因，后来的开发者就可能把推测当成依据，再交给下一轮 AI 继续使用。

因此，我希望保留下来的并非每段代码的文字翻译，而是业务目标、关键约束、方案取舍以及变更原因。Martin Fowler 在 2026 年介绍的架构决策记录（ADR）就是一种可参考的方法：简短记录决策发生时的背景、理由和结果，后续方案取代它时保留历史关联。这类信息很难单靠代码自动恢复，却可能决定下一次修改是否安全。

三、文档开始从交付附件，变成 AI 开发过程的一部分

过去的文档主要写给人看。需求用于沟通，设计用于评审，测试报告用于验收。它们当然影响开发，但在很多项目里，文件写完便放进知识库，下一次迭代未必有人打开。现在这种关系开始变化：经过确认的文档可以直接成为 Coding Agent 的输入，约束它怎样计划、实现和验证任务。

GitHub 的 Spec Kit 把需求规格、技术计划、任务拆解和实现连接起来；Codex、Claude Code 也分别支持通过 AGENTS.md、CLAUDE.md 保存项目约定。2025 年 12 月，Google 发布 Gemini CLI 扩展 Conductor，使用了 Context-Driven Development 这个名称，强调把项目背景和工作计划存入代码仓库，而不是只留在一次聊天里。这些产品的做法不完全相同，但都在尝试让上下文跨越单次对话，成为团队与 AI 可以持续使用的资料。

2026 年 Stack Overflow 开发者调查也从侧面说明了上下文的价值。在关于项目最需要哪些信息的提问中，85.2% 的受访者选择项目目标或需求，73.3% 选择代码、仓库或技术文档，还有 44% 选择历史决策及理由。调查反映的是受访者对信息重要性的认识，不能直接证明写文档提高了多少开发效率，但它说明，一个可靠的开发任务需要的材料远不止代码。

这改变了文档的投入产出关系。过去工程师写一份规范，可能只是供新人阅读；现在同一份准确的规范，也可以在后续开发、审查和测试中反复使用。写文档不再完全是开发之外的额外劳动，因为 AI 可以根据经过确认的需求、代码变更和测试结果协助起草、整理和更新。

这也是我理解的 AI Coding 文档管理：让文档持续参与开发，而不是写完后就放进知识库。不过，这并不意味着把仓库里的所有资料一股脑交给 AI 就会更有效。文档必须可信、能找到，并且与实际系统保持一致。否则，旧规范可能比没有规范更麻烦：AI 会认真执行一个早已失效的要求。

四、上下文驱动开发：让每一次开发都留下可复用的知识

我所说的上下文驱动开发，并不是开发前先写一份很长的提示词，也不只是把需求文档交给 AI 生成代码。更有价值的做法，是让开发过程中的关键知识形成闭环：需求说明为什么做，设计记录如何选择，代码落实实现，测试证明哪些条件得到了验证，变更记录再把实际结果带回项目上下文。

以一次功能迭代为例，人先确认业务目标和边界，AI 可以协助分析现有系统、生成设计草案、拆分任务；方案经过审查后，AI 再执行编码与测试，并整理接口变化和实现结果。开发中如果发现原方案需要调整，重要的不只是修改代码，还要把调整的理由和新的约束记录下来。这样，下一次接手任务的人或者 AI，至少有机会沿着需求、决策、代码和测试之间的关联，弄清系统为什么变成今天这样。

对长期运营的软件来说，这可能比单次节省多少编码工时更有意义。企业多年积累的除了代码和数据库，还有对客户、业务规则和技术取舍的认识。过去这些知识常常依附在具体的人身上；如果能随项目一起沉淀，人员交接、故障排查和后续重构就不必总是从头摸索。当然，这是一种值得验证的长期收益，不能因为文档生成得多，就断言维护成本已经下降。

另外还要区分文档与其他上下文。数据库结构、提交历史、运行日志和测试结果同样记录着项目事实，文档应当把关键知识与这些证据关联起来，而不是试图替代它们。

我也不赞成重新回到文档越多越好的时代。AI 生成几十份材料很容易，判断哪些该保留、哪些可信、哪些已经过期，反而更需要工程纪律。我的倾向是只保存未来难以从代码恢复、又会影响后续决策的关键信息，让 AI 承担起草、关联和一致性检查，由人负责业务事实、架构取舍与最终验收。文档、代码和运行结果出现冲突时，也必须回到证据，而不是默认某份文件永远正确。

回过头看，我过去不喜欢写文档，很大程度上是因为它消耗了当下的开发时间，价值却常常要在很久以后才体现。AI Coding 改变了其中一个条件：整理这些知识的成本正在降低，而且留下来的内容能够继续服务于人和 AI。

所以，我现在衡量 AI Coding 的价值，除了看它这次写代码有多快，还会关心项目在完成一次迭代后，是否比以前更容易被理解和继续修改。毕竟，代码可以越来越快地产生，但多年后接手系统的人，仍然需要知道当年为什么要这样写。

AI Coding 真正的价值，不是写代码变快，而是把讨厌的文档变成了核心资产 Share on X