Claude Code Subagents 实战：用专职子 Agent 做 review、调试、研究

适用场景

主对话窗口越塞越满、什么都丢给一个 agent 干，结果上下文被 review 输出、调试日志、研究资料污染，质量下降——这就是 Context Rot。Claude Code 的 subagents（子 agent） 是解法：把特定职责（代码审查、调试、文档、安全审计）交给独立上下文窗口 + 独立系统提示 + 受限工具权限的专职 agent，它在自己的窗口里干完，只把结论返回主线程，中间的文件内容和工具调用不污染你的主对话。

适合：

主会话频繁被大段 review / 日志 / 资料撑爆上下文的人
想要「一个写、一个独立审」而不是同一 agent 自夸自审的工作流
团队想把 review 标准、调试套路固化成可版本控制、可复用的角色
需要把高风险操作（审查）锁成只读、和能写代码的 builder 分开的场景

来源说明：本文基于 Claude Code 官方文档与多份 2026 实操指南综合整理。subagent 的存放路径、优先级、frontmatter 字段以官方最新文档为准。

核心概念：subagent 是什么

每个 subagent 是一个带 YAML frontmatter 的 Markdown 文件，body 逐字成为它的系统提示
它运行在自己独立的上下文窗口里，拿到的只有这个系统提示 + 基本环境信息（如工作目录），不继承 Claude Code 的完整主系统提示
主 agent 把任务委派给它，它跑完只返回最终结果——中间推理和工具调用对主线程不可见
这带来三个好处：上下文隔离（防污染）、并行探索、token 高效

定义文件的解剖

最小形态：

---
name: code-reviewer
description: Reviews code for quality and best practices. Use PROACTIVELY after writing code.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback. Flag security issues, performance
problems, and convention violations with the exact fix for each.
Output as a prioritized list. Do not modify any files.

字段含义：

字段	作用
`name`	唯一标识，调用时用它。整棵目录树里必须唯一
`description`	触发器，不是文档——Claude 靠它判断要不要自动委派
`tools`	安全杠杆：省略=继承全部工具；列出=只给这些（reviewer 只给只读工具）
`model`	成本杠杆：grep 密集的探索类路由到 Haiku 而非 Opus，省钱

关键：body 是系统提示，description 是委派的「使用条件」。社区惯例是在 description 里加 Use PROACTIVELY 或 use immediately after writing code 之类的话，推动 Claude 不用你开口就委派。

存放位置与优先级

Claude Code 在多个位置找 subagent 定义，同名时高优先级的赢（从高到低）：

Managed settings——组织级，管理员部署，最高优先级
--agents CLI flag——启动时用 JSON 定义，仅当次会话
.claude/agents/——项目级，提交进仓库，团队共享
~/.claude/agents/——用户级，个人的，跨所有项目可用
Plugin agents/ 目录——插件提供，最低优先级

两个注意点：

项目级 .claude/agents/ 是放「这个 codebase 专用 agent」的正确位置，提交进版本控制，全队用同一套并共同改进
两个目录都递归扫描，可以按 agents/review/、agents/research/ 分子目录组织——子目录路径不影响 agent 身份，身份只来自 name。同一 scope 下两个文件同名，Claude Code 会静默丢弃一个，所以全树 name 必须唯一
插件提供的 subagent 出于安全会忽略 hooks、mcpServers、permissionMode

三种调用方式（从建议到强制）

# 1. 自然语言——给个建议，Claude 自己决定要不要用
claude -p "Use the code-reviewer subagent to review payment.py"

# 2. @-mention——指定哪个 subagent 跑（不控制它收到的 prompt）
#    在交互界面输入 @ 选，或手写 @agent-code-reviewer
#    插件 agent 用带 scope 的名字，如 @agent-my-plugin:code-reviewer

# 3. --agent——整个会话都变成这个 agent（替换默认系统提示、工具限制、模型）
claude --agent code-reviewer

进阶：在 .claude/settings.json 里设 "agent": "<name>" 让某 agent 成为项目默认；CLI flag 同时存在时覆盖该设置。

记住递进关系：自然语言 = 建议，@-mention = 单次任务的保证，--agent = 整个会话就是那个 agent。

实战：read-only reviewer

把上面那个 code-reviewer.md 放进 .claude/agents/，然后：

claude -p "Use the code-reviewer subagent to review payment.py"

reviewer 用它那三个只读工具读文件、在自己的窗口里分析，flag 出 SQL 注入、O(n²) 循环并给出确切修法。这些都没以原始文件内容的形式进主对话——回来的是一份干净的结论报告。这就是 subagent 的全部价值：聚焦的 agent、锁死只读、在自己窗口里干完、返回紧凑总结。

常见踩坑

description 写成文档而非触发条件：Claude 靠它决定委派，写「这个 agent 审查代码」不如写「写完代码后主动用它审查质量和安全」。
同名静默覆盖：同一 scope 两个文件同名，Claude 静默保留一个丢另一个，全树 name 必须唯一。
reviewer 给了写权限：审查类 agent 一定锁只读（只给 Read/Glob/Grep），否则它可能边审边改，失去「独立第二意见」的意义。
什么都不限 tools：省略 tools 等于继承全部工具，敏感场景要显式收窄。
全用 Opus：grep 密集的探索类用 Opus 是浪费，路由到 Haiku/Sonnet。
body 太长：body 是系统提示，几千字会稀释重点，写清职责、输出格式、红线即可。
以为子目录改身份：agents/review/x.md 和 agents/x.md 的身份都只看 name，子目录只是组织。

和并行 worktree 的区别与配合

subagent：在一个 Claude Code 会话内，主 agent 委派给专职子 agent，上下文隔离、返回结论。解决的是「单会话上下文污染」。
git worktree 并行 agent：在多个会话/终端，每个 agent 占一个独立工作区和分支。解决的是「多 agent 同时改代码互相打架」。

两者正交，可叠加：用 worktree 隔离文件系统让多个主 agent 并行，每个主 agent 内部再用 subagent 隔离上下文。

一句话总结

专职职责 → 写成 .claude/agents/*.md（body=系统提示，description=触发器）
        → 审查类锁只读、探索类用便宜模型 → 自动委派或 @-mention
        → 在隔离窗口干完只返结论 → 主对话保持干净

subagent 让「一个写、一个独立审」成为默认工作流，比同一 agent 自审自夸可靠得多。

名字	tools	model	description 触发条件
`code-reviewer`	Read, Glob, Grep（只读）	sonnet	写完代码后主动审查质量/安全
`debugger`	Read, Glob, Grep, Bash	sonnet	遇到报错/测试失败时定位根因
`explorer`	Read, Glob, Grep（只读）	haiku	大仓库快速只读导航，省成本
`test-writer`	Read, Glob, Grep, Edit	sonnet	为改动的模块补单元测试
`security-auditor`	Read, Glob, Grep（只读）	opus	审计敏感代码路径，要最强模型