19 KiB
19 KiB
Subagents - 创建自定义子代理
来源：https://code.claude.com/docs/en/sub-agents 整理时间：2026-02-06
在 Claude Code 中创建和使用专门的 AI 子代理，用于特定任务的工作流和上下文管理。
目录
1. 概述
子代理（Subagents）是处理特定任务类型的专门 AI 助手。每个子代理运行在自己的上下文窗口中，拥有自定义系统提示、特定工具访问权限和独立权限。当 Claude 遇到匹配子代理描述的任务时，会委派给该子代理独立工作并返回结果。
子代理的核心优势
| 优势 | 说明 |
|---|---|
| 保留上下文 | 将探索和实现保持在主对话之外 |
| 强制约束 | 限制子代理可使用的工具 |
| 跨项目复用 | 通过用户级子代理在项目间共享配置 |
| 专业化行为 | 使用专注的系统提示处理特定领域 |
| 控制成本 | 将任务路由到更快、更便宜的模型（如 Haiku） |
Claude 使用每个子代理的 description 字段来决定何时委派任务。创建子代理时，编写清晰的描述让 Claude 知道何时使用它。
2. 内置子代理
Claude Code 包含以下内置子代理，会在合适时自动使用。每个子代理继承父对话的权限并添加额外的工具限制。
Explore（探索）
- 模型：Haiku（快速、低延迟）
- 工具：只读工具（拒绝 Write 和 Edit）
- 用途：文件发现、代码搜索、代码库探索
- 触发：Claude 需要搜索或理解代码库而不做修改时
- 特性：调用时指定彻底程度 ——
quick（快速定位）、medium（平衡探索）或very thorough（全面分析）
Plan（计划）
- 模型：继承主对话
- 工具：只读工具（拒绝 Write 和 Edit）
- 用途：计划模式下的代码库研究
- 触发：在计划模式中 Claude 需要理解代码库时
General-purpose（通用）
- 模型：继承主对话
- 工具：所有工具
- 用途：复杂研究、多步骤操作、代码修改
- 触发：任务需要探索和修改、复杂推理或多个依赖步骤时
其他辅助代理
| 代理 | 模型 | 使用场景 |
|---|---|---|
| Bash | 继承 | 在独立上下文中运行终端命令 |
| statusline-setup | Sonnet | 运行 /statusline 配置状态栏 |
| Claude Code Guide | Haiku | 询问 Claude Code 功能时 |
3. 快速入门：创建第一个子代理
子代理是带有 YAML frontmatter 的 Markdown 文件。可以手动创建或使用 /agents 命令。
步骤
- 打开子代理界面：运行
/agents - 创建新的用户级代理：选择 Create new agent → User-level（保存到
~/.claude/agents/，所有项目可用） - 用 Claude 生成：选择 Generate with Claude，描述子代理的功能
- 选择工具：只读审查员取消所有工具只留 Read-only tools
- 选择模型：如 Sonnet，平衡能力和速度
- 选择颜色：帮助在 UI 中识别正在运行的子代理
- 保存并试用：保存后立即可用，无需重启
使用 code-improver 代理建议改进这个项目
4. 配置子代理
4.1 使用 /agents 命令
/agents 提供交互式界面来管理子代理：查看所有可用子代理、创建新子代理、编辑配置和工具访问、删除自定义子代理。这是推荐的管理方式。
4.2 选择子代理作用域
子代理存储在不同位置，优先级不同。同名子代理高优先级胜出：
| 位置 | 作用域 | 优先级 | 创建方式 |
|---|---|---|---|
--agents CLI 标志 |
当前会话 | 1（最高） | 启动时传入 JSON |
.claude/agents/ |
当前项目 | 2 | 交互式或手动 |
~/.claude/agents/ |
所有项目 | 3 | 交互式或手动 |
插件的 agents/ 目录 |
插件启用处 | 4（最低） | 随插件安装 |
- 项目子代理 (
.claude/agents/)：特定于代码库，建议提交到版本控制供团队协作 - 用户子代理 (
~/.claude/agents/)：个人子代理，所有项目可用 - CLI 定义子代理：临时会话级别，不保存到磁盘，适合快速测试或自动化脚本
CLI 定义示例：
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'
4.3 编写子代理文件
子代理文件使用 YAML frontmatter 配置，后跟 Markdown 格式的系统提示：
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
子代理在会话启动时加载。手动添加文件后，重启会话或使用
/agents立即加载。
4.4 支持的 Frontmatter 字段
| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 唯一标识符，使用小写字母和连字符 |
description |
是 | Claude 何时应委派给此子代理 |
tools |
否 | 子代理可使用的工具。省略则继承所有工具 |
disallowedTools |
否 | 要拒绝的工具，从继承或指定列表中移除 |
model |
否 | 使用的模型：sonnet、opus、haiku 或 inherit。默认 inherit |
permissionMode |
否 | 权限模式：default、acceptEdits、dontAsk、bypassPermissions 或 plan |
skills |
否 | 启动时加载到子代理上下文的 Skills |
hooks |
否 | 作用域为此子代理的生命周期钩子 |
4.5 选择模型
- 模型别名：
sonnet、opus或haiku - inherit：使用与主对话相同的模型
- 省略：默认为
inherit
5. 控制子代理能力
5.1 可用工具
子代理可使用 Claude Code 的所有内部工具。默认继承主对话的所有工具（包括 MCP 工具）。限制工具的两种方式：
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash # 允许列表
disallowedTools: Write, Edit # 拒绝列表
---
5.2 权限模式
| 模式 | 行为 |
|---|---|
default |
标准权限检查，有提示 |
acceptEdits |
自动接受文件编辑 |
dontAsk |
自动拒绝权限提示（显式允许的工具仍可用） |
bypassPermissions |
跳过所有权限检查（谨慎使用） |
plan |
计划模式（只读探索） |
如果父级使用
bypassPermissions，此设置优先且不可覆盖。
5.3 预加载 Skills 到子代理
使用 skills 字段在启动时将 Skill 内容注入子代理上下文：
---
name: api-developer
description: Implement API endpoints following team conventions
skills:
- api-conventions
- error-handling-patterns
---
Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
Skill 的完整内容会被注入上下文，而非仅供调用。子代理不会继承父对话的 Skills，必须显式列出。
5.4 使用 Hooks 进行条件规则
对于工具使用的动态控制，使用 PreToolUse 钩子在操作执行前验证：
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
验证脚本示例（阻止 SQL 写操作）：
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2 # 退出码 2 阻止操作
fi
exit 0
5.5 禁用特定子代理
在 settings 中添加到 deny 数组，格式为 Task(subagent-name)：
{
"permissions": {
"deny": ["Task(Explore)", "Task(my-custom-agent)"]
}
}
或使用 CLI 标志：
claude --disallowedTools "Task(Explore)"
6. 为子代理定义 Hooks
6.1 子代理 Frontmatter 中的 Hooks
直接在子代理文件中定义，仅在该子代理活动时运行：
| 事件 | Matcher 输入 | 触发时机 |
|---|---|---|
PreToolUse |
工具名称 | 子代理使用工具之前 |
PostToolUse |
工具名称 | 子代理使用工具之后 |
Stop |
（无） | 子代理完成时（运行时转换为 SubagentStop） |
示例：验证 Bash 命令 + 编辑后自动运行 linter：
---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-command.sh $TOOL_INPUT"
PostToolUse:
- matcher: "Edit|Write"
hooks:
- type: command
command: "./scripts/run-linter.sh"
---
6.2 项目级子代理事件 Hooks
在 settings.json 中配置，响应主会话中的子代理生命周期事件：
| 事件 | Matcher 输入 | 触发时机 |
|---|---|---|
SubagentStart |
代理类型名称 | 子代理开始执行时 |
SubagentStop |
（无） | 任何子代理完成时 |
示例：
{
"hooks": {
"SubagentStart": [
{
"matcher": "db-agent",
"hooks": [
{ "type": "command", "command": "./scripts/setup-db-connection.sh" }
]
}
],
"SubagentStop": [
{
"hooks": [
{ "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
]
}
]
}
}
7. 使用子代理
7.1 理解自动委派
Claude 根据请求中的任务描述、子代理配置的 description 字段和当前上下文自动委派任务。
要鼓励主动委派，在描述中包含 "use proactively" 等短语。也可以明确请求特定子代理：
使用 test-runner 子代理修复失败的测试
让 code-reviewer 子代理查看我最近的更改
7.2 前台与后台运行
| 模式 | 特点 |
|---|---|
| 前台 | 阻塞主对话直到完成。权限提示和澄清问题传递给用户 |
| 后台 | 并发运行。启动前 Claude Code 提示需要的工具权限，确保预先批准。运行后自动拒绝未预先批准的操作。MCP 工具在后台子代理中不可用 |
后台子代理因权限缺失而失败时，可以在前台恢复它重试。
操作：
- 要求 Claude "在后台运行这个"
- 按 Ctrl+B 将正在运行的任务放到后台
- 设置
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1禁用所有后台任务功能
7.3 常见模式
隔离大量输出操作
将产生大量输出的操作（如测试套件、文档获取、日志处理）委派给子代理，详细输出留在子代理上下文，仅摘要返回主对话：
使用子代理运行测试套件，只报告失败的测试及其错误信息
并行研究
为独立调查生成多个同时工作的子代理：
使用单独的子代理并行研究认证、数据库和 API 模块
注意：多个子代理返回详细结果可能消耗大量上下文。
链式子代理
多步骤工作流中按顺序使用子代理：
使用 code-reviewer 子代理找出性能问题，然后使用 optimizer 子代理修复它们
7.4 选择子代理还是主对话
使用主对话：
- 任务需要频繁来回或迭代优化
- 多个阶段共享大量上下文（计划→实现→测试）
- 做快速、有针对性的更改
- 延迟敏感（子代理从头开始，可能需要时间收集上下文）
使用子代理：
- 任务产生大量不需要在主上下文中的输出
- 想强制特定工具限制或权限
- 工作是自包含的，可以返回摘要
子代理不能生成其他子代理。需要嵌套委派时，使用 Skills 或从主对话链式调用子代理。
8. 管理子代理上下文
8.1 恢复子代理
每次子代理调用创建新实例。要继续现有子代理的工作，要求 Claude 恢复它：
使用 code-reviewer 子代理审查认证模块
[代理完成]
继续该代码审查，现在分析授权逻辑
[Claude 恢复子代理，保留之前对话的完整上下文]
子代理转录存储在 ~/.claude/projects/{project}/{sessionId}/subagents/，文件名为 agent-{agentId}.jsonl。
转录持久性：
- 主对话压缩：不影响子代理转录
- 会话持久性：在同一会话内持久存在，重启 Claude Code 后可恢复
- 自动清理：根据
cleanupPeriodDays设置清理（默认 30 天）
8.2 自动压缩
子代理支持与主对话相同的自动压缩逻辑。默认在约 95% 容量时触发。设置 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 为更低百分比可提前触发（如 50）。
8.3 上下文窗口的根本限制
官方的恢复机制和自动压缩能缓解问题，但无法根本解决：
- 压缩会丢失细节：早期的发现、中间推理步骤在多轮压缩后可能完全消失
- 恢复依赖 JSONL 转录：虽然可以恢复，但重新加载的上下文仍受窗口大小限制
- 链式子代理之间信息断层：前一个子代理的完整工作过程不会传递给下一个，主对话只传递摘要
- 并行子代理各自隔离：多个子代理同时工作时，彼此不知道对方发现了什么
对于短小、专注的任务（子代理的典型用法），上下文窗口通常够用。但当子代理需要处理复杂的多步骤任务，或者多个子代理之间需要共享中间成果时，就需要额外的记忆机制。
对于需要跨子代理持久共享信息的场景，可参考 文件记忆实践指南，通过文件读写为 agent 提供简易的外部持久记忆。
9. 示例子代理
设计最佳实践
- 设计专注的子代理：每个子代理应擅长一项特定任务
- 编写详细描述：Claude 使用描述来决定何时委派
- 限制工具访问：仅授予必要权限，确保安全和专注
- 提交到版本控制：与团队共享项目子代理
9.1 代码审查员
只读子代理，审查代码但不修改。限制工具访问（无 Edit 或 Write）：
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately 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
Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.
9.2 调试器
可以分析和修复问题的子代理：
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
## Debugging Process
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Investigation approach:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations
Focus on fixing the underlying issue, not the symptoms.
9.3 数据科学家
面向数据分析的领域特定子代理：
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---
You are a data scientist specializing in SQL and BigQuery analysis.
When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly
Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations
For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data
Always ensure queries are efficient and cost-effective.
9.4 数据库查询验证器
允许 Bash 但通过 Hook 验证只允许只读 SQL 查询：
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access.
Execute SELECT queries to answer questions about the data.
When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context
You cannot modify data. If asked to INSERT, UPDATE, DELETE,
or modify schema, explain that you only have read access.
验证脚本：
#!/bin/bash
# 阻止 SQL 写操作，允许 SELECT 查询
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: Write operations not allowed. Use SELECT queries only." >&2
exit 2
fi
exit 0
chmod +x ./scripts/validate-readonly-query.sh
相关资源
- 通过插件分发子代理 — 跨团队或项目共享子代理
- 程序化运行 Claude Code — 用于 CI/CD 和自动化的 Agent SDK
- 使用 MCP 服务器 — 让子代理访问外部工具和数据
- Agent Teams — 多个 Claude Code 实例组成团队协作
- 文件记忆实践指南 — 用文件读写为 agent 提供外部持久记忆的自定义实践方案