Agent 方法论框架 superpowers 的三段独立评审怎么设计
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
superpowers 把评审当成一个信息隔离问题在解，而不是当成一个提示词写得好不好的问题。 三份评审提示词摆在一起看，最值钱的不是里面那几张检查表——那些东西谁都能列——而是每一份能拿到的输入被削到了什么程度，以及派发方被禁止做哪些事。它是 MIT 许可的开源项目，这几个文件你现在就能打开逐行核对。
站内 /learn/ai-pingshen-guize-ji/ 讲的是评审规则本身怎么定，/learn/agent-duishou-yanzheng/ 讲的是让另一个角色去验证结果的通用思路。这篇不重复那两层方法论，只做一件具体的事：拆一个真实仓库把这些想法写成文件之后长什么样，以及哪几处其实没落到实处。
一、三份提示词各自拿到什么
先看输入面积，这是最能说明设计意图的一项。
规格评审那份在 skills/brainstorming/spec-document-reviewer-prompt.md，整个模板里只有一个占位符：[SPEC_FILE_PATH]。也就是说，接手的一方拿到的全部东西就是一个文件路径。检查表五行——Completeness、Consistency、Clarity、Scope、YAGNI，每行配一句「看什么」。Clarity 那行写得很具体：Requirements ambiguous enough to cause someone to build the wrong thing，含糊到能被理解成两种东西才算问题，措辞不漂亮不算。
计划评审那份在 skills/writing-plans/plan-document-reviewer-prompt.md，占位符变成两个：[PLAN_FILE_PATH] 和 [SPEC_FILE_PATH]。多出来的那个不是给背景用的，是给对账用的——四项检查里有一项就叫 Spec Alignment。另外三项是 Completeness、Task Decomposition 和 Buildability，最后一项的原文是一句大白话：Could an engineer follow this plan without getting stuck?
任务评审那份在 skills/subagent-driven-development/task-reviewer-prompt.md，占位符一下涨到七个：模型、任务简报文件、全局约束、实现方的报告文件、BASE 与 HEAD 两个 SHA、以及一个 diff 文件。篇幅也从前两份的四十多行涨到一百八十多行。
这个梯度是有道理的。规格阶段除了文档本身没有别的客观证据可查，输入给多了只会污染判断；到了任务阶段，有 diff、有测试输出、有实现方自己写的报告，可核对的东西多了，提示词才需要长出「哪些能信、哪些不能信」的规矩。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 规格评审提示词 | 只凭一个规格路径查完整性、一致性、清晰度、范围与 YAGNI | skills/brainstorming/spec-document-reviewer-prompt.md | 设计文档写完、准备转成实施计划之前 |
| 计划评审提示词 | 同时拿计划和规格两个路径，重点查计划有没有覆盖规格、任务拆得能不能干 | skills/writing-plans/plan-document-reviewer-prompt.md | 计划写完、准备逐任务派活之前 |
| 任务评审提示词 | 读一次 diff，给出规格符合性和代码质量两个判断 | skills/subagent-driven-development/task-reviewer-prompt.md | 每个任务实现完、进入下一个任务之前 |
| 返工复评提示词 | 只裁决上一轮每条 finding 是否 ADDRESSED，外加看修复 diff 本身有没有新破坏 | skills/subagent-driven-development/re-review-prompt.md | 评审出了问题、返工一轮之后 |
| review-package 脚本 | 把 commit 列表、stat 汇总和带上下文的 diff 写进一个文件 | skills/subagent-driven-development/scripts/review-package | 派出任何一次代码评审之前 |
| task-brief 脚本 | 从计划里抽出单个任务的原文到独立文件 | skills/subagent-driven-development/scripts/task-brief | 派出实现方之前 |
| 进度台账 | 记完成行、返工轮次、以及被搁置的裁决 | 由 skills/subagent-driven-development/scripts/sdd-workspace 打印的目录下的 progress.md | 会话被压缩之后要恢复到正确位置时 |
二、不让评审方沾到作者上下文，是逐条堵死的
skills/subagent-driven-development/SKILL.md 开头给了原则句：They should never inherit your session's context or history — you construct exactly what they need.。这句话在整套文件里被拆成了好几条互相咬合的具体约束。
第一条，交接一律走文件，不走粘贴。 SKILL.md 里有一句很硬的观察：你粘进派发提示词里的任何东西、以及接手方打印回来的任何东西，会在整个会话剩下的时间里一直占着你的上下文，并在之后每一轮被重新读一遍。于是它给了两个 bash 脚本。task-brief 用一段 awk 从计划文件里按 Task N 标题抠出单个任务的全文，写到独立文件；review-package 则把三样东西拼进一个文件：
{
echo "# Review package: ${base}..${head}"
echo
echo "## Commits"
git log --oneline "${base}..${head}"
echo
echo "## Files changed"
git diff --stat "${base}..${head}"
echo
echo "## Diff"
git diff -U10 "${base}..${head}"
} > "$out"
派发方只把这个文件的路径交出去，diff 内容一次都不进它自己的上下文。SKILL.md 对这点的说法是「the package never enters the controller’s context」。
第二条，派发提示词里不许带会话史。 原文要求一次派发只描述一个任务，不描述这个会话经历过什么，并且点名禁止把「Tasks 1-3 之后的状态」这类累积摘要粘进后面的派发。它举了一个真实反例：某次派发提示词达到 42k 字符，其中 99% 是粘过去的历史。真正该给的只有三样——这一个任务、它要碰到的接口、以及全局约束。
第三条，不许替接手方预判结论。 这条写得最不留情面：不要指示对方忽略某个问题或不要标记某个问题；如果你正在写的提示词里出现了 do not flag、don't treat X as a defect、at most Minor 或者 the plan chose，就停手——你在预判，而动机通常是想给自己省掉一轮返工。正确做法是让它提出来，你在返工循环里裁决，并把裁决写进台账。
第四条，报告只是待核实的说法。 任务评审提示词里专门有一节标题就叫 Do Not Trust the Report，明确说实现方的报告可能不完整、不准确或过于乐观。更狠的一句是：报告里的设计理由同样是说法——「按 YAGNI 留着的」「故意保持简单」这类话，是实现方在给自己的活打分；已陈述的理由永远不降低一条问题的严重级别。同一段校准往下再走一句，这套逻辑就推到了计划身上：一条被计划文本明确要求、但按评审标准算缺陷的东西（不断言任何事的测试、逐字重复的逻辑块），仍然要按 Important 报出来并标注 plan-mandated，The plan's authorship does not grade its own work; the human decides.
第五条，看不到就说看不到，不许自己去爬。 任务评审的输入被限定成那份 diff 文件，提示词写明 diff 的上下文行就是被改文件的内容，除非某个必须判断的代码块在中途被截断，否则不要单独去读改动过的文件，也不要去爬更大的代码库；只有为了评估一个你能叫得出名字的具体风险，才允许做一次聚焦检查，并且要在报告里同时写出风险和你查了什么。查不了的怎么办？输出格式里留了一档 ⚠️ Cannot verify from diff，把这类要求交回给派发方。SKILL.md 接住了这一档：这些项不阻塞其余评审，但必须由你自己逐条解决，因为跨任务的上下文在你手上；确认是真缺口，就当成规格未通过，进返工循环。
这一整套读下来，隔离的落点其实是双向的：既不让评审方看见作者知道什么，也不让作者的上下文被评审材料撑爆。关于后半段的通用做法，可以对照 /learn/agent-shangxiawen-guanli/。
三、越靠近代码，怀疑越重
三份提示词的宽严不是一个标准。
规格和计划这两份的校准段几乎同调：只标出会在后续环节造成真实麻烦的问题；措辞改进和风格偏好都不算问题，规格那份还额外把「有些章节写得没别的详细」也排除在外；除非存在会导致计划本身出错的严重缺口，否则通过。输出里那栏 Recommendations 后面还跟着括号——advisory, do not block approval，建议不构成拦截。这是一种有意压低的门槛：文档阶段挑刺的边际收益很低，卡住反而更贵。
任务评审那份的校准段完全换了气质。它分三档，并且把 Important 的判据写死成可对照的样子：不正确或脆弱的行为、漏掉的要求、你会因此拦下合并的可维护性损伤——逐字重复的逻辑块、被吞掉的错误、什么都不断言的测试。而「覆盖率还可以更广」和各种打磨建议只能算 Minor。它还要求先说做得好的地方，理由写得很实在：准确的肯定能让实现方相信后面那些反馈。
测试纪律同样是隔离思路的延伸：实现方已经跑过测试并附了证据，评审方不要为了确认报告再跑一遍套件；只有读代码时产生了现有运行结果回答不了的具体疑问，才跑一个聚焦测试，不跑整包、不跑竞态检测、不做高次重复。觉得需要重度验证，就在报告里建议，而不是自己动手。另外有一句容易被忽略的判据：实现方报告的测试输出里如果有 warning 或其他噪音，那本身就是一条问题——测试输出应当是干净的。
返工阶段的复评则被刻意做窄。它的职责是给每条 finding 出 ADDRESSED 或 NOT ADDRESSED，并且原文强调「Attempted」不算已解决，那个具体缺陷必须不再存在；同时只看修复 diff 有没有引入新破坏。修复范围之外注意到的问题记到 Out-of-Scope Observations，不阻塞、也不延长循环。循环本身有上限：每个任务最多五轮，第 1 到 3 轮唤回原来那个实现方，第 4 到 5 轮换一个更强模型的新实现方，理由写得很直白——熬过三轮的循环通常意味着实现方看不见自己的问题，换人和升配一起做。跑满还不收敛就停止派发，逐条裁决：搁置的写清理由，涉及后续任务地基的直接标 BLOCKED 上报。
四、贯彻程度并不均匀：文档评审现在没被派出去
这是把三份文件摆在一起才看得出来的事，也是照抄之前必须知道的一点。
skills/writing-plans/SKILL.md 里有个 Self-Review 小节，第一句就把话说死了：这是你自己跑的检查清单，不是一次派发。它给了三步——规格覆盖、占位符扫描、类型一致性，还举了个例子：Task 3 里叫 clearLayers()、Task 7 里叫 clearFullLayers()，这就是个 bug。发现问题就地改，不用再评审一遍。
skills/brainstorming/SKILL.md 的九步清单同理：第 7 步是规格自查（inline），第 8 步是请用户本人评审写好的规格。也就是说，规格这一层的独立性最终押在人身上，而不是押在另一个 Agent 身上。
所以在这个提交里，流程图上真正被派出去的独立评审只有任务评审和返工后的复评。那两份文档评审模板仍然完整躺在仓库里，随时可以照着填参数派出去，但两个 SKILL 的正文已经不要求这么做了。仓库里还留着一点痕迹：brainstorming 的 User Review Gate 段落写着「After the spec review loop passes」、并且在用户提出修改后要求「re-run the spec review loop」，而它上面刚定义完的已经是一次就地自查。
对你的意义很直接：如果你打算把「规格和计划都过独立评审再执行」这句话当成这套方法论的默认行为，那在这个版本里它不成立，得你自己补上——把两份模板派出去是一个需要你主动做的动作。至于规格先行这件事本身的价值，可以对照 /learn/guige-qudong-kaifa-sdd/。
五、边界与代价
这套流程明确换掉了速度。 一个任务的完整路径是：抽简报、派实现、生成评审包、派评审、可能再走最多五轮返工，每轮都是一次修复派发加一次复评。SKILL.md 自己承认最贵的失败模式是派发方在上下文被压缩后丢了位置、把整段已完成的任务重派了一遍，所以还得额外维护一份台账文件，记录形如 Task <N>: complete (commits <base7>..<head7>, review clean) 的行。这些都是纯开销。
对小改动是过度设计。 改一行文案也要走简报、实现、评审包、双判断，成本远超收益。判断线可以借用 writing-plans 里 Task Right-Sizing 的定义：一个任务是最小的、自带测试周期、且值得一次评审把关的单元；只在「评审方有可能拒掉这一半而通过另一半」的地方才切开。切不出这种边界的改动，本来就不该套这个循环。
它让 Agent 更啰嗦。 报告文件、台账行、findings 列表、裁决理由，全是要写出来的文字产物。这套设计自己也知道，于是到处在压制：SKILL.md 要求工具调用之间最多叙述一行短句，评审提示词要求最终消息直接从判断开始，不要前言、不要过程叙述、不要收尾总结。需要专门写规矩去压的东西，说明是这套设计的固有副作用。
几件它明确不管的事。 任务评审提示词开头就撇清：这是任务范围的一道关卡，不是合并评审，全分支的宽口径评审在所有任务完成后单独做一次。复评不管修复 diff 之外的代码。⚠️ 那一档的项目评审方不负责解决，退回给派发方。模型选得对不对也不归提示词管——它只负责提醒你必须显式指定，因为省略会静默继承会话里最贵的那个。
它绑定 git 和 shell。 两个交接脚本都是 bash：评审包那份靠 git rev-parse、git log --oneline、git diff --stat 和 git diff -U10 干活，简报那份虽然只用 awk，也要先经由共用的工作目录脚本 git rev-parse --show-toplevel 找到仓库根，才知道把文件写去哪。SKILL.md 给了没有 bash 时的退路：自己跑那几条 git 命令、重定向到一个唯一命名的文件里。但如果你的工作流根本没有 git 提交粒度可言，评审包这一半就落不了地，剩下的只有文档层那两份模板。
六、上手与避坑清单
一、派评审时漏掉模型参数。 会踩是因为省略看上去无害，实际上任务评审和复评两份模板都把 [MODEL] 标成 REQUIRED，并注明省略会静默继承会话里最贵的那个模型，你不会收到任何提示。怎么避：把模型当必填项处理，按 diff 的体量、复杂度和风险来选，小的机械改动不需要最强模型。
二、拿 HEAD~1 当 BASE。 会踩是因为顺手，而且大多数时候看起来是对的。但一个任务经常产生多个 commit，HEAD~1 会静默地只保留最后一个，评审方看到的是残缺 diff 却毫不知情。怎么避：派实现之前先记下当时的 HEAD 作为 BASE，生成评审包时用它。SKILL.md 正文里这条禁令写了两遍，review-package 的脚本头注释里还写了第三遍，说明是真踩过。
三、在派发提示词里替对方定调。 会踩是因为你已经预感某条会是误报，想省一轮往返。怎么避：用提示词给的那组自查关键词扫一遍自己写的派发文本，出现 do not flag、don't treat X as a defect、at most Minor、the plan chose 就删掉重写；让它提，你在返工循环里裁决并记进台账，禁止悄悄丢弃。
四、把前面任务的进度摘要粘进新派发。 会踩是因为怕对方不懂背景，多给点总没错。代价是这些字会一直压在你的上下文里，那个 42k 字符的反例就是这么来的。怎么避：只给这一个任务的简报路径、它要触碰的接口签名、以及全局约束；如果早先某个任务在这块地方搁置过问题，给一个指向台账那一行的指针就够了。
五、拿实现方的自评当评审用。 会踩是因为实现方确实也做了自查，看起来重复。但 SKILL.md 明说自查不能替代任务评审，两个都得有；提示词更进一步，把自查里的设计理由也归到待核实的说法里。怎么避：自查是实现方的交付质量责任，评审始终由拿不到它上下文的一方做，角色分工见 /learn/agent-juese-fengong/。
六、忽略 ⚠️ 那一栏。 会踩是因为它不带 ❌，输出里看着像通过。它实际是评审方主动划出的盲区——要求落在没改动的代码里或跨了任务。怎么避：把每一条 ⚠️ 当成一件待办，用你手上的跨任务上下文自己核；确认是真缺口就按规格未通过处理，让它跟其他问题一起进返工循环，而不是标记任务完成。
七、以为文档评审会自动发生。 会踩是因为仓库里明明躺着两份文档评审模板，容易默认它们已经在流程里。怎么避：想要就自己派。填参数时注意区别——规格那份只需要规格路径，计划那份必须同时给计划和规格两个路径，缺了后者，Spec Alignment 这项就没有对照物，等于白审。
真要把这套东西搬进自己的流程，先用四个问题自检一遍：这次派出去的提示词里，有没有任何一句话依赖「我们之前聊过」；被审材料是以文件路径交出去的，还是粘进了正文；有没有出现替对方定调的措辞；⚠️ 和 Minor 这两类结果，有没有确定的去处。四条都能答上来，隔离才算真的立住了。
接着按这个顺序读源文件：先看 skills/subagent-driven-development/SKILL.md 的 The Task Loop 一节，它是整套流程的骨架；再读 task-reviewer-prompt.md 全文，那是三份里唯一被流程真正调用的一份；最后花两分钟扫 scripts/review-package 那四十来行 bash，看它怎么把「交接」这件事彻底落到一个文件上。这三份读完，剩下的模板你自己就能改了。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。