子代理

子代理（Subagents）是专业化的 AI 助手，负责处理特定类型的任务。每个子代理拥有独立的上下文窗口、自定义系统提示和专属工具权限。当 Claude 遇到匹配子代理描述的任务时，会自动委托给该子代理处理，子代理独立完成后返回结果。

注意：子代理在单个会话中工作。如果需要多个代理并行通信，请参考官方 Agent Teams 文档。

子代理的优势

• 保护主上下文：把探索性任务和详细分析放在独立上下文中，不污染主对话
• 强制限制工具：子代理只能使用你授权的工具，更安全
• 跨项目复用：用户级子代理在所有项目中可用
• 专注特定领域：针对性的系统提示让子代理更专业
• 控制成本：把简单任务路由到 Haiku 等更快更便宜的模型

内置子代理

Claude Code 内置了几个子代理，Claude 会在合适时自动使用：

子代理	模型	用途
Explore	Haiku（快速）	只读搜索和代码库分析，不做任何修改
Plan	继承父会话	计划模式下的代码库研究
general-purpose	继承父会话	复杂多步骤任务（可读写）
Bash	继承	在独立上下文中执行终端命令
Claude Code Guide	Haiku	回答关于 Claude Code 功能的问题

快速创建子代理

方式一：使用 /agents 命令（推荐）

1. 在 Claude Code 中运行 /agents
2. 选择"Create new agent"
3. 选择"Personal"（保存到 ~/.claude/agents/，所有项目可用）
4. 选择"Generate with Claude"，描述你的需求：

一个代码改进代理，扫描文件并就可读性、性能和最佳实践提出改进建议。
它应该解释每个问题，展示当前代码，并提供改进版本。

5. 选择工具、模型、颜色，配置完成

方式二：手动创建 Markdown 文件

在 .claude/agents/（项目级）或 ~/.claude/agents/（用户级）创建 .md 文件：

---
name: code-reviewer
description: 代码审查专家。代码修改后主动审查代码质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一个高级代码审查员，确保代码质量和安全标准。

审查时：
1. 运行 git diff 查看最近改动
2. 专注于被修改的文件
3. 立即开始审查

审查清单：
- 代码清晰可读
- 函数和变量命名良好
- 没有重复代码
- 有适当的错误处理
- 没有暴露的 API key
- 有输入验证
- 测试覆盖充分

按优先级给出反馈：
- 严重问题（必须修复）
- 警告（应该修复）
- 建议（可以改进）

子代理在会话启动时加载。手动添加文件后，重启会话或使用 /agents 命令立即加载。

子代理文件格式

---
name: 子代理名称（小写字母和连字符）
description: 何时应该委托给此子代理（Claude 据此决定是否委托）
tools: Read, Grep, Glob, Bash    # 可选，逗号分隔
model: sonnet                    # 可选
---

这里是子代理的系统提示内容...

支持的 frontmatter 字段

字段	必填	说明
name	是	唯一标识符，小写字母和连字符
description	是	Claude 何时应该委托给此子代理（影响自动触发）
tools	否	允许使用的工具（白名单）。省略则继承所有工具
disallowedTools	否	禁止使用的工具（黑名单）
model	否	使用的模型：sonnet/opus/haiku/完整模型 ID/inherit。默认 inherit
permissionMode	否	权限模式：default/acceptEdits/dontAsk/bypassPermissions/plan
maxTurns	否	最大代理回合数
skills	否	预加载到子代理上下文的技能列表
mcpServers	否	仅此子代理可用的 MCP 服务器
hooks	否	子代理生命周期 hooks
memory	否	持久记忆范围：user/project/local
background	否	true 则始终作为后台任务运行
effort	否	思考深度：low/medium/high/max
isolation	否	worktree 则在独立 git worktree 中运行

作用域和优先级

位置	作用域	优先级
--agents CLI 标志	当前会话	最高（1）
.claude/agents/	当前项目	2
~/.claude/agents/	所有项目	3
插件的 agents/ 目录	插件启用处	最低（4）

同名子代理，高优先级覆盖低优先级。

项目子代理（.claude/agents/）适合提交到版本库，让团队共用。

模型选择

model: sonnet     # Sonnet 4.6（均衡）
model: haiku      # Haiku 4.5（快速省钱）
model: opus       # Opus 4.6（最强能力）
model: claude-sonnet-4-6  # 完整模型 ID
model: inherit    # 继承主会话（默认）

工具控制

白名单方式（tools）

tools: Read, Grep, Glob, Bash

只允许列出的工具，适合需要严格限制的场景。

黑名单方式（disallowedTools）

disallowedTools: Write, Edit

继承所有工具，但排除指定的。

限制可生成的子代理

---
name: coordinator
description: 协调多个专业代理
tools: Agent(worker, researcher), Read, Bash
---

这是白名单：只能生成 worker 和 researcher 子代理。不含 Agent 则完全不能生成子代理。

MCP 服务器作用域

---
name: browser-tester
description: 用真实浏览器测试功能
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github    # 引用已配置的服务器名称
---

使用 Playwright 工具浏览、截图和交互网页。

内联定义的 MCP 服务器仅对此子代理可用，不会出现在主对话中。

持久化记忆

---
name: code-reviewer
description: 代码审查专家
memory: user
---

你是代码审查员。审查时记录到记忆目录：代码库模式、反复出现的问题和架构决策。

范围	位置	使用场景
user	~/.claude/agent-memory/<name>/	跨项目通用知识
project	.claude/agent-memory/<name>/	项目特定知识（可提交 git）
local	.claude/agent-memory-local/<name>/	项目特定但不提交版本库

记忆目录的 MEMORY.md 前 200 行会自动注入子代理上下文。

在会话中使用子代理

自动触发

Claude 根据 description 字段判断何时委托。在 description 中加 "主动使用" 等描述可以提高触发概率。

显式调用

使用 code-reviewer 子代理审查最近的改动
让 debugger 子代理分析这个失败的测试

@提及（强制运行一次）

在输入框中输入 @，从自动补全选择子代理：

@"code-reviewer (agent)" 查看 auth 模块的改动

整个会话作为子代理

# CLI 方式
claude --agent code-reviewer

# 项目默认（.claude/settings.json）
{
  "agent": "code-reviewer"
}

通过 CLI 动态定义

claude --agents '{
  "code-reviewer": {
    "description": "代码审查专家，代码修改后主动审查",
    "prompt": "你是代码审查员。专注于代码质量、安全和最佳实践。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

前台 vs 后台运行

• 前台子代理：阻塞主对话直到完成，权限提示和问题会透传给你
• 后台子代理：与你并行运行；启动前 Claude Code 会一次性申请所有需要的权限

按 Ctrl+B 可将运行中的任务移到后台。

设置环境变量 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 可禁用所有后台任务。

常见模式

隔离高输出任务

用子代理运行测试套件，只报告失败的测试和错误信息

并行研究

用独立的子代理并行研究认证、数据库和 API 模块

注意：子代理完成后结果返回主对话。多个子代理并行可能消耗大量上下文。

链式子代理

用 code-reviewer 子代理找出性能问题，然后用 optimizer 子代理修复它们

恢复子代理

用 code-reviewer 子代理审查认证模块
[代理完成后]
继续那个审查，现在分析授权逻辑

已停止的子代理收到 SendMessage 会在后台自动恢复。

示例：完整子代理模板

代码审查员

---
name: code-reviewer
description: 代码审查专家。代码修改后主动审查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是高级代码审查员。

被调用时：
1. 运行 git diff 查看最近改动
2. 专注于被修改的文件
3. 立即开始审查

审查要点：
- 代码清晰易读
- 命名规范良好
- 无重复代码
- 错误处理完善
- 无泄露的密钥或 API key
- 有输入验证
- 测试覆盖充分
- 考虑性能问题

反馈格式（按优先级）：
- **严重问题**（必须修复）：附具体修复示例
- **警告**（应该修复）
- **建议**（可以改进）

调试器

---
name: debugger
description: 调试专家，处理错误、测试失败和异常行为。遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

你是根因分析专家。

被调用时：
1. 捕获错误信息和调用栈
2. 确定复现步骤
3. 定位失败位置
4. 实现最小化修复
5. 验证解决方案

调试流程：
- 分析错误信息和日志
- 检查最近的代码变更
- 提出并验证假设
- 添加关键调试日志
- 检查变量状态

每个问题提供：
- 根本原因解释
- 支持诊断的证据
- 具体代码修复方案
- 测试方法
- 预防建议

只读数据库查询

---
name: db-reader
description: 执行只读数据库查询。数据分析或报表生成时使用。
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

你是数据库分析员，只有只读权限。执行 SELECT 查询回答关于数据的问题。

禁止执行 INSERT、UPDATE、DELETE 或修改 schema 的操作。如果被要求这样做，说明你只有读取权限。

验证脚本 ./scripts/validate-readonly-query.sh：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# 阻止写入操作（大小写不敏感）
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: 不允许写入操作，请使用 SELECT 查询。" >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

何时选择子代理而非主会话

使用子代理时：

• 任务会产生大量输出，你不需要放在主上下文中
• 需要强制特定工具限制或权限
• 任务自包含，可以返回摘要
• 需要并行处理多个任务

留在主会话时：

• 任务需要频繁交互或迭代
• 多个阶段共享大量上下文
• 快速的针对性修改
• 延迟敏感（子代理需要重新建立上下文）

使用 Skills 替代时：

• 需要在主对话上下文中运行的可复用工作流

使用 /btw 替代时：

• 快速提问，答案不需要记入历史

子代理不能生成其他子代理。需要嵌套委托时，在主对话中链式调用子代理。

相关资源

• 设置：子代理配置文件位置
• 权限：工具权限语法
• Hooks：子代理 hooks 配置
• Skills：可复用工作流提示词