AI编程之文档驱动开发

探究技术的本质，享受技术的乐趣！今天我们的议题是：AI编程之文档驱动开发。

为什么我们要使用文档驱动开发

在如今这个AI的时代，LLM的写代码的能力已经超过绝大多数人了，这个比重我认为占到了90%。既然LLM的代码能力这么强了，那为什么它写出来的代码总是与我们的预期不符呢？甚至我们不得不给AI写的代码擦屁股呢？设甚至被调侃为“AI善后工程师”。我认为最本质的原因是知识没有对齐。我们把LLM当做一个刚入职的实习生来看，他写代码的能力很强，但是对于公司内部的开发规范，技术栈偏好，业务知识一无所知，这个时候你给他一个需要理解业务之后才能开始的任务，他能做好才怪。那怎么办呢？唯一的办法就是：补齐上下文，进行知识对齐。而这也是文档驱动开发的核心所在。

文档驱动开发，让我们的注意力从编写代码转移到了编写文档上。编写文档的过程就是在和LLM补充上下文，对齐知识。有一个不错的比喻：LLM是编译器，我们写的文档源文件，而对应的代码不过是编译后的可执行的产物。所以文档驱动开发的核心流程在于先写文档，再写代码。这个流程不能流于表面，写文档的目的是提供上下文，提供业务知识。当LLM有足够的上下文之后，写的代码才能符合预期。

总之一句话，文档驱动开发解决的是LLM因为上下文的缺失导致无法按照预期完成任务的问题，解决手段是通过编写文档来对齐上下文，对齐知识。

我的所思所想

这里我想基于我这一周使用文档驱动开发，分享一些经验。首先我获得了两个认知：

1. 把LLM当做一位实习生，一位能力很强的实习生。
2. 文档即代码，你在撰写文档的过程，其实已经是在开发了。不要因为还没有写一行代码而担心任务延期。

我通过一个例子来介绍一下我的文档驱动开发工作流吧。我手头上有这样一个任务：组织机构等数据的同步。

背景是这样的：我们的业务系统重度依赖我们的一个组织机构管理服务，但是客户要求使用他们自己的组织机构服务来管理组织机构和用户数据。为了解决这个问题，我们决定通过数据同步的手段来解决这个问题，而不是改业务系统。

而当时的我，对我们公司内部的组织机构服务并不熟悉，更对客户自己的组织机构服务不熟悉了。这里面比较核心的问题在于数据模型的映射。比如我们的组织机构数据与客户自己的组织机构的数据如何建立对应关系。

当我接到这个任务的时候，一开始我认为是很简单的，就是数据的读和写没什么复杂的。于是我就打算尝试使用文档驱动开发来解决这个问题。

我编写的第一个文档就是业务设计文档，我需要和AI来对齐我们要干什么？以及为什么要这么干？但是这里我踩了一个坑，那就是业务设计文档的草稿不是我自己写的，而是我让AI分析其他的团队开发的数据同步服务生成的一份业务设计文档草稿。然后我们基于这个草稿不断的修改演进为最终的业务设计文档。正是因为草稿不是我自己写的，就导致了后续代码实现过程中出现了很大的偏差。换句话说就是你还没想好就动手写文档了。

我编写的第二个文档就是详细技术文档，就是结合了具体的技术栈，生成一份模块级别的实现文档，比如整个项目分为几个模块，这些模块之间的依赖关系是怎么样的？这些模块之间如何通过组合来完成任务的。详细技术文档主要解决的是如何做的问题。但是，这里我还是犯了和上面一样的错，详细技术文档的草稿不是我写的，也是让AI生成的，就导致后期代码的实现上出现了比较大的偏差，尤其是包结构的组织。这个错仍然是我自己根本就没有想好如果实现这个业务，就让AI来操作了。

我编写的第三个文档就是实现计划文档，主要是根据上面两个文档，生成一份分阶段的实现计划，每个阶段中都有详细的任务清单。

接下来就是具体的编码过程，我基于这份实现计划文档，先让AI思考这个阶段一次性完成的风险大不大，如果大，就会让其先拆分为几个子阶段，然后完成各个子阶段。而在具体写代码之前，我会开启编码工具的Plan模式，先让AI想清楚再写代码。

回过头来看，我感觉我犯了一个很严重的错误，那就是上下文的补充和对齐这件事情一定要人来做，而不是让AI自己探索。至少草稿得是自己写的，才能保证AI没有脱离你的掌控。所以我总结出来一条原则：AI只适合干非常具体的事情，宏观的事情他只能辅助，拍板，做决策的是你自己。

挖坑总结：

1. 文档的草稿得自己写，也就是自己心中要有一个大致的蓝图。而不是让AI来绘制这个蓝图。
2. 通过Review代码，发现AI编写的问题，比如性能问题，不符合开发规范的问题，在自己的AGENTS.md中补充，通过不断的补充，自己就拥有一份比较好的AI宪法了，AI写代码就更加符合规范了。
3. 能用流程图，时序图描述的地方，尽量使用图来描述，而不是纯文本。LLM对结构化的东西比较敏感。