Appearance
Claude Code Subagents实践指南：从入门到精通
子代理 = 一个专门角色 + 独立上下文 + 受限工具
一、Subagents是什么？
核心概念：Subagent 是 Claude Code 的专用 AI 助手——在独立的上下文窗口中运行，使用你定义的 system prompt 和受限工具集，完成任务后只返回摘要给主对话。
与其他扩展机制的区别
| 特性 | Subagents | Skills | CLAUDE.md | Hooks |
|---|---|---|---|---|
| 上下文 | 独立窗口 | 主对话内 | 主对话内 | 不占用 |
| 通信 | 只返回摘要 | 共享上下文 | 共享上下文 | 无 |
| 适合场景 | 隔离任务/领域专家 | 可重用工作流 | 始终需要的规则 | 自动化副作用 |
二、五分钟创建第一个 Subagent
方法A：通过 /agents 命令
bash
/agents- 切换到 Library 标签 → Create new agent → Personal
- 选择 Generate with Claude，输入描述
- 配置工具（Read-only tools）、模型（Sonnet）、颜色
- 按 s 保存
方法B：手动创建 .md 文件
创建 .claude/agents/code-reviewer.md：
yaml
---
name: code-reviewer
description: Expert code reviewer. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Provide feedback organized by priority: Critical → Warnings → Suggestions.三、16个 Frontmatter 字段速查
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✅ | 唯一标识符 |
| description | ✅ | 触发决策依据 |
| tools | ❌ | 允许工具白名单 |
| disallowedTools | ❌ | 拒绝工具黑名单 |
| model | ❌ | 使用的模型 |
| permissionMode | ❌ | 权限模式 |
| maxTurns | ❌ | 最大轮数 |
| memory | ❌ | 持久记忆范围 |
| background | ❌ | 后台运行 |
| isolation | ❌ | worktree隔离 |
| effort | ❌ | 努力程度 |
四、4种调用方式
| 方式 | 语法 | 保证执行 |
|---|---|---|
| 自动委派 | 自然语言描述 | 否 |
| @-mention | @agent-name 任务 | 是 |
| --agent标志 | claude --agent name | 是 |
| settings.json | "agent": "name" | 是 |
五、8个高频场景
场景1：隔离大量输出
测试套件、日志分析产生大量输出，放在主对话会消耗上下文。
yaml
tools: Bash
model: haiku场景2：并行独立研究
多个 subagent 同时探索不同方向。
Research the authentication, database, and API modules in parallel场景3：只读代码审查
yaml
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit场景4：领域专家
yaml
model: sonnet
memory: project场景5：worktree隔离
yaml
isolation: worktree场景6：模型成本路由
| 任务类型 | 推荐模型 |
|---|---|
| 文件搜索 | haiku |
| 代码审查 | sonnet |
| 架构分析 | opus |
六、实战示例
示例：code-reviewer
yaml
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer.
Review checklist:
- Code is clear and readable
- No duplicated code
- Proper error handling
- No exposed secrets
- Good test coverage
Provide feedback: Critical → Warnings → Suggestions示例：debugger
yaml
---
name: debugger
description: Debugging specialist for errors and test failures.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
maxTurns: 20
---
You are an expert debugger. Focus on fixing the underlying issue, not the symptoms.七、Agent Teams（实验性）
Agent Teams 让多个 Claude Code 实例作为团队协作。
启用方式
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}使用场景
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security
- One checking performance
- One validating test coverage最佳实践
- 团队规模：3-5 teammates
- 任务粒度：每个 teammate 约 5-6 个任务
- 避免文件冲突：确保每个 teammate 拥有不同文件集
八、故障排查
| 问题 | 解决方案 |
|---|---|
| Subagent 不触发 | 检查 description 写法 |
| 工具权限报错 | 检查 tools/disallowedTools 冲突 |
| memory 没有持久化 | prompt 中要求主动写入 |
总结
| 核心概念 | 说明 |
|---|---|
| 独立上下文 | 不污染主对话 |
| 受限工具 | 权限硬约束 |
| 只返回摘要 | 精简高效 |
Subagents 是唯一能隔离上下文的扩展机制。
关键词：Claude Code Subagents, 子代理, Agent Teams, frontmatter配置, code-reviewer
