105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
## 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]]
|