03-多 Agent 编排与置信度过滤

多 Agent 编排与置信度过滤

学习目标

本章将分析 Claude Code 中两个代表性多 Agent 插件——feature-dev 和 pr-review-toolkit——掌握：

Orchestrator Command 如何编排多个专项 Agent
置信度打分过滤系统（0-100 分阈值 80）的具体实现
并行 vs 顺序执行的选择策略
只读分析与可写实现的权限分离模式
模型路由：Opus 用于深度分析，Sonnet 用于常规任务，inherit 用于轻量任务

前置知识

本章涉及多 Agent 编排的通用原理，建议先阅读：

下文假设你已理解多 Agent 编排的基础概念，直接聚焦 Claude Code 的具体实现。

项目实践

feature-dev：7 阶段编排

/feature-dev Command 是 Orchestrator 模式的教科书级实现：

关键门控点（用户必须显式确认才能继续）：

阶段	门控类型	等待内容
阶段 3	问答门控	等待用户回答所有歧义问题
阶段 4→5	架构选择	等待用户从多个方案中选择
阶段 5→6	实现授权	不开始编码直到用户明确批准
阶段 7	审查决策	询问用户对审查发现的处理意见

并行启动模式：

阶段 2：2-3 个 code-explorer Agent 同时分析代码库的不同方面
阶段 4：2-3 个 code-architect Agent 分别设计不同架构方案（最小改动、干净架构、务实平衡）
阶段 7：3 个 code-reviewer Agent 从不同维度审查（简洁性/DRY、bug/正确性、项目规范）

只读分析 Agent：所有 3 个 Agent 类型的工具列表完全一致且为只读：

Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput

不包含 Write、Edit、Bash——分析 Agent 仅提供信息，不修改代码。

pr-review-toolkit：6 专项 Agent

与 feature-dev 的 3 通用 Agent 不同，pr-review-toolkit 采用专项 Agent 模式，每个 Agent 专注一个审查维度：

Agent	模型	专注领域	输出
`code-reviewer`	opus	代码质量、bug、CLAUDE.md 规范	Critical/Important 问题
`code-simplifier`	opus	代码简化和一致性	简化建议
`comment-analyzer`	inherit	注释准确性和时效性	注释问题列表
`pr-test-analyzer`	inherit	测试覆盖和行为缺口	关键度 1-10 的测试缺口
`silent-failure-hunter`	inherit	静默失败和错误处理	CRITICAL/HIGH/MEDIUM 问题
`type-design-analyzer`	inherit	类型设计和不变量	封装/不变量评分 1-10

上下文感知触发：Command 根据 git diff --name-only 的结果决定启动哪些 Agent：

始终启动：code-reviewer
测试文件变更 → pr-test-analyzer
注释/文档变更 → comment-analyzer
错误处理变更 → silent-failure-hunter
类型文件变更 → type-design-analyzer
审查通过后 → code-simplifier

模型路由策略：

opus 用于深度代码审查和简化（需要理解复杂代码路径）
inherit 用于其他轻量分析（继承调用者的模型，降低成本）

置信度打分系统

code-reviewer Agent 实现了 0-100 定量置信度系统：

分数	含义
0	完全没信心 — 误报或已有问题
25	有些信心 — 可能是问题，可能是风格偏好
50	中等信心 — 真实问题但可能是小毛病
75	高度信心 — 已复核，很可能是真实问题
100	完全确定 — 确定真实，会频繁发生

阈值 = 80：仅报告置信度 ≥ 80 的发现。

报告分组：

Critical (90-100)：严重 bug 或 CLAUDE.md 规范违反
Important (80-89)：需要关注的中等问题
不报告 (0-79)：低于阈值，被过滤

并行 vs 顺序执行

pr-review-toolkit 支持两种执行模式：

/pr-review-toolkit:review-pr              # 顺序（默认）
/pr-review-toolkit:review-pr all parallel # 并行

维度	顺序	并行
速度	慢（逐个完成）	快（同时工作）
可理解性	每份报告依次到达	需要聚合所有报告
Token 效率	较高（可复用前一个结果）	较低（可能重复读取相同文件）

结构化输出聚合

所有 Agent 定义统一的输出模板，使编排者可以聚合结果：

## 审查摘要
- Critical (90-100): ...
- Important (80-89): ...

## 发现列表
| 严重度 | 文件:行号 | 问题描述 | 修复建议 | 来源 Agent |
|--------|----------|---------|---------|-----------|

每个发现都标记来源 Agent，用户知道是哪个专项 Agent 发现的。

陷阱与对策

陷阱	表现	对策
并行 Agent 重复读取相同文件	Token 浪费	编排者预先读取共享文件，注入各 Agent 上下文
置信度阈值过低（如 50）	噪音过多，用户忽略报告	保持阈值在 80+
门控点缺失	Agent 自动推进到实现阶段，用户来不及审查	在 Command 中显式添加”等待用户确认”指令
Agent 工具集过大	分析 Agent 意外修改代码	只包含 Read/Glob/Grep 等只读工具

设计取舍

为什么 feature-dev 的分析 Agent 没有写入权限？

分析 ≠ 实现。分析阶段的目标是理解问题和约束，而非解决问题。如果分析 Agent 在分析过程中修改代码，可能破坏后续 Agent 需要的分析基线，也让用户失去对变更的可见性和控制力。

为什么 code-reviewer 用 Opus 而其他 Agent 用 inherit？

代码审查是最关键的环节——误报会浪费开发者时间，漏报可能引入 bug。Opus 的更强推理能力对于识别复杂代码路径中的边界条件至关重要。其他 Agent（如注释分析、测试分析）的任务相对机械，inherit 足够。

为什么需要 3 个 code-reviewer Agent 而非 1 个通用审查？

每个 Agent 从不同维度审视代码：一个关注简洁性和 DRY 原则，一个关注 bug 和正确性，一个关注项目规范遵循度。合并为一个 Agent 会导致注意力分散，降低每个维度的审查深度。

参考来源

Claude Code Subagent 文档
源码: plugins/feature-dev/commands/feature-dev.md
源码: plugins/feature-dev/agents/code-*.md
源码: plugins/pr-review-toolkit/commands/review-pr.md
源码: plugins/pr-review-toolkit/agents/*.md

版本信息

📅 2026-05-24 🏷️ v2.1.150 🔀 39e853e