adverse-review

Adverse — 多 Agent 对抗式代码审查

此技能是 adverse 项目中面向 Claude Code 的原生部分。同样的逻辑也可通过独立 CLI（adverse review …）使用。在 Claude Code 中运行时，优先使用此技能——它使用 Claude Code 原生的 Agent 工具来启动审查者（没有子进程身份验证问题，速度更快），并且仅在确定性源代码收集和综合步骤中调用 Node 辅助程序。

何时使用此技能

用户明确要求对代码进行对抗式／多视角／评审小组审查，或者用户即将合并／提交／发布一项重要更改，并要求再检查一遍。如果差异只是简单的机械性改动（格式调整、依赖项升级、拼写错误），则不要调用此技能——说明原因并停止。

前置条件

PATH 中需有 node（>= 20）。使用 node --version 进行验证。技能脚本位于 ${SKILL_DIR}/scripts/ 下，且仅使用标准库（无需运行 npm install）。

如果缺少 node，请告知用户：从 nodejs.org（或其包管理器）安装 Node 20+ 后重新调用。不要改用其他实现；确定性综合器是此流程的约定。

阶段 0 — 确定审查范围

在消耗令牌前确定范围：

1. 如果用户指定了路径，则以该路径为范围。
2. 否则，如果 git status --porcelain 报告存在未提交的更改，则审查这些更改（与 HEAD 对比的 diff 模式）。
3. 否则，如果当前分支领先于 main（或 master／已配置的上游分支），则审查自合并基点以来的 diff。
4. 否则审查整个工作目录。

用一句话说明所选范围，让用户可以提出调整。

阶段 1 — 收集源代码

运行 Node 辅助程序，遍历目标并生成一个适合放入提示词的文本块：

node ${SKILL_DIR}/scripts/collect.mjs --target <path> [--diff [base]] --out /tmp/adverse-source.txt --files-out /tmp/adverse-files.json

/tmp/adverse-source.txt 是要嵌入审查者提示词的内容。 /tmp/adverse-files.json 是文件列表（使用它向用户确认范围）。此辅助程序实施与 CLI 相同的源代码大小上限。

如果收集失败，请向用户说明错误——几乎总是“未找到目标”或“diff 为空”。

阶段 2 — 第 1 轮：独立审查

使用 Claude Code 的 Agent 工具，并行启动三名审查者，每名审查者对应一个角色。每名审查者会收到：

• 系统提示词：从 ${SKILL_DIR}/scripts/prompts/<persona>.txt 读取（auditor / adversary / pragmatist）。
• 用户消息：在 /tmp/adverse-source.txt 内容前加上 ${SKILL_DIR}/scripts/prompts/round1.txt。
• 模型：除非用户要求其他模型，否则使用 opus。如果用户选择了较小的模型，将其用于所有三个角色——不同角色使用不同模型会违背单模型设计。

每个子 Agent 必须返回一个符合以下架构的单一 JSON 对象：

{
  "persona": "<auditor|adversary|pragmatist>",
  "verdict": "approve|conditional|reject",
  "summary": "<one sentence>",
  "findings": [
    {
      "severity": "critical|warning|info",
      "file": "<path or null>",
      "line": <int or null>,
      "title": "<short noun phrase>",
      "detail": "<2-6 sentences>",
      "fix": "<concrete remediation or null>"
    }
  ]
}

将每个解析后的 JSON 对象保存到磁盘：

• /tmp/adverse-round1-auditor.json
• /tmp/adverse-round1-adversary.json
• /tmp/adverse-round1-pragmatist.json

如果子 Agent 返回格式错误的 JSON，则仅针对该角色重试一次，并将解析器／验证器错误追加到原始提示词中。如果重试仍失败，则舍弃该角色。如果存活的角色少于 2 个，则中止运行并报告失败——综合至少需要 2 个观点。

三名审查者全部完成后，将结果合并到一个文件中，供下一阶段使用：

node ${SKILL_DIR}/scripts/combine.mjs \
    --round1 /tmp/adverse-round1-auditor.json /tmp/adverse-round1-adversary.json /tmp/adverse-round1-pragmatist.json \
    --out /tmp/adverse-round1.json

阶段 3 — 第 2 轮：交叉评审

针对每个完成了有效第 1 轮评审的角色，启动一个子 Agent，使其：

• 查看所有第 1 轮评审（合并后的 /tmp/adverse-round1.json）。
• 验证自己认同的发现（跨评审方向验证就是判断信号）。
• 对自己认为错误或夸大的发现提出质疑（并说明具体原因）。
• 可选择补充其他视角提出的新发现。

系统提示词：与第 1 轮使用相同的角色文件。用户提示词：${SKILL_DIR}/scripts/prompts/round2.txt 的内容，然后是合并后的第 1 轮 JSON，最后是源代码块。

输出架构：

{
  "persona": "<auditor|adversary|pragmatist>",
  "validate":  [{ "from": "<reporter>", "title": "<title>", "reason": "<…>" }],
  "challenge": [{ "from": "<reporter>", "title": "<title>", "reason": "<…>" }],
  "added":     [<finding object>]
}

将每个结果保存到 /tmp/adverse-round2-<persona>.json，然后合并：

node ${SKILL_DIR}/scripts/combine.mjs \
    --round2 /tmp/adverse-round2-*.json \
    --out /tmp/adverse-round2.json

如果用户要求加快评审，或使用了 --single-round，则完全跳过阶段 3。综合器会将缺失的第 2 轮视为空交叉评审。

阶段 4 — 综合

运行确定性综合器。这会生成规范报告——切勿自行用 LLM 编写发现结果，综合器的分组（交叉验证／共识／有争议／单独提出）本身就传达了判断信号。

node ${SKILL_DIR}/scripts/synthesize.mjs \
    --round1 /tmp/adverse-round1.json \
    --round2 /tmp/adverse-round2.json \
    --out /tmp/adverse-report.md \
    --json-out /tmp/adverse-report.json \
    --html-out /tmp/adverse-report.html

阅读 /tmp/adverse-report.md，并向用户提供摘要，而非完整报告：

1. 结论行（例如，SHIP-WITH-CAVEATS (2/3 ship, 1/3 block)）。
2. 按严重程度和置信度统计数量。
3. 最重要的 3 项发现（优先列出交叉验证，其次是共识，最后是有争议的发现），并各用一行概述。
4. 指明磁盘上完整报告和 HTML 仪表板的位置。

然后询问用户希望如何继续：

• 只修复经过交叉验证的发现？（置信度最高）
• 修复除有争议项之外的所有内容？（最常见）
• 查看某项具体发现的完整推理过程？
• 只保存报告，由我自行审阅？

在用户选择之前，不要开始编辑文件。

阶段 5 — 清理

用户处理完报告后，删除 /tmp/adverse-*，并告知用户本次运行已完成。不要提交这些文件。

故障处理

故障	处理方式
collect.mjs 退出码非零	告知用户错误。常见原因：目标不存在、在非 git 目录中使用 --diff、差异为空。
某位评审者连续两次返回无效内容	继续使用 2 位评审者，并在摘要中将本次运行标记为“降级”。
≥2 位评审者失败	中止。告知用户模型运行异常，并建议使用其他模型或 --single-round 重新运行。
node 不在 PATH 中	告知用户安装 Node 20+。不要自行变通。
用户中断	停止启动新的子 Agent。告知用户部分产物的位置。

给编排器的备注

• 此技能约需 6 次模型调用（3 次第 1 轮 + 3 次第 2 轮）。按用户要求跳过第 2 轮，可减少一半调用。
• 角色提示词有意要求“专注于各自领域”——不要用通用评审指令覆盖它们，否则会削弱设计所依赖的正交性。
• 综合器是使用 Node 编写的确定性代码，不依赖 Python（synthesize.mjs）。验证／质疑边的数量就是共识信号；不要再运行第 4 次 LLM“裁判”环节。
• 独立 CLI（adverse review）是另一种运行方式，可通过子进程调用任意编码 Agent（claude -p、codex exec 等）。只有用户询问如何在 Claude Code 之外运行时，才向其提及。