并行处理测试缺陷的自动化工作流 —— Claude Code + Codex CLI + Git Worktree（Windows/WSL 实战手册）

TL;DR

• 结论：在 WSL2（ext4 文件系统）中，用 claude --worktree <bug-id> 一键派生独立工作树 + 让 Codex 当 fixer / Claude Code 当 reviewer（两者 headless 互调），通过一个 bash 编排脚本控制 fix→review→fix 最多 3 轮的循环,是当前 2026 年中最稳、可直接落地的方案;批量场景再叠一层 xargs -P / GNU parallel 控制并发度即可。
• 关键工具栈：Claude Code 原生 --worktree(由 Anthropic Claude Code 产品负责人 Boris Cherny 在 2026 年 2 月 20 日发布的 v2.1.50 公开宣布,前一天 v2.1.49 先加入了 subagent 级隔离;v2.1.50 是正式带 CLI flag 的版本) + WorktreeCreate/Remove hooks;Codex CLI codex exec / codex exec review --uncommitted --json --output-schema;Codex ~/.codex/agents/*.toml 子代理;Claude Code .claude/agents/、.claude/commands/、settings.json hooks。不要 把项目放在 /mnt/c/ —— vxlabs 实测 WSL2 跨边界访问 NTFS 大约比 WSL1 慢 5 倍(“WSL 2 accessing host (NTFS) files is about 5 times slower than WSL 1 accessing those same files”), 而 WSL2 自身的 ext4 “very close to native Linux performance”, 所以实际 ext4 vs 跨界 NTFS 的差距比 5× 更大。
• 可直接抄走的最小落地物：本报告给出 5 个文件——scripts/dispatch-bug.sh(单缺陷端到端)、scripts/batch-bugs.sh(批量并发)、.claude/agents/code-reviewer.md、.claude/settings.json(hooks + permissions)、~/.codex/agents/bug-fixer.toml。再加一份 CLAUDE.md + AGENTS.md 的约定模板。

Key Findings

1. Claude Code 已原生支持 worktree：v2.1.49 (2026-02-19) 先加入 subagent 级 worktree 隔离,v2.1.50 (2026-02-20) 正式带 --worktree/-w flag —— 由 Anthropic Claude Code 产品负责人 Boris Cherny 在 X 上宣布,该公告被引超过一百万次。 claude -w <name> 自动在 .claude/worktrees/<name>/ 创建分支 worktree-<name>, 结束时还有保留/删除询问; 并提供 WorktreeCreate / WorktreeRemove 两个 hook 用于自定义路径与拷贝 .env。 Anthropic 官方 Common workflows 文档把”用 worktree 跑并行会话”列为推荐模式。
2. Codex CLI 的并行能力分两层：codex exec 是稳定的 headless 入口(Rust 实现,输出 stderr 进度 + stdout 最终消息;--json 是 newline-delimited JSONL 事件流;可叠 --output-schema 强制结构化输出; 可叠 --cd/-C 指定工作目录、--skip-git-repo-check 跳过 git 检查); GA 之后的 Codex Subagents(~/.codex/agents/*.toml)默认 max_threads=6、max_depth=1,** 只有显式指令才会被生成** —— 这意味着批量并行最好在 worktree + 进程级并行(多个 codex exec)做,而不是依赖 Codex 内部的 subagent。
3. Codex 评审有专门子命令 codex exec review：必须传 --uncommitted / --base <branch> / --commit <sha> 三选一; 输出按 [P0]/[P1]/[P2]/[P3] 四级( 注意是 P0–P3 不是 P1–P4,源自 codex-rs/core/review_prompt.md,并在 JSON 中带 priority 字段 0–3); 最后给出 overall correctness 裁决。 但 --json 默认是 JSONL 事件流,需配合 --output-schema 才得到结构化 findings;已知 issue #15451 提示在启用 MCP 时这个组合可能被静默忽略。
4. OpenAI 官方有 codex-plugin-cc 插件(github.com/openai/codex-plugin-cc,2026-03-30 发布,Apache-2.0;unite.ai 原话:“OpenAI published a Codex plugin on March 30 that installs directly inside Anthropic’s Claude Code, letting developers run code reviews and delegate tasks to Codex without leaving their existing workflow”), 在 Claude Code 里直接暴露 6 个 命令:/codex:review、/codex:adversarial-review、/codex:rescue、/codex:status、/codex:result、/codex:cancel。 安装:/plugin marketplace add openai/codex-plugin-cc → /plugin install codex@openai-codex → /codex:setup。 它复用本机的 codex 二进制 + ~/.codex/config.toml, 并提供 Review Gate(基于 Stop hook 的循环评审),但官方 README 自己警告:“review gate can create a long-running Claude/Codex loop and may drain usage limits quickly” —— 因此用于关键评审推荐保留,但批量自动循环要自己控上限。
5. Claude Code Hooks 的关键事件：PreToolUse / PostToolUse / Stop / SubagentStop / SessionStart / WorktreeCreate / WorktreeRemove 等。Stop hook 配合 stop_hook_active 字段可以实现”评审不过就阻塞退出、让 Claude 继续修”,但 必须 在 hook 里检查该字段避免死循环。
6. Claude Code headless 模式核心字段：--print/-p、--output-format json|stream-json|text、--max-turns、--allowed-tools、--permission-mode {default|acceptEdits|plan|dontAsk|bypassPermissions}、 --dangerously-skip-permissions、--bare(推荐用于 CI/脚本,跳过 ~/.claude 自动加载)、 --resume <session-id>。--output-format json 返回的关键字段是 result、session_id、total_cost_usd、num_turns、is_error、duration_ms、usage、modelUsage(** 不是** cost_usd,后者只出现在 stream-json 单条事件里)。
7. WSL 文件系统选择决定生死：vxlabs 的基准测试(2019,WSL2 早期但定性结论至今未变)明确指出”WSL 2 accessing host (NTFS) files is about 5 times slower than WSL 1 accessing those same files”,并建议”copy your files to the WSL 2 local filesystem and work there”; Microsoft 官方 Codex Windows 文档也写明:“Working in Windows-mounted paths like /mnt/c/… can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like ~/code/my-app)”。
8. 同仓库内 Claude + Codex 协作的 footgun：两者会同时编辑文件→ git 状态错乱。社区主流共识(DEV.to 的 samlai 帖、SmartScope 的循环分析)是 物理隔离:项目里同时放 CLAUDE.md(给 Claude)和 AGENTS.md(给 Codex), 再用 worktree 让每个缺陷独占一个工作树。
9. 批量编排参考实现：开源生态已经成熟 —— hamelsmu/claude-review-loop [![](claude-citation:/icon.png?validation=93C51488-4DF4-4D62-8563-6EDAF8BCFA07&citation=eyJlbmRJbmRleCI6NDU3MywibWV0YWRhdGEiOnsiaWNvblVybCI6Imh0dHBzOlwvXC93d3cuZ29vZ2xlLmNvbVwvczJcL2Zhdmljb25zP3N6PTY0JmRvbWFpbj1naXRodWIuY29tIiwicHJldmlld1RpdGxlIjoiR2l0SHViIC0gaGFtZWxzbXVcL2NsYXVkZS1yZXZpZXctbG9vcDogQ2xhdWRlIENvZGUgcGx1Z2luOiBhdXRvbWF0ZWQgY29kZSByZXZpZXcgbG9vcCB3aXRoIENvZGV4IMK3IEdpdEh1YiIsInNvdXJjZSI6IkdpdEh1YiIsInR5cGUiOiJnZW5lcmljX21ldGFkYXRhIn0sInNvdXJjZXMiOlt7Imljb25VcmwiOiJodHRwczpcL1wvd3d3Lmdvb2dsZS5jb21cL3MyXC9mYXZpY29ucz9zej02NCZkb21haW49Z2l0aHViLmNvbSIsInNvdXJjZSI6IkdpdEh1YiIsInRpdGxlIjoiR2l0SHViIC0gaGFtZWxzbXVcL2NsYXVkZS1yZXZpZXctbG9vcDogQ2xhdWRlIENvZGUgcGx1Z2luOiBhdXRvbWF0ZWQgY29kZSByZXZpZXcgbG9vcCB3aXRoIENvZGV4IMK3IEdpdEh1YiIsInVybCI6Imh0dHBzOlwvXC9naXRodWIuY29tXC9oYW1lbHNtdVwvY2xhdWRlLXJldmlldy1sb29wIn1dLCJzdGFydEluZGV4Ijo0NTQ2LCJ0aXRsZSI6IkdpdEh1YiIsInVybCI6Imh0dHBzOlwvXC9naXRodWIuY29tXC9oYW1lbHNtdVwvY2xhdWRlLXJldmlldy1sb29wIiwidXVpZCI6ImI3ODNlNWVmLTJmMjEtNGM4MC05MTI3LWZmMWI5NDlhYmU4ZiJ9 "GitHub")](https://github.com/hamelsmu/claude-review-loop)(Stop-hook + Codex)、 amazedsaint/clocoloop(MAX_ITERATIONS 循环、tmux 监控)、 dementev-dev/adversarial-review [![](claude-citation:/icon.png?validation=93C51488-4DF4-4D62-8563-6EDAF8BCFA07&citation=eyJlbmRJbmRleCI6NDY3NywibWV0YWRhdGEiOnsiaWNvblVybCI6Imh0dHBzOlwvXC93d3cuZ29vZ2xlLmNvbVwvczJcL2Zhdmljb25zP3N6PTY0JmRvbWFpbj1naXRodWIuY29tIiwicHJldmlld1RpdGxlIjoiR2l0SHViIC0gZGVtZW50ZXYtZGV2XC9hZHZlcnNhcmlhbC1yZXZpZXc6IENsYXVkZSBDb2RlIHNraWxsIGZvciBhZHZlcnNhcmlhbCBBSSBjb2RlICYgcGxhbiByZXZpZXcuIE9uZSBBSSB3cml0ZXMsIGFub3RoZXIgdGVhcnMgaXQgYXBhcnQuIEl0ZXJhdGl2ZSBmaXggbG9vcCB1bnRpbCBhcHByb3ZlZC4gwrcgR2l0SHViIiwic291cmNlIjoiR2l0SHViIiwidHlwZSI6ImdlbmVyaWNfbWV0YWRhdGEifSwic291cmNlcyI6W3siaWNvblVybCI6Imh0dHBzOlwvXC93d3cuZ29vZ2xlLmNvbVwvczJcL2Zhdmljb25zP3N6PTY0JmRvbWFpbj1naXRodWIuY29tIiwic291cmNlIjoiR2l0SHViIiwidGl0bGUiOiJHaXRIdWIgLSBkZW1lbnRldi1kZXZcL2FkdmVyc2FyaWFsLXJldmlldzogQ2xhdWRlIENvZGUgc2tpbGwgZm9yIGFkdmVyc2FyaWFsIEFJIGNvZGUgJiBwbGFuIHJldmlldy4gT25lIEFJIHdyaXRlcywgYW5vdGhlciB0ZWFycyBpdCBhcGFydC4gSXRlcmF0aXZlIGZpeCBsb29wIHVudGlsIGFwcHJvdmVkLiDCtyBHaXRIdWIiLCJ1cmwiOiJodHRwczpcL1wvZ2l0aHViLmNvbVwvZGVtZW50ZXYtZGV2XC9hZHZlcnNhcmlhbC1yZXZpZXcifV0sInN0YXJ0SW5kZXgiOjQ2NDYsInRpdGxlIjoiR2l0SHViIiwidXJsIjoiaHR0cHM6XC9cL2dpdGh1Yi5jb21cL2RlbWVudGV2LWRldlwvYWR2ZXJzYXJpYWwtcmV2aWV3IiwidXVpZCI6IjhmZjE5NDQ5LTAwYTItNDBiNy1hMDI3LWU5YTE2ZTljMWYyYyJ9 "GitHub")](https://github.com/dementev-dev/adversarial-review)(Claude 写 / Codex 撕,迭代到 APPROVED)、 Dicklesworthstone/claude_code_agent_farm(20+ agents + tmux), 均可作为模板抄改。
10. Anthropic 多 agent 系统结论可借鉴：他们的 Research 系统跑 orchestrator-worker 模式,内部评估”a multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on our internal research eval”;同时”多代理消耗约 15× tokens 于单代理对话” —— 意味着 批量并行度要克制:3–5 个并发 worktree 已经是甜区,超出会被本机 CPU/磁盘 + API 限速双向卡死。

Details

1. 总体架构

┌────────────────────────── 主机：Windows 11 + WSL2 Ubuntu ──────────────────────────┐
│                                                                                       │
│   ~/code/myrepo/                  (主工作树, main 分支, ext4)                         │
│   ~/code/myrepo/.git/                                                                  │
│   ~/code/myrepo/.claude/worktrees/bug-1023/   (Claude Code -w 自动创建)                │
│   ~/code/myrepo/.claude/worktrees/bug-1042/                                            │
│   ~/code/myrepo/.claude/worktrees/bug-1057/                                            │
│                                                                                       │
│   每个 worktree 内：                                                                   │
│     ┌──────────────────────────────────────────────────────────────┐                 │
│     │  Step A  codex exec  (workspace-write, gpt-5.3-codex)        │ ← fixer         │
│     │  Step B  claude -p --bare  (code-reviewer subagent, JSON)    │ ← reviewer      │
│     │  Step C  if NEEDS_FIX: 回到 A，最多 3 轮                       │                 │
│     │  Step D  生成 summary.md，git commit + 推送 PR                 │                 │
│     └──────────────────────────────────────────────────────────────┘                 │
│                                                                                       │
│   编排层：bash 脚本（dispatch-bug.sh / batch-bugs.sh）                                  │
│   并发控制：xargs -P 3   或  GNU parallel -j 3                                          │
│   日志：~/code/myrepo/.claude/runs/<bug-id>/{fix.log,review.json,summary.md}            │
└──────────────────────────────────────────────────────────────────────────────────────┘

设计原则：

• 谁动文件 vs 谁评审：Codex 拿 workspace-write 写代码;Claude Code 评审时拿 --permission-mode plan 或仅 Read/Grep/Glob/Bash(git diff:*),禁止它再去改文件 —— 这避免了同仓库写入冲突,也让评审更纯粹。
• 互为 reviewer 的优势：两家模型在训练数据和评审偏好上有差异,交叉评审能捕获更多 blind spots。Anthropic《2026 Agentic Coding Trends Report》(resources.anthropic.com 发布的官方 PDF)指出了一个”delegation gap”:“Developers now use AI in roughly 60% of their work — but they report being able to fully delegate only 0–20% of tasks” —— 评审 gate 正是用来弥合这 40–80% 间距的关键机制。
• 不要追求”两个 agent 共享上下文”：CLAUDE.md 给 Claude,AGENTS.md 给 Codex;两者只通过 git diff + 缺陷描述 + reviewer 的 JSON 报告通讯。

2. WSL + Worktree 工程实践

2.1 文件系统位置(必须)

• 把仓库放在 ~/code/...(WSL ext4),不要 放 /mnt/c/...(NTFS via 9P)。
• 如果你必须从 Windows 侧访问,用 \\wsl.localhost\Ubuntu\home\<user>\code\myrepo,性能远好于反过来。
• WSL2 ≥ 2.4.x;Microsoft 官方 Codex Windows 指南推荐 Node.js 22 LTS。

2.2 worktree 目录约定

两种主流方案：

• 方案 A：用 Claude Code 原生 --worktree(推荐起点)。.claude/worktrees/<name>/ 在仓库内,自动清理, 与 Claude 的 hooks/skills 体系深度集成。把 .claude/worktrees/ 加进 .gitignore。
• 方案 B：sibling 目录(推荐给重度并行)。~/code/myrepo-bug-1023/、~/code/myrepo-bug-1042/ 这种同级目录;通过 WorktreeCreate hook 改写 Claude Code 的默认行为。优点:编辑器/Valet/Docker 之类的工具更容易识别;缺点:自己要管清理。

2.3 共享依赖 vs 隔离依赖

2.4 worktree.sh 创建脚本(sibling 目录,含 .env 拷贝)

#!/usr/bin/env bash
# scripts/wt-create.sh — 在仓库同级目录创建 worktree
# 用法: ./scripts/wt-create.sh <bug-id> [base-branch]
set -euo pipefail
BUG_ID="${1:?need bug id}"
BASE="${2:-origin/main}"

REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"
WT_DIR="$(dirname "$REPO_ROOT")/${REPO_NAME}-${BUG_ID}"
BRANCH="bugfix/${BUG_ID}"

git -C "$REPO_ROOT" fetch --quiet origin
if git -C "$REPO_ROOT" show-ref --verify --quiet "refs/heads/${BRANCH}"; then
  git -C "$REPO_ROOT" worktree add "$WT_DIR" "$BRANCH"
else
  git -C "$REPO_ROOT" worktree add -b "$BRANCH" "$WT_DIR" "$BASE"
fi

# 拷贝本地未跟踪文件（.env 等）
[[ -f "$REPO_ROOT/.env" ]] && cp "$REPO_ROOT/.env" "$WT_DIR/.env"
# 共享 node_modules（硬链接，省磁盘且互不污染删除）
if [[ -d "$REPO_ROOT/node_modules" ]]; then
  cp -al "$REPO_ROOT/node_modules" "$WT_DIR/node_modules" 2>/dev/null || \
    ln -s "$REPO_ROOT/node_modules" "$WT_DIR/node_modules"
fi

echo "$WT_DIR"

2.5 清理脚本

#!/usr/bin/env bash
# scripts/wt-clean.sh — 合并/丢弃后清理
set -euo pipefail
WT="${1:?worktree path}"
REPO_ROOT="$(git -C "$WT" rev-parse --show-toplevel || echo "$WT")"
BRANCH="$(git -C "$WT" branch --show-current)"

git -C "$REPO_ROOT" worktree remove --force "$WT" || rm -rf "$WT"
git -C "$REPO_ROOT" branch -D "$BRANCH" 2>/dev/null || true
git -C "$REPO_ROOT" worktree prune

2.6 合并策略建议

• 默认走 PR/MR 流程,不要直接 push main;多个缺陷分支之间相互独立,PR 之间不依赖。
• 在主 worktree 里 git fetch && git rebase origin/main,不要 在 bug worktree 里 rebase —— 因为 bug worktree 的 HEAD 是 reviewer 看过的版本,rebase 后还要重新评审。
• 合并冲突高发的缺陷(动同一个文件):批量阶段串行处理这一小簇,其余仍并行。
• 合并完成后用 wt-clean.sh 回收。

3. Claude Code 高级特性配置

3.1 项目根 CLAUDE.md(约 50 行甜区,过长反而稀释信号)

# 项目约定（Claude Code 读取）

## 必读上下文
- 这是一个 [简述项目]。架构入口：`src/main.ts` → `src/router.ts`。
- 构建：`pnpm build`；测试：`pnpm test`；lint：`pnpm lint`。
- 提交前必须跑 `pnpm lint && pnpm test`。

## 修复缺陷工作流
- 缺陷修复永远在独立 worktree 进行；分支名 `bugfix/<id>`。
- 评审报告写到 `.claude/runs/<id>/review.json`，格式见 `.claude/agents/code-reviewer.md`。
- 修复 summary 写到 `.claude/runs/<id>/summary.md`。

## 硬规则
- 不要修改 `db/migrations/` 下已合入的迁移；新加迁移文件。
- 不要在测试文件外引入 `console.log`。
- 不要碰 `.env`、`secrets/`、`*.key`。

## 评审通过标准
- 单元测试全绿；新增公共 API 必须有测试。
- 不引入新的 lint 错误。
- 修改面 ≤ 影响范围说明里列出的文件。

同目录放 AGENTS.md(Codex 读),内容偏指令式(命令清单、不该做什么),与 CLAUDE.md 互补但 不重复。OpenAI 官方文档明确

3.2 .claude/agents/code-reviewer.md(项目级 subagent)

---
name: code-reviewer
description: 评审一段 git diff，按规约输出结构化 JSON。仅读权限。MUST BE USED when reviewing bug fixes.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(pnpm test:*), Bash(pnpm lint:*)
model: sonnet
---

You are a senior code reviewer. Review the uncommitted diff in the current
worktree against the bug description provided in the prompt.

ALWAYS output ONLY a single JSON object (no prose, no markdown fences) with this shape:

{
  "verdict": "PASS" | "NEEDS_FIX",
  "summary": "<one-line headline>",
  "root_cause": "<短句根因>",
  "issues": [
    {
      "severity": "P0" | "P1" | "P2" | "P3",
      "file": "<path>",
      "line": <int|null>,
      "title": "<问题标题>",
      "detail": "<具体描述>",
      "suggested_fix": "<可选补丁建议>"
    }
  ],
  "tests_run": ["pnpm test", "pnpm lint"],
  "impact": "<影响范围: 文件/模块>",
  "next_steps": "<回归测试建议>"
}

Rules:
- 不要修改任何文件。
- 把 P0/P1 列为 NEEDS_FIX 的依据；P2/P3 可以 PASS 但记录在 issues 里。
- 至少跑 `pnpm test` 和 `pnpm lint` 一次再下判断。

3.3 .claude/settings.json(项目级,已含 hooks 和权限白名单)

{
  "permissions": {
    "allow": [
      "Read", "Grep", "Glob",
      "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
      "Bash(git add:*)", "Bash(git commit:*)", "Bash(git push:*)",
      "Bash(pnpm install:*)", "Bash(pnpm test:*)", "Bash(pnpm lint:*)",
      "Bash(codex exec:*)"
    ],
    "deny": [
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)",
      "Write(./db/migrations/**)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const f=JSON.parse(require('fs').readFileSync(0,'utf8')).tool_input.file_path||''; if(/\\.(ts|tsx|js|jsx)$/.test(f)) require('child_process').execSync('pnpm prettier --write '+JSON.stringify(f),{stdio:'inherit'});\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); [ \"$(echo \"$INPUT\" | jq -r .stop_hook_active)\" = \"true\" ] && exit 0; pnpm -s lint || { echo '{\"decision\":\"block\",\"reason\":\"lint failed, please fix before stopping\"}'; exit 0; }"
          }
        ]
      }
    ],
    "WorktreeCreate": [
      { "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/wt-hook.sh\"" } ] }
    ],
    "WorktreeRemove": [
      { "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/wt-hook.sh\"" } ] }
    ]
  }
}

3.4 自定义 slash command .claude/commands/fix-bug.md

---
description: 修复一个缺陷（在当前 worktree 内运行：先实现修复，再调用 code-reviewer 评审）
argument-hint: <缺陷标题/描述>
allowed-tools: Read, Write, Edit, Bash(git *), Bash(pnpm *), Task
---

任务：修复缺陷 —— $ARGUMENTS

请执行以下步骤：
1. 用 Explore subagent 定位涉及代码（不要把搜索结果塞进主上下文）。
2. 实施最小修复，遵循 CLAUDE.md 的硬规则。
3. 跑 `pnpm test` 和 `pnpm lint`。
4. 调用 `code-reviewer` subagent 评审 git diff，传入本缺陷描述。
5. 如果评审 verdict 为 NEEDS_FIX，按 P0/P1 issues 修复后再次评审，最多 3 轮。
6. 最终输出 `.claude/runs/<id>/summary.md`：根因、改动思路、解决方案、影响范围、测试建议。

3.5 Headless 模式调用模板

# 评审：纯读、结构化 JSON，自动放过常用工具
claude -p --bare \
  --permission-mode dontAsk \
  --allowed-tools "Read,Grep,Glob,Bash(git diff:*),Bash(pnpm test:*),Bash(pnpm lint:*)" \
  --output-format json \
  --max-turns 8 \
  --append-system-prompt "$(cat .claude/agents/code-reviewer.md)" \
  "$(cat <<EOF
请评审当前 worktree 的未提交改动。
缺陷描述：${BUG_DESC}
按 .claude/agents/code-reviewer.md 的 JSON 格式输出。
EOF
)" > review.json

关键 flag 说明：

• --bare：跳过 OAuth/keychain 自动发现和 ~/.claude 的 hooks/skills 加载,CI 必备(官方文档明确”--bare is the recommended mode for scripted and SDK calls, and will become the default for -p in a future release”)。
• --permission-mode dontAsk：未在 allowlist 的工具调用一律拒绝(不是询问),不会卡住脚本。
• --max-turns N：硬上限,防止无限 agent loop 烧 token。
• --output-format json：返回单个 JSON 对象(不是 stream),字段为 result/session_id/total_cost_usd/num_turns/is_error/duration_ms/usage/modelUsage。

4. Codex CLI 高级特性配置

4.1 ~/.codex/config.toml(推荐起点)

model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
approval_policy = "never"     # 给 codex exec 用；交互 TUI 你可以另开 profile

[agents]
max_threads = 6
max_depth = 1

[profiles.bug-fixer]
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
approval_policy = "never"

[profiles.fast]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "low"

[profiles.reviewer]
model = "gpt-5.4"            # 不同家族交叉评审更稳
model_reasoning_effort = "high"
sandbox_mode = "read-only"

4.2 ~/.codex/agents/bug-fixer.toml(custom subagent)

name = "bug-fixer"
description = "实施单一缺陷的最小修复；不重构无关代码。"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
You implement the smallest patch that resolves the reported bug.
- Read AGENTS.md and CLAUDE.md before editing.
- Add or update tests covering the regression.
- Never modify db/migrations files that already exist.
- Run `pnpm test` and `pnpm lint` after your change. Iterate until both pass.
- Emit a final summary with: root cause, patch outline, files changed, test results.
"""
nickname_candidates = ["Patch", "Mender", "Fixer"]

4.3 Headless 调用模板

# fix：写权限、最大化推理强度
codex exec \
  --cd "$WT_DIR" \
  --profile bug-fixer \
  --sandbox workspace-write \
  --json \
  --output-last-message "$RUN_DIR/fix.last.txt" \
  "$(cat <<EOF
请修复以下缺陷。完成后简要总结改动。
缺陷 ID: $BUG_ID
描述: $BUG_DESC
当前 worktree: $WT_DIR
EOF
)" 2> "$RUN_DIR/fix.events.jsonl" \
  | tee "$RUN_DIR/fix.stdout.log"

# review：用 codex 自带的 review 子命令做交叉评审（可选）
codex exec review --uncommitted \
  --cd "$WT_DIR" \
  --profile reviewer \
  --json \
  > "$RUN_DIR/codex-review.jsonl"

codex exec 的关键 flag：

• --cd <DIR> / -C：设工作目录。** 这是多 worktree 并行的核心**。
• --sandbox read-only|workspace-write|danger-full-access： 评审用 read-only,修复用 workspace-write。
• --json：newline-delimited JSONL 事件流(注意:与 Claude 的 --output-format json 行为不同,更像 stream-json)。
• --output-schema schema.json：用 JSON Schema 强约束 final agent message。
• --output-last-message <path>：把最终消息写到文件, 最适合脚本读取。
• --ephemeral：不保存 rollout(一次性任务)。
• --skip-git-repo-check：当 cwd 不是 git 仓库时跳过守卫。
• --full-auto：等价于 --sandbox workspace-write --ask-for-approval never, CI 友好。
• CODEX_API_KEY=xxx codex exec ...：仅在 codex exec 下支持的 inline 鉴权。

4.4 codex-plugin-cc(官方插件,可选加成)

如果你想在 Claude Code 交互里直接 /codex:review：

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

提供的命令(共 6 个,以 openai/codex-plugin-cc 官方 README 为准):/codex:review、/codex:adversarial-review、/codex:rescue(把任务整体交给 Codex)、 /codex:status、/codex:result(查看历史结果,含 Codex session-id 可 codex resume)、/codex:cancel(取消活跃后台作业)。 其底层就是调本机 codex CLI + codex app server,复用 ~/.codex/config.toml。** 注意官方 README 自己警告 Review Gate 会拉长 Claude/Codex 循环、可能快速烧光配额** —— 因此用于”手动派单单个缺陷”很合适,批量场景仍建议走自己写的 bash 脚本以便控上限。

5. 单个缺陷端到端编排脚本(核心落地物)

scripts/dispatch-bug.sh：

#!/usr/bin/env bash
# scripts/dispatch-bug.sh
# 用法: ./scripts/dispatch-bug.sh <BUG_ID> "<BUG_DESC>" [BASE_BRANCH]
set -euo pipefail

BUG_ID="${1:?bug id required}"
BUG_DESC="${2:?bug description required}"
BASE="${3:-origin/main}"
MAX_ROUNDS="${MAX_ROUNDS:-3}"

REPO_ROOT="$(git rev-parse --show-toplevel)"
WT_DIR="$(./scripts/wt-create.sh "$BUG_ID" "$BASE")"
RUN_DIR="$REPO_ROOT/.claude/runs/$BUG_ID"
mkdir -p "$RUN_DIR"

echo "[$BUG_ID] worktree=$WT_DIR  runs=$RUN_DIR"

# 缺陷描述落盘，让 agents 都能读
cat > "$WT_DIR/.bug.md" <<EOF
# Bug $BUG_ID
$BUG_DESC
EOF

round=0
verdict="NEEDS_FIX"
while [[ "$verdict" == "NEEDS_FIX" && $round -lt $MAX_ROUNDS ]]; do
  round=$((round+1))
  echo "[$BUG_ID] ===== Round $round/$MAX_ROUNDS ====="

  # ---- Step 1: Codex 修复 ----
  codex exec \
    --cd "$WT_DIR" \
    --profile bug-fixer \
    --sandbox workspace-write \
    --full-auto \
    --json \
    --output-last-message "$RUN_DIR/fix.r${round}.txt" \
    "$(cat <<EOF
你是 bug-fixer。请修复 $WT_DIR/.bug.md 描述的缺陷。
- 已有评审反馈（如有）: $RUN_DIR/review.r$((round-1)).json
- 最小改动；必须新增/更新覆盖该缺陷的测试。
- 完成后跑 pnpm test 和 pnpm lint，直到通过。
EOF
)" 2> "$RUN_DIR/fix.r${round}.jsonl"

  # ---- Step 2: Claude 评审 ----
  pushd "$WT_DIR" >/dev/null
  claude -p --bare \
    --permission-mode dontAsk \
    --allowed-tools "Read,Grep,Glob,Bash(git diff:*),Bash(git log:*),Bash(pnpm test:*),Bash(pnpm lint:*)" \
    --output-format json \
    --max-turns 10 \
    --append-system-prompt "$(cat "$REPO_ROOT/.claude/agents/code-reviewer.md")" \
    "请评审本 worktree 的未提交改动。缺陷描述见 .bug.md。按规约输出 JSON。" \
    > "$RUN_DIR/review.r${round}.full.json"
  popd >/dev/null

  # 提取 reviewer 输出（result 字段里的 JSON）
  jq -r '.result' "$RUN_DIR/review.r${round}.full.json" > "$RUN_DIR/review.r${round}.json"

  verdict="$(jq -r '.verdict // "NEEDS_FIX"' "$RUN_DIR/review.r${round}.json")"
  echo "[$BUG_ID] Round $round verdict=$verdict"

  if [[ "$verdict" == "PASS" ]]; then
    break
  fi
done

if [[ "$verdict" != "PASS" ]]; then
  echo "[$BUG_ID] ⚠️ 达到 $MAX_ROUNDS 轮仍未通过；请人工介入"
  jq '.issues' "$RUN_DIR/review.r${round}.json" || true
  exit 2
fi

# ---- Step 3: 生成 summary + 提交 ----
claude -p --bare \
  --permission-mode dontAsk \
  --allowed-tools "Read,Bash(git diff:*),Bash(git log:*),Write" \
  --max-turns 6 \
  "$(cat <<EOF
基于本 worktree 的 git diff 和 $RUN_DIR/review.r${round}.json，
生成 $RUN_DIR/summary.md，包含以下小节：
- 根因分析
- 改动思路
- 解决方案（关键 diff 摘要）
- 影响范围（文件/模块/边界）
- 测试建议（回归 case）
EOF
)" > /dev/null

git -C "$WT_DIR" add -A
git -C "$WT_DIR" commit -m "fix($BUG_ID): $BUG_DESC

Auto-fixed by codex+claude review loop ($round rounds).
See $RUN_DIR/summary.md"

# 推送并创建 PR（可选，需要 gh CLI）
if command -v gh >/dev/null; then
  git -C "$WT_DIR" push -u origin "bugfix/$BUG_ID"
  gh pr create --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
    --title "fix($BUG_ID): $BUG_DESC" \
    --body "$(cat "$RUN_DIR/summary.md")" \
    --base main --head "bugfix/$BUG_ID"
fi

echo "[$BUG_ID] ✅ Done. summary: $RUN_DIR/summary.md"

6. 批量并行处理脚本

输入格式(bugs.tsv,制表符分隔)：

1023	登录页 captcha 偶发不刷新
1042	订单详情金额未脱敏
1057	导出 CSV 中文乱码

或者 JSON(bugs.json)—— 同时支持：

#!/usr/bin/env bash
# scripts/batch-bugs.sh
# 用法: ./scripts/batch-bugs.sh bugs.tsv  (TSV: bug_id\tdesc)
#       PARALLEL=3 ./scripts/batch-bugs.sh bugs.tsv
set -euo pipefail
INPUT="${1:?input file (TSV or JSON)}"
PARALLEL="${PARALLEL:-3}"        # 同时跑几个；建议 2-4
LOG="$(git rev-parse --show-toplevel)/.claude/runs/batch-$(date +%Y%m%d-%H%M%S).log"

# 统一转成 "id<TAB>desc" 流
to_pairs() {
  if [[ "$INPUT" == *.json ]]; then
    jq -r '.[] | [.id, .desc] | @tsv' "$INPUT"
  else
    cat "$INPUT"
  fi
}

mkdir -p "$(dirname "$LOG")"
echo "Batch start: $(date)" | tee "$LOG"

to_pairs | \
  xargs -I{} -P "$PARALLEL" bash -c '
    IFS=$"\t" read -r ID DESC <<< "{}"
    echo "[BATCH] start $ID"
    if ./scripts/dispatch-bug.sh "$ID" "$DESC"; then
      echo "[BATCH] ok $ID"
    else
      echo "[BATCH] FAIL $ID ($?)"
    fi
  ' 2>&1 | tee -a "$LOG"

# 汇总报告
echo "=== Batch summary ===" | tee -a "$LOG"
for dir in .claude/runs/*/; do
  id="$(basename "$dir")"
  v="$(jq -r '.verdict // "?"' "$dir"/review.r*.json 2>/dev/null | tail -1)"
  echo "$id  $v"
done | tee -a "$LOG"

并发度建议：

为什么不要更多？ Anthropic 在他们的多 agent 系统博客明确:“a multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on our internal research eval” —— 但同篇博客也指出”multi-agent systems use approximately 15× more tokens than single chats”。本地侧再看,每个 worktree 平均吃 1–2 GB RAM(dev server + 测试进程),并发太高会撞磁盘 IO 墙。

7. 终端复用与可观测性

• 盯多个 agent 同时跑：WSL 内 tmux 是最稳的选择(每个 worktree 一个 pane;tmux -CC 在 Windows Terminal 下也可), Claude Code Agent Farm 等成熟项目都用 tmux + pane title 实时显示状态。
• 不建议在 Windows Terminal 多标签里手动开 N 个会话 —— 重启电脑就全没了。
• 可选 dashboard：disler 的 claude-code-hooks-multi-agent-observability 是基于 hooks 把事件转发到 Bun/SQLite/WebSocket 的实时看板;如果只是 3–5 个并发,看 .claude/runs/*/review.r*.json 已经够。
• 日志命名约定：runs/<bug-id>/fix.r<N>.jsonl、review.r<N>.json、summary.md;状态文件 runs/<bug-id>/status 写 running|fixing|reviewing|passed|failed。

8. 完整端到端演练(虚构示例)

场景：测试同学一次性提交三个缺陷：

• BUG-1023：登录页 captcha 偶发不刷新
• BUG-1042：订单详情金额未脱敏(脱敏正则丢了 $)
• BUG-1057：导出 CSV 中文乱码(缺 UTF-8 BOM)

步骤：

1. WSL 终端：

   BASH复制

   cat > bugs.tsv <<EOF
   1023	登录页 captcha 偶发不刷新
   1042	订单详情金额未脱敏
   1057	导出 CSV 中文乱码
   EOF
   PARALLEL=3 ./scripts/batch-bugs.sh bugs.tsv

2. tmux 里开三个 pane,watch -n 5 'cat .claude/runs/1023/status .claude/runs/1042/status .claude/runs/1057/status'。

3. 大约 8 分钟后,编排脚本依次完成：

• 1023 第 1 轮
  改了 src/components/Captcha.tsx,Claude 评审发现”没加 race condition 测试” → NEEDS_FIX。
• 1023 第 2 轮
  加了测试,Claude 评审 → PASS。
• 1042：Codex 一轮 PASS。
• 1057
  第 1 轮加了 BOM 但破坏了纯 ASCII 文件的兼容性,Claude P1 → NEEDS_FIX;第 2 轮 PASS。

1. 自动 push 三个分支并开 PR;.claude/runs/<id>/summary.md 作为 PR body。
2. 你只在 main 上 git fetch && git rebase origin/main && gh pr review --approve —— 真正的人介入时间 < 10 分钟/批。

9. 常见踩坑(Windows + WSL 专项)

Recommendations

阶段 1(今天 / 1 小时上手)：

1. 把仓库迁到 ~/code/(ext4),WSL 里跑 git clone。
2. 在仓库根写一份 ~50 行的 CLAUDE.md 和 ~30 行的 AGENTS.md(互不重复)。
3. 升级 Claude Code 到 v2.1.50+(2026-02-20 Boris Cherny 在 X 上宣布的版本) 和 Codex CLI v0.125+;试 claude -w demo-task 验证 worktree 工作。
4. 复制本文的 code-reviewer.md 和 settings.json 到 .claude/,跑一次 claude /agents 确认被识别。

阶段 2(一周内 / 单缺陷模式)： 5. 把 scripts/wt-create.sh、scripts/wt-clean.sh、scripts/dispatch-bug.sh 落到仓库;用一个真实的小缺陷跑一遍。 6. 调 MAX_ROUNDS(默认 3,复杂仓库可调到 4–5)和 --max-turns(fix 用 20、review 用 10 是甜区)。 7. 让一两个同事在他们的 worktree 上跑同一个脚本,验证多人多 worktree 不互踩。 8. 基准切换标准：如果 review 通过率第 1 轮 < 60%,先优化 CLAUDE.md 里的”评审通过标准”和 code-reviewer.md 的输出格式,不要急着加更多 agent。

阶段 3(两周内 / 批量模式)： 9. 落 scripts/batch-bugs.sh;用历史 5–10 个真实缺陷做回归测试,看哪些场景被自动 fix 命中率高(小型 bug fix 命中率通常 ≥70%)。 10. 加 tmux + 一个简单的 watch 状态面板。 11. 并发度逐步加压：从 PARALLEL=2 起,加到 weekly 限额或 CPU 触顶为止。

阶段 4(一个月内 / 进阶)： 12. 引入 codex-plugin-cc(OpenAI 2026-03-30 发布的官方插件)做手动派单时的人机协作评审;和脚本化的批量流程并存。 13. 跑评估：每 50 个缺陷统计一次”自动通过率 / 平均轮数 / 平均成本(total_cost_usd)/ 人工干预率”。阈值:自动通过率 < 50% 或人工干预率 > 30% 时,停下来优化 prompts 和约定文档,不要堆 agent 数。注意 Anthropic《2026 Agentic Coding Trends Report》自己报告的”delegation gap” —— 业界平均”AI 用在 60% 的工作里,但实际能完全委派的只有 0–20%”, 30% 的人工干预率是真实合理的基线。 14. 把 .claude/agents/code-reviewer.md 拆成两个:code-reviewer-security(专门看注入/越权/凭证)+ code-reviewer-correctness(逻辑/边界) —— Anthropic 自己博客提到细分 reviewer 能再提一截质量。 15. 不要做的事：

• 不要把 Codex subagent 的 max_depth 调到 ≥2(指数级烧 token)。
• 不要把”修复 + 评审”放到一个 Claude 会话里(自己评审自己有偏差)。
• 不要在主分支的 worktree 上跑批量任务(脏掉主工作树)。
• 不要忽略 --bare —— CI/批量场景下没它就会被本地 ~/.claude 污染。

升级触发器：

• 当批量任务 ≥ 50/天,从 bash 切到 Python + structured logging,并把状态存 SQLite。
• 当团队 > 5 人,把 .claude/agents/、.claude/commands/、scripts/ 提到独立的 plugin 仓库,用 /plugin install 分发。
• 当出现跨缺陷依赖(缺陷 B 必须等 A 合并),切到 DAG 编排(Taskfile/Makefile 或 GitHub Actions matrix)。

Caveats

• 官方 vs 社区做法的标注：worktree 原生支持(v2.1.49 加入 subagent 隔离 / v2.1.50 加入 -w CLI flag,由 Boris Cherny 在 2026-02-20 宣布)、subagents、hooks、headless 模式、codex exec、codex exec review 全部是 Anthropic / OpenAI 官方文档化的特性;codex-plugin-cc(2026-03-30 OpenAI 发布)是 OpenAI 官方仓库;“互为 reviewer 的循环编排脚本”是 社区主流模式(hamelsmu/claude-review-loop、dementev-dev/adversarial-review、ching-kuo/claude-codex 等),不是任何一家官方的”参考实现”。本文给出的 dispatch-bug.sh / batch-bugs.sh 是基于这些项目和官方 flag 文档综合推断的最小可用版,使用前请自己跑通一遍。
• 版本时效性：本文按 2026 年 5 月知识截断写作;Claude Code 与 Codex CLI 迭代非常快(Claude Code ~每周一次小版本,Codex CLI 每月数次发布)。具体 flag 名(特别是 --bare 当前 stable,但 OpenAI 文档预告”will become the default for -p in a future release”)、 --permission-mode 值集合(dontAsk 是较新增加的)、codex exec --json + --output-schema 的稳定性(issue #15451 尚未关闭) 都可能变。升级前先 claude --version 和 codex --version 比对官方 changelog。
• 成本与限额：Anthropic 工程博客明确”multi-agent ≈ 15× tokens of single chat”;fix→review 循环至少 ×2,迭代 3 轮就 ×6 起跳。Claude Max5/Max20 都有每周限额;Codex 看 ChatGPT 订阅档。批量场景务必监控 total_cost_usd 累加,否则容易一夜烧光配额。
• 不适用场景：
  • 涉及大量需求理解 / 跨团队对齐的缺陷(“业务说应该是 A,PM 说应该是 B”),自动化只能帮你写 patch,定不了规约。
  • 必须改 DB schema migration 的缺陷 —— 评审无法替代 DBA review,建议把这类 bug 在 dispatch-bug.sh 入口处过滤出来走人工。
  • UI 视觉 / E2E 类 bug —— 需要 screenshot/录屏,超出本文范围(可以接 Playwright MCP 但复杂度上一档)。
• 关于”P1–P4”严重级：第三方文档(mcpmarket、alexfazio gist)写过 P1–P4;但 openai/codex 仓库内的 codex-rs/core/review_prompt.md 源码使用的是 P0/P1/P2/P3,JSON 里 priority 取 0–3。本文 reviewer subagent 沿用 P0–P3 以与 Codex 评审 JSON 对齐。
• WSL1 不再支持 Codex：Codex CLI 0.115+ 改用 bubblewrap sandbox(OpenAI 官方 Windows 文档明确),WSL1 已停止支持; 必须 WSL2。
• Claude --output-format json 字段细节：本文按 2026 春的字段集编写(total_cost_usd 而非 cost_usd);老脚本里若用了 cost_usd 需迁移。Anthropic 文档原文:“With --output-format json, the response payload includes total_cost_usd and a per-model cost breakdown”。
• Anthropic 多 agent 实验数据来源：报告里”15×”和”90.2% 优于单代理”的数字来自 Anthropic 工程博客《How we built our multi-agent research system》(发布于 2025 年 6 月,资源页 anthropic.com/engineering/multi-agent-research-system),原文:“a multi-agent system with Claude Opus 4 as the lead agent and Claude Sonnet 4 subagents outperformed single-agent Claude Opus 4 by 90.2% on our internal research eval”, 用于 Research(breadth-first 搜索)场景;对于”修复缺陷”这类强依赖、改写文件的工作,他们自己的博客原文也说”multi-agent systems are less effective for tightly interdependent tasks such as coding” —— 所以本文的方案故意在 worktree 层做隔离,避免落入这个陷阱。
• Codex subagent 仍处于演进中：OpenAI 官方文档自己写了”the format may evolve as authoring and sharing mature”。 如果你打算把 ~/.codex/agents/*.toml 当成长期方案,建议把同样的角色用”prompt 注入 + profile 切换”再实现一份作为备份。
• WSL2 ext4 vs NTFS 性能引用细节：vxlabs 的”WSL 2 accessing host (NTFS) files is about 5 times slower than WSL 1 accessing those same files”原意是 WSL2→NTFS 比 WSL1→NTFS 慢 5×,不是 直接对比 WSL2 ext4。同篇文章另外指出 WSL2 自己的 ext4 “very close to native Linux performance”, 所以真实的 ext4 vs 跨界 NTFS 差距实际比 5× 更大,但官方/社区都没给出统一的精确倍数。日常体感是 “在 /mnt/c 下跑 pnpm install 或 git status 会让你怀疑人生”,这就是为什么必须迁到 ~/code/。