AI编程之文档驱动开发，用多个文档即可开发出完整产品

2025年11月7日

大家好，和很多人一样，我和团队现在全力投入 AI 辅助开发。但问题来了：随着新功能不断上线、bug 持续修复、在 Cursor 上频繁提交代码……代码库开始变得像丛林一样混乱。功能都能跑通，测试也全部通过，可当初做决策的背景却逐渐丢失了。AI Agent（有时甚至是人类开发者）会重复实现已有功能，或者写出不符合现有模式的代码。

这个问题在大量使用 AI 开发的团队里越来越常见，所以我想分享一下我们摸索出的解决方案。

过去几个月，我们总结出了自己的文档驱动开发（SDD）流程，相比其他方法有些独特优势。核心在于：采用结构化的执行工作流，同时记录 Agent 的工作结果。下面详细说明这套方法如何运作、带来了哪些实际改变，以及其他团队如何借鉴。

什么是文档驱动开发

简单说就是：先设计好文档，再把它们作为实现的输入。然后把实现过程中发生的事情（研究、Agent 讨论、代码审查等）记录成_输出文档_，供未来参考。整个循环是：

输入文档：产品简报、技术简报、用户故事、任务需求
工作流：研究 → 规划 → 编码 → 审查 → 修订
输出文档：研究日志、编码计划、代码笔记、审查结果、发现总结

把文档（输入和输出）当作核心资产，可以强制团队深入理解需求，保持决策可追溯。目标不是堆砌文档，而是创建恰到好处的结构——让决策可追溯，让 Agent 下次迭代同一功能时有足够上下文。

这套方法为什么有效

更好的复用，更少的重复。维护研究日志、发现总结和历史文档后，更容易识别已经"解决过"的代码或模式，直接复用就行，不用重新发明轮子

减少上下文丢失。文档提交到 git 后，下次有人处理这个功能，他们（以及 Agent）能看到之前做了什么、失败过什么、做了哪些决策。追踪"为什么这样改"、"为什么因为风险 Y 跳过了功能 X"变得简单多了

新人上手更快。新工程师能直接看到清晰的文档说明（要构建什么 + 怎么构建）和之前的工作记录，磨合时间大大缩短

具体怎么做（分步指南）

首先说明一下，这套方法真正适用的是比较大的功能开发。bug 修复、小调整或清理任务，简单说明一下让 Agent 直接干活就够了。

对于大型项目或功能，流程是这样的：

定义 prd.md：功能目标、用户旅程、基本需求
定义 tech_brief.md：高层架构、约束条件、技术栈、术语定义
为每个功能/用户故事写 requirements.md：故事内容、验收标准、依赖关系
为故事下的每个任务写 instructions.md：详细任务指令（要做什么研究、涉及哪些代码区域、测试指南）。粒度大概是一个典型 PR 的大小。别写代码级细节，那些留给 Agent 实现时处理更好
开始实施时，创建一套自定义命令，为每个任务做这些事：
- 创建任务的 research.md：记录对代码库、现有模式、注意事项的学习
- 创建 plan.md：记录如何实现
- 写完代码后创建 code.md：记录实际做了什么、改了什么、跳过了什么
- 创建 review.md：记录反馈和改进建议
- 最后创建 findings.md：记录反思总结、需要关注的点、后续行动
把这些文档和代码一起提交，未来的人（Agent 或人类）就有完整上下文了
使用统一的文件夹命名：比如 project/story/task/requirements.md、…/instructions.md 等，保持直观
为每种文档类型创建模板，轻量且标准化
选 2-3 个功能做试点，改进文档模板、文件夹约定、命名方式后再全面推广

几点经验教训

文档模板必须简单。太复杂的话，大家就会跳过
能自动化的尽量自动化：创建任务时自动生成空白文档文件。可以的话集成到你的系统里
定期回顾文档：每两周问一次"哪些输出发现我们忽略了？"能及时发现技术债务
对于 Agent 驱动的工作流：确保 Agent 能访问文档文件夹，并且知道怎么用。没有这些结构化输入，效果会大打折扣

最后说两句

如果你一直在快速交付能用的功能，但感觉正失去对代码库的控制，希望这套文档驱动开发流程能帮到你。

额外福利：如果你想要个工具来自动化这类工作流，不用自己手动操作（包括输入文档创建、任务管理、输出文档），我正在开发一个叫 Devplan 的工具，也许你会感兴趣。

如果你尝试过类似方法，很想听听哪些有效、哪些没用。