AI写掉75%新代码后,我才明白:文档才是真正的“源代码”

最近我一直在关注 Agent Harnesses 的项目。它想给智能体系统的开发方式做一点标准化。

这篇文章不聊项目本身，而是聊聊它引发的一些反馈。最典型的一句是：

“不就是一堆 Markdown 文件吗？真正和 AI 有关的，是能跑起来的代码。”

这句话听起来很耳熟，也很值得展开聊聊：它背后是什么心态？在什么背景下成立？又和软件开发正在发生的变化有什么关系？

软件开发正在发生一次大反转：文档就是代码。

软件开发者讨厌写文档，几乎从软件诞生就开始了。

在关于敏捷项目管理的讨论里，有一个绕不开的文件：敏捷宣言。它开启了现代软件开发的主流思路，而其中第二条原则就是：可工作的软件，高于详尽的文档。

那份宣言里写得很清楚：

个人与互动，高于流程与工具；可工作的软件，高于详尽的文档；客户合作，高于合同谈判；响应变化，高于遵循计划。

也就是说，右边的项目也有价值，但我们更看重左边的项目。

软件是不断演进、不断变化的东西。一个项目经过多次修改，可能和最初的样子完全不同。这意味着，围绕软件写的文档必须持续更新、持续维护，才能跟上代码库的变化。

这会给维护代码的人带来很大压力：时间到底该花在维护那些注定会过时的文档上，还是花在真正推动项目前进的代码上？

这两者之间怎么平衡，一直有争议。正确的做法取决于你的角色、项目、团队规模，以及团队内部的动态。

如果你是一个独立创始人，正在拼命做一个新产品，你根本没时间给每个函数、每个接口、每个 API 都写文档。你有更重要的事要做，而且文档可能是多余的——因为只有你自己会看代码。

如果是一个小型、经验丰富的开发团队，一些文档确实重要，但主要是用来协调高层方向、让团队对齐。示意图、关键 API 的规格说明——尤其是两个开发者同时从两端开发同一个接口时——再加上一些任务单，基本就够了。

但当项目变大，事情就复杂了。

开发者会加入，也会离开；市场团队可能需要了解产品某些功能是怎么运作的；你可能还需要技术支持团队来帮助客户。很快，“去找当初做它的人问问”就变得不现实，甚至完全不可能。

到了这个阶段，不管技术团队喜不喜欢，他们都得坐下来写点文档。

过去四十多年，事情基本就是这样。不同开发者对什么时候开始写文档、写多少、为什么写，可能有不同看法，但总的来说，文档是随着项目成熟，出于必要才被写出来的。

有了 AI，这个现状彻底变了。

智能体系统在开发速度上，已经超过了人类开发。

代码质量好吗？不总是。但它似乎开始变得足够好，尤其是在一个有能力的开发者引导下。

Business Insider 曾报道，Google 表示公司75% 的新代码由 AI 生成。

一个人坐下来，花几个月时间，一行一行手工完善一个原型——坦白说，这已经是过去式了。

现代软件开发更像是：懂行的人把自己的理解交给 AI 系统，然后确保这些 AI 系统实现出稳健、忠实于自己想法的方案。

本质上，软件开发者的角色，正在变得更像技术产品负责人或项目经理。

在复杂环境里做好这件事，仍然需要软件开发的硬技能。你得知道自己在做什么，才能有效管理一群 AI 智能体。但坐下来亲手写每一行代码，正在变得越来越少见。

当软件开发的基石发生这么大的变化，文档的角色跟着变化，也就不奇怪了。

现在，每一个软件项目都像是一个小到中型团队。每个开发者都在用 AI 增强自己的工作。很快，大多数知识工作者也会进入同样的状态。

随着 AI 成长和进化，大多数人都会以某种方式被 AI 增强、协助和支持。我对此既兴奋又害怕，就像大多数人一样。但不管感受如何，这已经是一个很明显的现实。

具体到软件开发，我觉得人们实际做的工作，和他们想象自己做的工作之间，存在一种割裂感。

很多开发者已经写了几十年代码，他们仍然把自己想象成“写代码的人”。他们用 AI 来加速，但最终还是自己在创造。

然而，当 AI 开始生成一个代码库的 50%、60%、90%、99% 时，这种自我认知就越来越不准确了。

越来越多时候，你说自己“写了代码”，在一个和 AI 系统合作的项目里，更像是一种语言习惯，而不是一句真实陈述。

那些职业生涯都在写代码的开发者，现在坦白说，已经不怎么写代码了。他们仍然在完成事情，但他们不知道该怎么描述自己在做什么，以及为什么自己仍然必要。

我觉得，有些开发者还没有在自我认知上完成跳跃。

现实中，他们更像管理者，而不是开发者。他们管理的，是一群速度极快、能力不差、但状态飘忽的 AI 开发者。

这些 AI 开发者能快速理解大量信息，并利用这些信息迅速写出大量代码；但它们也会忽略整块关键文档，做出明显和项目潜台词不一致的奇怪假设，而且每次你关掉再打开终端，它们对问题的理解就会完全重置。

在这种环境里，文档不是可有可无的附加项。它是现代开发者能否高效工作的根本，而且绝对关键。

当然，大语言模型仍然不稳定，所以扎实的软件开发能力依然非常重要。但随着大语言模型和智能体系统继续进化，用来让智能体理解代码库、做出修改的指令，开始变得比代码本身更重要。

越来越多时候，代码是基于文档生成的，而不是反过来。

于是，我们回到那句话：

“不就是一堆 Markdown 文件吗？真正和 AI 有关的，是能跑起来的代码。”

我在网上经常看到这种情绪：智能体系统是复杂、精密的软件，而各种提示词和上下文，只是边缘兴趣。

这话不是完全没道理。似乎每天都有人发文章，说自己“做了一个 AI 智能体，帮我在网上赚大钱”，而那个“AI 智能体”其实是 Claude，指向三个措辞糟糕的 Markdown 文件。

到了这一步，“一堆 Markdown 文件”几乎成了土味、拼凑、炒作型软件的标志。这种内容又多又廉价，自然会侵蚀“为智能体系统结构化信息”这件事的形象。更何况，它从父亲“提示工程”那里，就已经继承了一股不太好的味道。

但这句话虽然在一个维度上真实合理，也有一个很大的不真实之处。

它暗示：把信息组织成智能体容易访问、容易理解的形式，并不重要。

随着智能体系统演进，技能、指令、MCP 服务器和其他范式，会被打包进越来越大的项目里。这时候，高效组织信息就会变成一个关键且并不简单的任务。

我担心，有些开发者没有意识到：文档正在从软件的副产品，变成软件的根本性产物。

定义系统、定义它们如何工作、定义它们背后的意图，对现代 AI 增强型开发者来说，至关重要。

用一致的方式定义这些信息，让智能体系统在项目整个生命周期里持续参考，正在成为一项基本技能。

因此，写和维护好文档——也许比写好代码更重要——正在变成一项根本性的能力。

这篇文章里的这些想法，也正是 Agent Harnesses Standard 想推进的方向。

它的目标，是定义信息应该如何结构化，才能让智能体系统更稳健地使用。

它要成功，不能只靠少数人闭门造车。这类东西需要不同观点一起打磨，才能真正完善。

如果你对这个话题感兴趣，可以去 GitHub 看看怎么参与：

GitHub：https://github.com/agentharnesses/agentharnesses

Agent Harnesses 想做的，是一种标准化方式：给 AI 智能体角色、上下文和能力。