| name | doc-review-loop |
| description | 双 agent 交替评审循环 · writer agent 写技术决策书/评审文档/跨团队对齐文档，reviewer agent 扮演严苛评审员逐条质疑找问题，循环直到通过。适用于：技术决策书、出货前评审、复杂改动论证、跨团队对齐、改 vs 不改类问题。TRIGGER when the user says: '我要一份决策书' / '写评审文档' / '建立 writer 和 reviewer 双 agent' / '让评审 agent 评下' / '站在评审员角度看' / '这文档不严谨重写'。DO NOT TRIGGER for: 简单 README / 单页技术 memo / 个人笔记（开销过大不划算）。 |
| last-verified | "2026-04-27T00:00:00.000Z" |
Doc Review Loop —— 双 agent 交替评审循环
解决什么问题
写技术决策书时，单 agent 容易出现：
- 前后矛盾（同份文档不同章节互相打脸）
- 论证不到位（"0 hits 所以可以删"这种弱论证）
- 缺乏来龙去脉（只说"这张表可删"不说"原本干嘛的 / 历史 / 影响 / 证据"）
- 站不住评审员的视角（评审员问"为什么"时答不上来）
每次都让用户手工 challenge、来回返工，效率低。
双 agent 模式：让 reviewer agent 在 writer agent 出稿后立刻扮演严苛评审员逐条质疑，writer 修改，循环到 reviewer 通过。质量在内部就过一道筛，不依赖用户每次手工 review。
适用场景
✅ 该用：
- 出货前 / 评审前 决策书（"改 vs 不改 X，给充分理由"）
- 跨团队对齐文档（PM / 业务 / 上游平台 / 法务都要看）
- 复杂改动论证（涉及多服务 / 多模块 / 兼容性 / 历史包袱）
- 风险评估 / 影响分析
❌ 不该用：
- 简单 README / 安装文档（杀鸡用牛刀）
- 单页技术 memo（< 500 字）
- 个人笔记 / TODO
工作流程
用户原始需求
│
▼
┌──────────────────────────────────────┐
│ 主对话（你 / Claude 主线） │
│ 任务：把需求拆成 writer agent prompt │
│ + reviewer agent role 定义 │
└──────────────────────────────────────┘
│
▼ 派 writer agent 出初稿
┌──────────────────────────────────────┐
│ Writer Agent (初稿) │
│ - 输入：需求 + 代码/实测证据 │
│ - 输出：HTML / Markdown / 文档草稿 │
└──────────────────────────────────────┘
│
▼ 派 reviewer agent 评审
┌──────────────────────────────────────┐
│ Reviewer Agent (评审 v1) │
│ - 角色：严苛 PM / 评审员（背景白纸） │
│ - 任务：每个论断都质疑 │
│ - 输出：N 个问题（按严重度排序） │
└──────────────────────────────────────┘
│
▼ 主对话整合 reviewer 输出 → writer prompt
┌──────────────────────────────────────┐
│ Writer Agent (改稿 v2) │
│ - 逐条回应 reviewer 问题 │
│ - 修改文档 │
└──────────────────────────────────────┘
│
▼ 再 reviewer
▼ ... 循环到通过 / 达到上限（默认 3 轮）
│
▼
最终稿 + 评审历史日志
关键约束
- 主对话不写文档，只协调 writer / reviewer。
- Writer agent 不评自己的稿（自检会盲，必须独立 reviewer）。
- Reviewer agent 必须扮演无背景的评审员（system prompt 里强调"假设你是 PM，对项目背景一无所知，每个论断都质疑"）。
- 三轮上限：超过 3 轮还过不了说明需求不清晰，回到主对话和用户对齐。
- 每轮 diff 留档：把每轮 reviewer 的问题列表存进
<doc_root>.review.log 文件，方便追溯。
步骤详解
Step 1 · 主对话拆需求
主对话收到用户"我要一份关于 X 的决策书"后：
-
列出需求清单：
- 文档目标（决策？对齐？教育？）
- 受众（PM / 工程师 / 上游平台工程师 / 业务方？）
- 必须涵盖的论点（改 vs 不改、风险、成本、收益）
- 需要的代码 / 实测证据
-
派 writer agent 出初稿（看 templates/writer-prompt.md）
Step 2 · Writer agent 出稿
Writer agent 收到的 prompt 包括：
- 文档主题 + 受众
- 用户给的代码证据（已经查过的部分）
- 需要补充查的部分（writer 可以再查）
- 要包含的论点 / 决策 / 数据
- 输出格式（HTML / MD）
Writer 出第一版后，主对话不要动它（留给 reviewer 评）。
Step 3 · Reviewer agent 评审
Reviewer agent 收到的 prompt 强调：
- "你是没接触过这个项目的 PM / 评审员"
- "每个论断都问：为什么这么说？证据在哪？前后矛盾吗？"
- "找出至少 5 个问题，按严重度排序（A 阻塞 / B 必须改 / C 建议改）"
- "不要客气、不要 hedge，直接列问题"
输出格式（reviewer 必须遵循）：
## 评审 v{N}
### A 级问题（阻塞 · 不改无法发布）
1. [问题] [位置] [建议]
2. ...
### B 级问题（必改 · 论证不充分）
1. ...
### C 级问题（建议改 · 表述能更清晰）
1. ...
### 通过 / 不通过
[判断 + 理由]
Step 4 · Writer agent 改稿
主对话把 reviewer 的问题清单 + 原稿一起给 writer，prompt 是：
"Reviewer 给了 X 个问题（A:N1 / B:N2 / C:N3）。你的任务：(1) 逐条回应每个问题，说明怎么改 / 为什么不改；(2) 改文档；(3) 输出 diff（哪些章节改了什么）。"
Step 5 · 循环
主对话再派 reviewer 看新稿。Reviewer 可能：
- 通过 → 流程结束
- 还有问题 → 继续 Step 4
最多 3 轮。3 轮还过不了 → 回主对话和用户重新对齐。
文件输出约定
每个文档跑完循环后，主对话产出：
<doc_path>.html 或 <doc_path>.md — 最终稿<doc_path>.review.log — 评审历史日志（每轮 reviewer 问题 + writer 回应）- （可选）
<doc_path>.png — 全页截图（如果是 HTML 且配套 anthropic-design）
模板文件
templates/writer-prompt.md — writer agent 的 system prompt 模板templates/reviewer-prompt.md — reviewer agent 的 system prompt 模板references/anti-patterns.md — 写决策文档的反面教材清单（writer 必读）references/review-checklist.md — reviewer 必查的 N 项清单
触发关键词
主语义：
- "我要一份决策书"
- "写评审文档"
- "建立 writer 和 reviewer 双 agent"
- "让评审 agent 评下"
- "站在评审员角度看"
- "这文档不严谨重写"
- "改 vs 不改类问题需要充分论证"
强信号词：
- "评审"+"严谨"
- "决策"+"理由"
- "充分"+"论证"
- "出货前"+"评审"
反面教材（什么时候该用却没用）
抽象案例：用户要求"某重要 config 改 vs 不改的决策书"，主对话直接写了一稿。用户 review 时发现：
- 论证薄弱（"0 hits 所以可删" 不够）
- 前后矛盾（同项目不同章节给出冲突结论）
- 缺来龙去脉（某 config 原本干嘛的没说）
如果当时用 doc-review-loop，reviewer 在内部就会问出这些问题，writer 修完才给用户，免去用户手工 challenge。
不适合的反例
- "写一份 README" → 简单文档，单 agent 出稿即可
- "写个 commit message" → 太短，杀鸡用牛刀
- "翻译这段英文" → 没有论证需求
参考
templates/writer-prompt.mdtemplates/reviewer-prompt.mdreferences/review-checklist.md
