文档即代码

AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

我一直在进行一个项目，该项目试图标准化开发代理系统的一个方面。这篇文章不是关于那个项目的，而是我在向世界展示该项目时收到的一些反馈。具体来说，是具有以下特点的反馈：

这只是 markdown 文件。真正的AI 相关东西是实际的运行代码

我想花点时间来解读这种情绪所暗示的含义、它存在的背景，以及它与软件开发作为一门学科的发展方向之间的关系。

1、文档与代码之间的斗争

自软件诞生以来，软件开发者就一直讨厌创建文档。在我关于敏捷项目管理的文章中，我讨论了许多内容，其中包括"敏捷宣言"。这份文档开启了主导现代软件开发的敏捷软件开发理念。它的第二个原则是优先考虑功能软件而非文档。

软件是一个不断演变和动态的事物。经过多次修订，项目可能会发生巨大变化，这意味着围绕该软件的文档必须不断更新和维护，以跟上代码库的变化。这给维护代码库的人带来了压力；他们是优先维护那些最终会变得过时的文档，还是专注于实际推动项目前进的代码？

这两者之间的平衡是一个有争议的话题，正确的方法取决于你的角色、你正在从事的项目、你所在团队的规模以及该团队的动态。

如果你是一个独自开发新产品的创始人，你没有时间记录每个函数、每个接口和每个 API。你有更大的事情要做，而且文档是多余的，因为作为唯一的创始人，无论如何只有你一个人会查看代码。

对于一个由经验丰富的开发者组成的小团队来说，一些文档很重要，但主要是为了协调高层举措和使团队朝着正确的方向前进。图表、关键 API 的规范（当两个开发者同时在两端工作时），以及使团队朝着同一目标前进的工单，几乎就是你所需要的全部。

随着项目的增长，事情变得更加复杂。开发者可能会加入或离开公司，营销团队可能需要关于产品功能特定方面的信息，你可能需要引入技术支持团队来协助客户。很快，"问那个构建它的人"就变得不可行，如果不是不可能的话。此时，无论技术团队是否喜欢，他们都必须坐下来编写一些文档。

四十多年来，情况大体如此。不同的开发者可能对何时开始编写文档、编写多少以及为什么编写有不同的看法，但通常文档是随着项目的成熟而出于必要性编写的。随着 AI 的出现，这种现状完全改变了。

2、软件开发格局的变化

代理系统已经超越了人类开发。代码质量好吗？并不总是，但看起来它开始变得足够好，尤其是在有能力的开发者指导下。

坦率地说，一个人坐下来花几个月时间手工完善原型的范式已经成为过去。现代软件开发范式是那些知道自己在做什么的人将他们的理解委托给 AI 系统，并确保这些 AI 系统实施与其愿景一致的稳健解决方案。

从本质上讲，软件开发者的角色正变得更像是技术产品负责人/项目经理的角色。在复杂环境中做好工作仍然需要软件开发的硬技能；你需要知道自己在做什么才能有效地管理一个 AI 代理团队，但坐下来编写单行代码正变得越来越罕见。

随着软件开发的基础发生如此显著的变化，文档的角色也随之改变也就不足为奇了。

3、AI 与文档的角色

现在每个软件项目都是一个中小型团队。每个开发者都在使用 AI 来增强他们的工作。很快，大多数知识工作者将处于同样的情况。随着 AI 的发展和进化，大多数人类将在某种程度上得到 AI 系统的增强、辅助和支持。像大多数人一样，我对这个前景既兴奋又害怕。然而，无论人们的感受如何，这都是明显的现实。

当我们具体看待软件开发时，我觉得人们实际所做的工作与他们想象自己所做的工作之间存在认知失调。许多开发者已经写了几十年的代码，他们仍然想象自己在编写代码。他们使用 AI 来帮助自己更快地完成工作，但他们最终是创造者。然而，随着 AI 开始生成代码库的 50%、60%、90%、99%，这种概念化变得越来越不准确。越来越多地说你在与 AI 系统合作的项目中"编写了代码"，感觉更像是语言上的怪癖而非真实的陈述。

那些职业生涯都在编写代码的开发者现在，坦率地说，并不编写代码。他们仍然在完成一些事情，但他们不知道如何描述他们正在做什么以及为什么他们是必要的。我觉得一些开发者在如何概念化自己方面还没有实现飞跃。实际上他们是管理者，而不是开发者。一个管理着非常快速、相当有能力但奇怪地不一致的 AI 开发者的管理者。他们能够快速理解大量信息，并利用这些信息快速编写大量代码，但也会忽略整个关键的文档部分，做出与他们正在处理的项目的潜台词明显不一致的奇怪假设，并且每次关闭和打开终端时都会完全重置对问题的理解。

在这种环境下，文档不是什么多余的项目；它对于成为现代时代有效的开发者至关重要。自然，随着 LLM 保持不一致，强大的软件开发技能仍然根本重要。然而，随着 LLM 和代理系统的不断发展，用于让代理系统理解代码库和进行更改的指令开始变得比代码本身更重要的基础工件。越来越多的是，代码是基于文档创建的，而不是相反。

因此，我们回到启发这篇文章的情绪

这只是 markdown 文件。真正的AI 相关东西是实际的运行代码

我在互联网上经常看到这种情绪：代理系统是复杂而精密的软件，而指导它们的各种提示和上下文只具有边缘价值。这其中有一些智慧；似乎每天都有人发布文章，讲述他们如何"制作了一个 AI 代理来帮助他们在网上赚十亿美元"，而那个"AI 代理"就是 Claude，指向三个措辞糟糕的 markdown 文件。此时，"一堆 markdown 文件"标志着粗糙、黑客式和炒作的软件，这种内容形式的频繁和廉价对为代理系统构建信息的理念产生了自然的侵蚀作用，而这个理念已经从其父辈"提示工程"那里继承了不好的名声。

虽然在某个维度上是真实且合理的，但这个陈述中也存在显著的不真实性。即信息的结构化使得代理可以轻松访问和理解并不重要。随着代理系统的发展，技能、指令、MCP 服务器和其他范式被捆绑到越来越大的项目中，信息的有效组织成为一项关键且并非微不足道的任务。

我担心一些开发者不理解，文档正在从软件的副产品转变为成为其基本工件。定义系统、它们如何工作以及背后的意图对于现代 AI 增强型开发者至关重要。以代理系统可以在项目生命周期中持续引用的一致方式定义该信息正在成为一项基本技能。因此，编写和维护良好文档的能力（也许比编写良好的代码更重要）正在成为一项根本重要的技能。

原文链接: The Documentation is the Code

汇智网翻译整理，转载请标明出处