4.0 KiB
4.0 KiB
Why
- AI 产出代码的速度远远大于人类 review 的速度，所以人应该把注意力聚焦在高杠杆的位置，而不是把主要精力消耗在逐行看代码上。
- 文档就是这种高杠杆工具。它能用较小的注意力成本，约束 Agent 对需求、边界、架构和实现路径的理解。
- 参考：人类注意力应分配到高杠杆的点
核心观点
- 先写文档，不是为了增加流程，而是为了降低实现偏差。
- 文档优先编程的本质，是先把“要做什么、为什么这样做、做到什么程度算对”说清楚，再让 Agent 批量实现。
- 如果文档质量足够高，后续代码实现、review、回溯修正都会轻很多。
How
下面以 OMX 工作流为例。
1. 从策划文档发起
- 输入：策划文档 / 需求文档 / PRD
- 目标：给后续所有文档一个统一的问题定义和业务背景
2. 通过 $deep-interview 产出访谈文档
- 输入：策划文档
- 产物：访谈文档
- 作用：
- 明确目标、边界、本期做什么、不做什么
- 补充约束条件和项目上下文
- 沉淀一些和具体项目绑定的技术前提
- 说明：
- 这份文档更像“给 Agent 用的澄清稿”，用来减少需求理解偏差
3. 通过 $alignment-c4-dynamic 产出 C4 Dynamic 文档
- 输入：访谈文档
- 产物：C4 Dynamic
- 作用：
- 描述关键运行时交互
- 收敛模块边界、接口约定、架构约束
- 形成较粗粒度的技术方案和协作视图
4. 通过 $plan 产出细化计划文档
- 输入：访谈文档 + C4 Dynamic
- 产物：Plan 文档
- 作用：
- 把粗粒度方案继续细化
- 明确任务拆解、模块边界、接口约定、实施顺序
- 让后续实现不再依赖临场发挥
5. 通过 $ralplan 产出可执行实现计划
- 输入：访谈文档 + C4 Dynamic + Plan 文档
- 产物：Ralplan 文档
- 作用：
- 把前面的信息进一步压实为“面向执行”的实现计划
- 让实现阶段的上下文、顺序和约束更集中
- 当前理解：
- 它位于 Plan 和实际编码之间，作用类似“可直接驱动实现的执行蓝图”
6. 通过 $alignment-flow ralplan文档 产出时序图
- 输入：Ralplan 文档
- 产物：时序图 / Flow 文档
- 作用：
- 把关键流程细化到方法、接口、调用顺序和异常分支
- 用自然语言 + 流程表达把实现细节前置说明清楚
7. 通过 $ralph ralplan文档 产出代码
- 输入：Ralplan 文档
- 产物：代码
- 作用：
- 按前面已经定义好的文档约束进行实现
8. Review 代码，并把偏差回写到文档
- 如果没问题：
- 把前面产出的文档整理后沉淀到项目记忆中
- 如果有问题：
- 先判断问题出在实现，还是出在前置文档本身
- 很多偏差并不是 Agent “写错了”，而是上游文档没有把关键约束表达清楚
偏差修正回路
- 如果差异主要出在 C4 Dynamic：
- 重新跑
$deep-interview - 修正访谈文档
- 再回到 C4 Dynamic 阶段继续收敛
- 重新跑
- 如果差异主要出在 Plan / Ralplan：
- 重新跑
$plan或$ralplan - 把差异点回写到访谈文档
- 再继续推进后续阶段
- 重新跑
- 如果差异主要出在时序图 / Flow：
- 重新跑
$ralplan - 同时把差异回写到 Plan、Ralplan、访谈文档
- 再进入实现阶段
- 重新跑
实践原则
- 文档不是“交付物附属品”，而是实现质量的上游控制面。
- review 不应该只盯代码，也要反查是哪一层文档没有把问题讲清楚。
- 一旦发现偏差，优先修正文档源头，而不是只在代码层打补丁。
参考
-
- 需求 / PRD
- 技术方案设计
- 任务拆解
!
-
- 可对照理解为三类核心文档：
- 第一类：需求 / PRD
- 第二类：技术方案
- 第三类：任务拆分
!
