文档驱动开发

D3(Documentation Driven Development) - 从模糊需求到精准实现：文档驱动开发实践。

文档驱动开发的核心思想

文档驱动开发的核心思想是：No Code - 先用 AI 生成完整的技术文档，再基于文档生成代码。这种方法论源于我在实际项目中的探索和思考。

从 UED 设计师案例引发的思考

最近观察了我们 UED 团队的设计师们开发软件的经历，让我对 AI 辅助开发有了更深的认识。他们开发的各种应用虽然功能不同，但都面临着相似的挑战：

名称 应用类型 制作人 当前状态 跑通的关键点 线上地址 备注（难点、卡点）
博客网站 - 李兵 已上线 收费、域名、部署、SEO、存储（数据库+对象存储）、数据监控、可视化组件 https://www.bingool.yz 1. 复杂接口调试比较困难，cursor 不能支持
拍照补光+构图工具 微信小程序 吴浅 已上线 微信认证、备案、代码审核、发布 微信搜小程序：好用的相机 1. 个人开发者变现困难，只支持广告流量收入（需满累计 500P）
牛马别忘打卡 微信小程序 金程炎 已上线 - - 1. 个人开发者变现困难，只支持广告流量收入（需满累计 500P）
GulpO 记录饮水工具 微信小程序 陈亮 已上线 微信认证、备案、代码审核、发布 微信搜小程序：GulpO 1. 功能交互逻辑修改易出 bug，无法完全修复 2. 推广变现难
一木心星球 微信小程序 张成润 已上线 数据库存储、后台管理、微信认证、备案、代码审核、发布 微信搜小程序：一木心星球 1. 项目功能多了之后，问题定位及解决会比较麻烦
超级记账 微信小程序 李忠阳 已上线 微信认证、备案、代码审核、发布 微信搜小程序：超级记账 1. 个人开发者变现困难，只支持广告流量收入（需满累计 500P）
防呆计算器 微信小程序 朱顺吉 审核中 代码版本管理、组件调用、微信认证、备案、代码审核 - 1. 组件兼容、显示等问题 2. 代码过多，cursor 卡顿
学区找房 微信小程序 金燕灵 审核中 数据获取、数据更新、代码版本管理、备案 - 1. 商用小程序发布审核难 2. 房源数据获取和更新
多猫家庭管理 微信小程序 王堵彪 开发中 线上存储、版本管理、大模型接入 - 1. AI 做流畅动画较为困难
田园消消乐小游戏 微信小程序 孙浩 开发中 数据存储、H5 套壳现有小程序 - 1. 开发过程中发现 H5 框架不太适合开发小游戏 2. H5 较
中华文化博物馆大全 网页 袁媛 开发中 博物馆馆藏数据、展览数据，周边商品交易 - 1. 数据不全、或者不对外 2. 接支付需要成本

Claude Code 使用体验

在实际项目中，我尝试使用 Claude Code 来重构一个 Chrome 插件的技术架构。当时的需求很明确：将插件改为 WXT 框架，但不能改变任何功能。

方案确实成功生成了，但下午高峰时段开始执行代码变更时，Claude Code 却无法使用了。连续的 API 错误让我不得不转向其他工具：

1
2
3
4
API Error (504 Gateway Time-out)·Retrying in1 seconds...(attempt 1/10)
API Error (520status code (no body))·Retryingin 1seconds..(attempt 2/10)
API Error (504 Gateway Time-out)·Retrying in 5 seconds...(attempt 4/10)
...

Code Buddy 的使用经历

后来我转向 Code Buddy，基于 Claude Code 的分析过程记录进行改写。效果并不理想，改出了一堆报错，而且经过多轮修改也改不好。

这让我想到一个很形象的比喻：”将控制权交给了我不理解的力量”和”AI IDE 像是一个反复无常的实习生”。

为什么会出现这种现象？我总结了两个主要原因：

  1. 需求太粗糙，AI 一口吃不下
  2. 缺乏可参考的示例（代码）

Code Buddy-V2 的改进尝试

第二次尝试时，我改进了 prompt 的描述方式：

“我想把 ai-vis-analyzer 这个 Chrome 插件的技术架构改为 WXT 框架，修改后的代码结构可以参考 info-visualization-poc 这个项目进行组织。info-visualization-poc 是一个经过验证的项目，其文件组织结构、基础配置、构建方式都经过了测试。请帮我分析下该如何修改，注意千万不能改变该插件的功能。先别写代码，先帮我分析方案，待我确认后，再执行具体的修改操作，且修改后的项目放在 ai-vis-analyzer-wxt 目录下。你可以询问我一些问题来明确需求。”

这次耗费的时间很长，但看起来似乎靠谱多了。不过修正 React 的热更新问题时，Code Buddy 还是搞不定，最后还是靠 Claude Code 解决了。

逻辑一致性的挑战

在后续的开发过程中，我发现了一个更深层次的问题：逻辑不一致。

“现在 ai-vis-analyzer-wxt 的程序能跑起来了，但是插件的实现逻辑和我提供的原始项目不一致。比如目前点击左侧原始网页中的增强分析按钮以后，后续执行的流程就和我提供的 ai-vis-analyzer 项目中的逻辑是不一致的。请仔细检查一下。整个插件的这些逻辑请严格按照 ai-vis-analyzer 这个项目的逻辑去复刻，不要改变任何的逻辑和功能。”

更好的解决办法是：先让 LLM 分析当前项目的流程，然后再让其改正新项目的逻辑。

原始项目的完整流程是：

  1. 文本选择 → 显示 ToolBar 工具栏
  2. 点击”增强分析” → 发送消息到 background script
  3. Background script → 打开侧边栏，延迟 1 秒后发送 UPDATE_SIDE_PANEL 消息
  4. 侧边栏 → 接收消息，开始分析流程（思考 → 工具 → 执行 → 完成）

深度思考：AI 辅助开发的本质

通过这些经历，我开始深入思考几个关键问题：

  1. 为什么 Claude Code 这么强（重构 FinancialChart 组件时，一把就搞定了）？
  2. 人是怎么做项目的？

从这些问题可以看出，Code Buddy 的转写不能一步到位，每次只会转写一部分内容，需要我们进行任务拆分后，逐个让其转写：

  • 基本的程序框架结构修改
  • 逻辑的迁移（包括数据接口的迁移）
  • UI 页面的迁移（创建 UI 组件、迁移组件的渲染调用逻辑）

Claude Code 之所以强大，就在于它能把复杂任务拆分得很细（不只是你看到的界面上的那几个子任务），这样相当于需求和方案都非常细致全面，不至于遗漏细节。这和人做开发任务的时候本质上是一样的。

文档驱动开发的实践框架

基于这些经验，我总结出了文档驱动开发的实践框架：

阶段 1：需求分析与概念设计（做什么）

在这个阶段，我们需要明确项目的核心需求。以我开发前端 UI 组件库为例：

“我想开发一个前端 UI 组件库，这个库会用在两个不同的场景。其中一个是 Chrome 插件，我需要通过 Chrome 插件给用户的网页注入一些内容，比如一个 Hover 小卡片，或者某一段文本的总结卡片。另一个应用场景是由业务方开发人员直接引用我们的组件库，在他们的网页内部实例化组件。”

关键是要采用渐进式深入的模式，使用 EARS 结构化描述需求：

EARS（Easy Approach to Requirements Syntax）结构化需求描述方法能够帮助我们生成详细的需求文档。我们只需提供一个粗糙的需求描述，让 AI 采用 EARS 规范帮我们生成详细的需求文档。

阶段 2：技术调研与选型

在这个阶段，我们需要考虑项目信息、历史痛点和个人关注点。比如：

  • POC 项目技术架构越简单越好，别尝试新技术
  • 别猜测一些耗时太长的内容，比如故事线，耗费了大量时间在这个组件上，性价比不高
  • 后端接口做好 mock 数据，特别是模型的输出接口，巨慢无比，开发阶段不 mock，调试前端效率极低

多角度对比模式要求 AI 从多个维度进行分析和比较：

  • 性能表现
  • 开发体验
  • 生态系统
  • 浏览器兼容性
  • 学习成本
  • 适用场景

阶段 3：架构设计（怎么做）

当我经验不足，不知道该怎么设计程序架构时，我会让 AI 分析多个优秀的同类组件库，融合它们的特性，帮我进行程序设计。

以可视化组件库为例，我会参考 ECharts、AntV-G2、VChart、AntDesign 等优秀项目，要求设计具备以下特性：

核心架构原则：

  1. 分层解耦原则 - 所有成功的可视化组件库都采用了分层架构
  2. 可组合性原则 - 作为基本单元，支持资源组合
  3. 数据驱动原则
  4. 主题系统化原则
  5. 跨平台抽象原则
  6. 性能优先原则

必备设计特性（按重要性排序）：

  1. API 设计层面：声明式配置 API
  2. 架构设计层面：分层解耦架构
  3. 渲染优化：高效的渲染性能
  4. 样式管理层面：Design Token 体系，基于 TypeScript 的主题系统

阶段 4：数据结构设计

制定组件库协议是关键步骤。比如 HIVIS 组件库协议的制定，这为后续的开发提供了明确的标准。

阶段 5：测试（做得对不对）

测试是确保质量的重要环节。在实际项目中，我们需要建立完整的测试体系，包括单元测试、集成测试等。

阶段 6：实施规划

最后是制定详细的实施计划，包括开发阶段划分、每个阶段的具体任务、技术关键点和验收标准、风险点识别和应对方案、开发时间预估等。

项目反思与经验总结

通过近期两个项目的实践，我有了更深的反思：

我们的这些探索类项目，都是 Prompt 驱动型需求，需求的确认一定是在逐步验证 Prompt 中定下来的。该写哪些 Prompt、每个 Prompt 该怎么写，这两个如果没定下来，需求和方案就大概率是模糊的、错误的。

Prompt、组件，必须都基于数据结构去定。比如这次在我们的数据结构协议没定下来之前，后端是没法写 Prompt 的（因为不确定输入和输出）。

应该写哪些 Prompt，需要在前面就和流程绑定好、确认下来，并且明确每个 Prompt 的输入和输出。工具的分类是根据取数逻辑和数据结构来区分的。

开发者角色的转变

在 AI 时代，开发者的角色正在发生转变：

Vibe Coding → AI 工程化开发
码农 → AI 产品经理&架构师

开发人员的职责转变为：设计任务和系统结构优化，必须具备更高层次的抽象能力、判断力、战略思维、技术审美。

AI 则负责：辅助设计、所有的编码工作。

具体来说，开发流程可以分为三个主要环节：

  1. 需求分析：做什么
  2. 程序设计：怎么做
  3. 测试：做得对不对

语音输入的优势

在实际使用中，我发现语音输入能显著增加上下文带宽，帮助用户提供更全面、细致的指令，无论经验水平如何，都能获得更优结果。

虽然因为输入方式的问题，一些 Prompt 内容在逻辑和语义上比较混乱，但这并不影响其有效性。关键是要建立有效的沟通机制，让 AI 能够准确理解我们的需求。

未来展望

文档驱动开发不仅是一种方法论，更是一种思维方式的转变。它要求我们在编写代码之前，先通过文档来理清思路、明确需求、设计方案。这种方式虽然前期投入较大，但能够显著提高开发效率，减少返工，提升项目质量。

随着 AI 技术的不断发展，我相信文档驱动开发会成为越来越重要的开发模式。它不仅能够帮助我们更好地利用 AI 的能力，还能够促进团队协作，提高项目的可维护性。

在这个 AI 与人类协作的新时代，我们需要不断学习和适应新的工作方式，找到人机协作的最佳平衡点。文档驱动开发，或许就是这个平衡点的一个重要探索。