用途
Sub-Agents 用于在 Claude Code 中创建具有隔离上下文的专用 AI 代理,让不同任务由各自独立的代理处理,从而提升任务专注度与执行效率。
主要能力
- 创建和配置子代理,支持自定义提示词、工具和模型。
- 提供交互式、手动和 CLI 三种创建方式。
- 支持内置代理:General-purpose(Sonnet,全部工具,用于复杂多步任务)、Plan(Sonnet,只读,用于计划模式研究)、Explore(Haiku,只读,用于快速代码库搜索)。
- 支持模型选择:Haiku(最快,适合搜索和快速查找)、Sonnet(快速,适合大多数任务,默认)、Opus(较慢,适合复杂推理)。
- 支持工具组合定制,例如只读的代码审查代理、调试代理、实现代理等。
- 支持可恢复代理(通过 agentId 恢复上下文)和代理链式调用(如先用 code-analyzer 发现问题,再用 optimizer 修复)。
使用方式
交互式(推荐)
运行 /agents 打开菜单,创建、编辑和管理代理。
手动创建
mkdir -p .claude/agents
cat > .claude/agents/reviewer.md << 'EOF'
---
name: reviewer
description: Code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer focusing on quality and security.
## Review Checklist
- Code clarity and naming
- Error handling
- Security vulnerabilities
- Test coverage
EOF
CLI 方式
claude --agents '{
"reviewer": {
"description": "Code reviewer",
"prompt": "Review for quality and security",
"tools": ["Read", "Bash"],
"model": "sonnet"
}
}'
代理文件格式
---
name: agent-name
description: When/why to use this agent
tools: Read, Edit, Bash # Optional, inherits all if omitted
model: sonnet # sonnet, haiku, claude-opus-4-5-20251101, inherit
---
System prompt content here...
配置字段
| 字段 | 是否必填 | 选项 |
|---|---|---|
| name | 是 | 小写字母、连字符 |
| description | 是 | 何时使用 |
| tools | 否 | 工具列表(省略则继承全部) |
| model | 否 | sonnet、haiku、claude-opus-4-5-20251101、inherit |
工具组合示例
# Code Reviewer (read-only)
tools: Read, Grep, Glob, Bash
# Debugger
tools: Read, Edit, Bash, Grep, Glob
# Implementer
tools: Read, Write, Edit, Bash, Glob
示例代理:代码审查
---
name: code-reviewer
description: Reviews code for quality and security. Use after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---
Review code for:
- Security vulnerabilities
- Code quality issues
- Missing error handling
- Test coverage gaps
Output findings by priority: Critical > Warning > Suggestion
示例代理:调试器
---
name: debugger
description: Debug errors and test failures.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---
Debugging process:
1. Capture error details
2. Identify failure location
3. Form hypotheses
4. Test and verify
5. Implement fix
文件存放位置与优先级
| 类型 | 位置 | 优先级 |
|---|---|---|
| 项目 | .claude/agents/ | 最高 |
| 用户 | ~/.claude/agents/ | 较低 |
高级模式
可恢复代理:代理返回 agentId 后,可稍后恢复上下文继续执行。
[Agent returns agentId: "abc123"]
# Later: resume with context
claude -r "abc123" "Continue analysis"
代理链式调用:
Use code-analyzer to find issues,
then use optimizer to fix them
适用场景
- 需要为特定任务(如代码审查、调试、实现)配置专用代理。
- 希望限制代理可用工具以控制权限或行为。
- 需要为不同任务选择不同模型以平衡速度与推理能力。
- 需要多代理协作或链式处理复杂工作流。
限制
- 文档未提供关于收费、价格、平台兼容性、性能效果等方面的信息。
- 具体可用工具列表、模型完整清单及版本细节暂未提供。
- 代理数量上限、并发限制等暂未提供。