Claude Code Subagents

Subagents 让 Claude Code 把聚焦工作委派给带独立指令和上下文的代理。它们适合可拆分的调研、审查、测试或实现任务。

最近核验: 2026/7/19
适用版本: Claude Code 2.1.x。本机使用 2.1.198 核对 CLI 拼写；官方文档可能描述更新的 2.1.x 行为。
核验方式: 依据官方文档和本地 agent flags 核对 subagent definition、tool allowlist、nesting 和 permission behavior；未启动 subagent 或模型任务。
官方来源: Subagents Permissions Changelog

可复现实践

设计 Read-only Reviewer Subagent 并证明工具边界

委派独立审查，但不授予编辑、秘密访问或无限 child-agent spawning。

准备

唯一临时仓库。
有预期 evidence 的有界 review question。
除 reviewer 必须读取内容外不放 confidential fixture。

执行步骤

创建 scoped agent definition

只允许 inspection tools，并要求 prompt 输出 evidence。

步骤 1

AGENT_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-agent.XXXXXX")
printf '%s\n' "$AGENT_LAB"
cd "$AGENT_LAB" && git init -q
mkdir -p .claude/agents
printf '%s\n' '---' 'name: read-only-reviewer' 'description: Review a bounded diff and cite file evidence.' 'tools: Read, Grep, Glob' '---' '' 'Report findings by severity. Do not propose edits without cited evidence.' > .claude/agents/read-only-reviewer.md

检查 allowlist
启动前确认 Edit、Write、Bash、MCP 和 Agent 均不存在。
步骤 2
```
sed -n '1,12p' .claude/agents/read-only-reviewer.md
```
在无害 fixture 上运行
要求 main session 用指定 agent 检查一个 text file；本次未执行模型。
独立挑战结果
自行验证引用行，拒绝没有文件证据的结论。

预期结果

Reviewer 给出 file-grounded finding，且不编辑、不运行 command、不调用 MCP、不生成新 agent。

验证

检查 tool usage，不信任 final prose。
确认 `git status --short` 未改变。
用请求编辑的 negative prompt 验证边界。

失败处理

Agent 无法启动

检查 tool name 和 definition scope；未解析 tool 现在会显式失败。

Review 缺少 evidence

收窄任务并要求 file/line citation 后再行动。

清理或回退

返回原目录，只删除打印出的 AGENT_LAB 路径。
通过 reviewed version control 禁用真实 project agent，不编辑 user-level agent。

边界与不适用场景

Subagent 默认继承可用 tools，least privilege 必须显式配置。
Delegation 分离 context，不转移责任；main reviewer 仍需验证 finding 和数据暴露。

为什么隔离任务

隔离可以减少上下文混杂。审查代理专注缺陷，调研代理检查文档，实现代理限制在更窄文件范围内。

并行工作

当子任务相互独立时，并行代理有价值。如果每一步都依赖同一个文件或同一个未定方案，并行通常只会增加协调成本。

指令设计

Subagent 需要明确范围、期望输出和边界。涉及代码改动时，应指定文件或模块归属，避免多个代理互相覆盖。

审查结果

Subagent 输出是输入，不是最终事实。合并前仍要检查证据、冲突、测试结果以及是否符合用户目标。

Command	Description
`/tasks`	查看运行中和已完成的后台 Subagents。
`/background`	分离主会话，让工作继续在后台运行。
`/branch`	尝试不同方向，同时保留当前线程。
`claude agents --json`	以脚本方式读取活跃后台会话。