code-review-expert

name

code-review-expert

description

通用代码审核专家 — 基于 git worktree 隔离的多 Agent 并行代码审核系统，集成 Context7 MCP 三重验证对抗代码幻觉。 语言无关，适用于任意技术栈（Go, Python, JS/TS, Rust, Java, C# 等）。 Use when: (1) 用户要求代码审核、code review、安全审计、性能审查, (2) 用户说"审核代码"、"review"、"检查代码质量"、"安全检查", (3) 用户要求对 PR、分支、目录或文件做全面质量检查, (4) 用户提到"代码审核专家"或"/code-review-expert"。 五大审核维度：安全合规、架构设计、性能资源、可靠性数据完整性、代码质量可观测性。 自动创建 5 个 git worktree 隔离环境，派发 5 个专项子 Agent 并行审核， 通过 Context7 MCP 拉取最新官方文档验证 API 用法，消除 LLM 幻觉， 汇总后生成结构化 Markdown 审核报告，最终自动清理所有 worktree。

Universal Code Review Expert

基于 git worktree 隔离 + 5 子 Agent 并行 + Context7 反幻觉验证的通用代码审核系统。

Guardrails

• 只读审核，绝不修改源代码，写入仅限报告文件
• 语言无关，通过代码模式识别而非编译发现问题
• 每个子 Agent 在独立 git worktree 中工作
• 审核结束后无条件清理所有 worktree（即使中途出错）
• 问题必须给出具体 file:line，不接受泛泛而谈
• 涉及第三方库 API 的发现必须通过 Context7 MCP 验证，严禁凭记忆断言 API 状态
• 文件 > 500 个时自动启用采样策略
• 上下文保护：严格遵循下方 Context Budget Control 规则，防止 200K 上下文耗尽

Context Budget Control (上下文预算管理)

核心问题：5 个子 Agent 并行审核时，每个 Agent 读取大量文件会快速耗尽 200K 上下文，导致审核卡住或失败。

预算分配策略

主 Agent 在 Phase 0 必须计算上下文预算，并分配给子 Agent：

总可用上下文 ≈ 180K tokens（预留 20K 给主 Agent 汇总）
每个子 Agent 预算 = 180K / 5 = 36K tokens
每个子 Agent 可读取的文件数 ≈ 36K / 平均文件大小

七项强制规则

1. 文件分片不重叠：每个文件只分配给一个主要维度（按文件类型/路径自动判断），不要多维度重复审核同一文件。高风险文件（auth、crypto、payment）例外，可分配给最多 2 个维度。

2. 单文件读取上限：子 Agent 读取单个文件时，使用 Read 工具的 limit 参数，每次最多读取 300 行。超过 300 行的文件分段读取，仅审核关键段落。

3. 子 Agent prompt 精简：传递给子 Agent 的 prompt 只包含：

   • 该维度的精简检查清单（不要传全部 170 项，只传该维度的 ~30 项）
   • 文件列表（路径即可，不包含内容）
   • C7 缓存中该维度相关的部分（不传全量缓存）
   • 输出格式模板（一次，不重复）

4. 结果输出精简：子 Agent 找到问题后只输出 JSON Lines，不要输出解释性文字、思考过程或总结。完成后只输出 status 行。

5. 子 Agent max_turns 限制：每个子 Agent 使用 max_turns 参数限制最大轮次：

   • 文件数 ≤ 10: max_turns=15
   • 文件数 11-30: max_turns=25
   • 文件数 31-60: max_turns=40
   • 文件数 > 60: max_turns=50

6. 大仓库自动降级：

   • 文件数 > 200：减为 3 个子 Agent（安全+可靠性、架构+性能、质量+可观测性）
   • 文件数 > 500：减为 2 个子 Agent（安全重点、质量重点）+ 采样 30%
   • 文件数 > 1000：单 Agent 串行 + 采样 15% + 仅审核变更文件

7. 子 Agent 使用 run_in_background：所有子 Agent Task 调用设置 run_in_background=true，主 Agent 通过 Read 工具轮询 output_file 获取结果，避免子 Agent 的完整输出回填到主 Agent 上下文。

文件分配算法

按文件路径/后缀自动分配到主要维度：

模式	主维度	辅助维度（仅高风险文件）
*auth*, *login*, *jwt*, *oauth*, *crypto*, *secret*	Security	Reliability
*route*, *controller*, *handler*, *middleware*, *service*	Architecture	-
*cache*, *pool*, *buffer*, *queue*, *worker*	Performance	-
*db*, *model*, *migration*, *transaction*	Reliability	Performance
*test*, *spec*, *log*, *metric*, *config*, *deploy*	Quality	-
其余文件	按目录轮询分配到 5 个维度	-

主 Agent 汇总时的上下文控制

Phase 3 汇总时，主 Agent 不要重新读取子 Agent 审核过的文件。仅基于子 Agent 输出的 JSON Lines 进行：

• 去重合并
• 严重等级排序
• Context7 交叉验证（仅对 critical/high 且未验证的少数发现）
• 填充报告模板

---

Workflow

Phase 0 — Scope Determination

1. 确定审核范围（按优先级）：

   • 用户指定的文件/目录
   • 未提交变更：git diff --name-only + git diff --cached --name-only
   • 未推送提交：git log origin/{main}..HEAD --name-only --pretty=format:""
   • 全仓库（启用采样：变更文件 → 高风险目录 → 入口文件 → 其余 30% 采样）

2. 收集项目元信息：语言构成、目录结构、文件数量

3. 生成会话 ID：

   SESSION_ID="cr-$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 4)"
   WORKTREE_BASE="/tmp/${SESSION_ID}"
   

4. 将文件分配给 5 个审核维度（每个文件可被多维度审核）

Phase 0.5 — Context7 Documentation Warm-up (反幻觉第一重)

详细流程见 references/context7-integration.md

1. 扫描依赖清单（go.mod, package.json, requirements.txt, Cargo.toml, pom.xml 等）
2. 提取核心直接依赖，按优先级筛选最多 10 个关键库：
   • P0 框架核心（web 框架、ORM）→ P1 安全相关 → P2 高频 import → P3 其余
3. 对每个库调用 resolve-library-id → get-library-docs（每库 ≤ 5000 tokens）
4. 构建 C7 知识缓存 JSON，传递给所有子 Agent
5. 降级：Context7 不可用时跳过，报告标注 "未经官方文档验证"

Phase 1 — Worktree Creation

CURRENT_COMMIT=$(git rev-parse HEAD)
for dim in security architecture performance reliability quality; do
  git worktree add "${WORKTREE_BASE}/${dim}" "${CURRENT_COMMIT}" --detach
done

Phase 2 — Parallel Sub-Agent Dispatch (反幻觉第二重)

在一条消息中发出所有 Task 调用（subagent_type: general-purpose），必须设置：

• run_in_background: true — 子 Agent 后台运行，结果写入 output_file，避免回填主 Agent 上下文
• max_turns — 按文件数量设置（见 Context Budget Control）
• model: "sonnet" — 子 Agent 使用 sonnet 模型降低延迟和 token 消耗

Agent 数量根据文件规模自动调整（见 Context Budget Control 大仓库降级规则）。

每个 Agent 收到：

参数	内容
worktree 路径	${WORKTREE_BASE}/{dimension}
文件列表	该维度独占分配的文件（不重叠）
检查清单	该维度对应的精简清单（~30 项，非全量 170 项）
C7 缓存	仅该维度相关的库文档摘要
输出格式	JSON Lines（见下方）
文件读取限制	单文件最多 300 行，使用 Read 的 limit 参数

每个发现输出一行 JSON：

{
  "dimension": "security",
  "severity": "critical|high|medium|low|info",
  "file": "path/to/file.go",
  "line": 42,
  "rule": "SEC-001",
  "title": "SQL Injection",
  "description": "详细描述",
  "suggestion": "修复建议（含代码片段）",
  "confidence": "high|medium|low",
  "c7_verified": true,
  "verification_method": "c7_cache|c7_realtime|model_knowledge",
  "references": ["CWE-89"]
}

关键规则：

• 涉及第三方库 API 的发现，未经 Context7 验证时 confidence 不得为 high
• verification_method == "model_knowledge" 的发现自动降一级置信度
• 每个子 Agent 最多消耗分配的 Context7 查询预算
• 完成后输出：{"status":"complete","dimension":"...","files_reviewed":N,"issues_found":N,"c7_queries_used":N}

Phase 3 — Aggregation + Cross-Validation (反幻觉第三重)

1. 等待所有子 Agent 完成
2. 合并 findings，按 severity 排序
3. Context7 交叉验证：
   • 筛选 c7_verified==false 且 severity 为 critical/high 的 API 相关发现
   • 主 Agent 独立调用 Context7 验证
   • 验证通过 → 保留 | 验证失败 → 降级或删除（标记 c7_invalidated）
4. 去重（同一 file:line 合并）
5. 生成报告到 code-review-report.md（模板见 references/report-template.md）

Phase 4 — Cleanup (必须执行)

for dim in security architecture performance reliability quality; do
  git worktree remove "${WORKTREE_BASE}/${dim}" --force 2>/dev/null
done
git worktree prune
rm -rf "${WORKTREE_BASE}"

即使前面步骤失败也必须执行此清理。

Severity Classification

等级	标签	定义
P0	critical	已存在的安全漏洞或必然导致数据丢失/崩溃
P1	high	高概率触发的严重问题或重大性能缺陷
P2	medium	可能触发的问题或明显设计缺陷
P3	low	代码质量问题，不直接影响运行
P4	info	优化建议或最佳实践提醒

置信度：high / medium / low，低置信度须说明原因。

Five Review Dimensions

每个维度对应一个子 Agent，详细检查清单见 references/checklists.md：

1. Security & Compliance — 注入漏洞(10 类)、认证授权、密钥泄露、密码学、依赖安全、隐私保护
2. Architecture & Design — SOLID 原则、架构模式、API 设计、错误策略、模块边界
3. Performance & Resource — 算法复杂度、数据库性能、内存管理、并发性能、I/O、缓存、资源泄漏
4. Reliability & Data Integrity — 错误处理、空值安全、并发安全、事务一致性、超时重试、边界条件、优雅关闭
5. Code Quality & Observability — 复杂度、重复、命名、死代码、测试质量、日志、可观测性、构建部署

Context7 Anti-Hallucination Overview

详细集成文档见 references/context7-integration.md

三重验证防御 5 类 LLM 幻觉：

幻觉类型	说明	防御层
API 幻觉	错误断言函数签名	第一重 + 第二重
废弃幻觉	错误标记仍在用的 API 为 deprecated	第二重 + 第三重
不存在幻觉	声称新增 API 不存在	第一重 + 第二重
参数幻觉	错误描述参数类型/默认值	第二重实时查
版本混淆	混淆不同版本 API 行为	第一重版本锚定

验证覆盖度评级：FULL (100% API 发现已验证) > PARTIAL (50%+) > LIMITED (<50%) > NONE

Error Handling

• 某个子 Agent 失败：继续汇总其他结果，报告标注不完整维度
• git worktree 创建失败：git worktree prune 重试 → 仍失败则回退串行模式
• Context7 不可用：跳过验证阶段，报告标注 "未经官方文档验证"
• 所有情况下 Phase 4 清理必须执行

Resources

• references/checklists.md — 5 个子 Agent 的完整检查清单 (~170 项)
• references/context7-integration.md — Context7 MCP 集成详细流程、缓存格式、查询规范
• references/report-template.md — 审核报告 Markdown 模板