## 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 不应该只盯代码，也要反查是哪一层文档没有把问题讲清楚。
- 一旦发现偏差，优先修正文档源头，而不是只在代码层打补丁。

## 参考
- [[AI-First产研团队的交付路径]]
  - 需求 / PRD
  - 技术方案设计
  - 任务拆解
![[AI-First描述工作流.png]]

- [[天猫新品团队AI编码实战指南（下）]]
  - 可对照理解为三类核心文档：
  - 第一类：需求 / PRD
  - 第二类：技术方案
  - 第三类：任务拆分
![[美团AI工作流.png]]