adversarial-review

对抗性评审

使用 fresh-eyes 评审的自动化批评-修复循环。每一轮都以全新的视角审查代码——不了解决策背后的原因，也不对实现抱有偏见。修复 Critical 和 Suggestion 级别的问题，然后由新一轮评审再次检查。仅剩 Nitpick 级别的问题或完成 3 轮后，循环停止。

执行方式——与 Harness 无关

约定是 fresh-eyes 批评-修复循环，而不是某一种具体机制：

• Claude Code —— 每轮都启动一个新的评审子 Agent（Agent 工具， subagent_type: general-purpose），让评审者确实对代码和先前轮次毫无记忆。这是最彻底的「全新视角」。
• Codex / 其他单 Agent harness —— 自行运行循环：每一轮都以全新的视角重新阅读 diff 并进行评审，假装从未见过这些内容，有意搁置你对编写原因的了解。不需要子 Agent；重要的是保持全新视角，而非流程边界。

以下内容均以 Claude 的子 Agent 术语描述循环——单 Agent harness 可将「启动评审者」映射为「进行一次冷评审」，将「新的子 Agent」映射为「从头重新阅读」。

适用场景

• 实现完成后、提交之前——尤其适用于功能和重构
• 更改涉及关键路径、安全敏感代码或复杂逻辑时
• 你希望评审比自己给出的更严格时
• 流程中的位置：implement → /simplify → /adversarial-review → /finalize → commit

不适用场景

• 微小更改、仅文档更改、配置微调——改用 /simplify + /finalize
• 实现过程中——先完成构建，再进行评审
• 只想快速做合理性检查时——改用 /code-review

输入模式

解析 $ARGUMENTS 以确定要评审的内容：

• **无参数：**评审未提交的更改——运行 git diff 和 git diff --cached，获取已暂存和未暂存的更改
• **文件/目录路径：**评审指定文件——直接读取这些文件，并将其作为待评审代码
• **--base=<ref> / --fork=<sha>：**指定用于比较的 base 或 fork 点（调用方传入此参数，以便评审准确看到预期的 diff）。如果提供此参数，则评审 <fork-or-base>...HEAD，并跳过下方的自动解析步骤。
• **--pr 标记：**评审整个分支的 diff。稳健地解析 base——不要假定是 main。使用现有 PR 的 base；否则使用仓库默认分支，并解析为本地存在的 ref，随后确定真正的 fork 点：

  BASE="$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo main)"
  if git rev-parse --verify --quiet "$BASE" >/dev/null; then BASE_REF="$BASE";
  elif git rev-parse --verify --quiet "origin/$BASE" >/dev/null; then BASE_REF="origin/$BASE";
  else echo "No base ref for '$BASE' — fetch it and retry"; exit 1; fi
  FORK="$(git merge-base "$BASE_REF" HEAD)"
  git diff "$FORK"...HEAD
  

如果 diff 为空，请告知用户没有需要评审的内容，然后停止。

第 1 步：收集上下文

派发评审者之前，收集以下两项内容：

Diff

根据上述输入模式收集 diff。这是评审者要评议的内容。

项目规范

在项目中查找评审者应了解的规范文档。查找以下内容：

• CLAUDE.md 文件（项目根目录及嵌套目录）
• 常见位置的指南/规范文档：project/guides/、docs/、.cursor/rules/、AGENTS.md
• Lint 和风格配置文件（.rubocop.yml、.eslintrc.*、.prettierrc、standardrb 配置等）

**预算：**将规范上下文控制在约 5K 个 token。包含 CLAUDE.md 文件和 Lint 配置。不要包含完整的实现指南、功能文档或 README——评审者要评估的是代码质量，而非功能完整性。如果规范材料超出预算，优先保留 CLAUDE.md 文件，其次是 Lint 配置。

第 2 步：派发评审子 Agent

使用 Agent 工具启动一名评审者：

• subagent_type：general-purpose
• description："Adversarial code review — round N"
• prompt：下方的完整评审提示词，其中的 {conventions} 和 {diff} 替换为实际内容

评审提示词

You are a senior developer doing a cold code review. You have never seen this
code before. You have no context on why decisions were made. You did not write
any of this. Review with completely fresh eyes.

## Project Conventions

{conventions}

## Code to Review

{diff}

## Review Criteria

Be opinionated. Review for:

- **Correctness:** bugs, logic errors, edge cases, race conditions
- **Security:** injection, auth bypass, data exposure, OWASP top 10
- **DRY:** duplicated logic that should be extracted
- **Modularity:** classes/methods doing too much, unclear boundaries
- **Testability:** code that's hard to test, missing test coverage
- **Simplicity:** over-engineering, unnecessary abstractions, premature generalization
- **Architecture:** does it conform to the project's established patterns and conventions?
- **Naming:** unclear or misleading names
- **Error handling:** swallowed errors, missing edge cases

## Output Format

Return findings as a list. Each finding MUST have:

- **Severity:** Critical | Suggestion | Nitpick
- **Location:** file path and line range
- **Issue:** what's wrong
- **Fix:** specific, concrete recommendation

Severity definitions:
- **Critical** = bugs, security issues, data loss risk, broken functionality
- **Suggestion** = improvements that meaningfully affect quality, maintainability, or conformance
- **Nitpick** = style preferences, minor naming quibbles, cosmetic issues

Be honest about severity. Don't inflate Nitpicks to Suggestions.
If the code is solid, say so — an empty findings list is a valid result.

Step 3: 处理审查发现

审查子 Agent 返回后：

1. 阅读审查发现
2. 直接在代码中修复所有 Critical 和 Suggestion 项
3. 跳过任何与既定项目规范或本次会话中先前讨论相冲突的发现，并说明跳过原因
4. 记录 Nitpick 项，但不采取行动
5. 跟踪本轮发现和修复的内容

请自行判断。如果某项发现有误或会导致问题，就跳过并说明原因。审查者视角新鲜，但缺少你们的对话上下文——你了解它不了解的内容。

Step 4: 循环

应用修复后：

1. 收集新的差异 — 与原始基线比较（而非上一轮）。每次都应让审查者看到完整的变更集，而不只是修复内容。
2. 使用更新后的差异，启动一个全新的审查子 Agent。不要复用之前的子 Agent。
3. 重复以上步骤，直到满足以下任一条件：
   • 只剩 Nitpick 发现 → 停止，代码已整洁
   • 已完成 3 轮 → 停止，并报告任何剩余的非 Nitpick 发现

Step 5: 报告

完成后，提供摘要：

## Adversarial Review Complete

**Rounds:** N of 3
**Result:** [Clean — only nitpicks remain | Capped — N issues remain after 3 rounds]

### Round 1
- [Critical] file.rb:12-15 — description (FIXED)
- [Suggestion] file.rb:30 — description (FIXED)
- [Nitpick] file.rb:45 — description

### Round 2
- [Nitpick] file.rb:32 — description

### Remaining Nitpicks
- file.rb:45 — description
- file.rb:32 — description

如果第一轮没有任何发现，报告代码已通过审查且没有问题，然后停止。

常见错误

• 第 2 轮复用同一个子 Agent——它会记住自己的发现，失去“新鲜视角”的优势。务必启动一个新的子 Agent。
• 只对比修复内容，而不是完整变更集——第 2 轮的审查者应看到所有内容，而不只是第 1 轮之后的改动。
• 盲目应用所有发现——你拥有审查者缺少的对话上下文。请自行判断。跳过与项目规范或先前决定相冲突的发现，并说明原因。
• 对琐碎改动运行此流程——这会产生不必要的成本。如果只是重命名了一个变量，请改用 /simplify + /finalize。