在使用 Claude Code 编程工作中,你是否遇到过以下这些问题?
- 代码审查时需要反复切换上下文
- 复杂任务产生大量输出,占用了大量上下文
- 希望某些 skill agent 只能读取而不能修改代码
- 想要在多个项目中复用相同的工作流程
Sub Agent(子代理) 正是为解决这些问题而生。它让你能够创建专门处理特定任务的 AI 助手,每个子代理都有独立的上下文、工具权限和系统提示。
什么是 Sub Agent?
Sub Agent 是运行在独立上下文窗口中的专业化 AI 助手。当 Claude 遇到匹配子代理描述的任务时,会自动委托给该子代理处理,完成后返回结果。
核心优势
| 优势 | 说明 |
|---|---|
| 保留上下文 | 探索和实现工作与主对话分离 |
| 强制约束 | 限制子代理可使用的工具 |
| 跨项目复用 | 用户级子代理可在所有项目中使用 |
| 专业化行为 | 针对特定领域使用专注的系统提示 |
| 控制成本 | 将任务路由到更快、更便宜的模型(如 Haiku) |
内置子代理
Claude Code 官方也内置了一些子代理,按需调用。
| 子代理 | 模型 | 用途 |
|---|---|---|
| Explore | Haiku | 只读代理,用于搜索和分析代码库 |
| Plan | 继承主对话 | 在计划模式下收集上下文 |
| general-purpose | 继承主对话 | 处理复杂的多步骤任务,可读写 |
| Bash | 继承主对话 | 在独立上下文中运行终端命令 |
| statusline-setup | Sonnet | 配置状态栏时使用 |
| Claude Code Guide | Haiku | 回答关于 Claude Code 功能的问题 |
快速上手:创建你的第一个子代理
创建子代理的方式有两种,一种是自动,一种是手动。让我们尝试自动创建一个代码审查子代理,它可以扫描指定的文件并提出改进建议。
步骤 1:执行子代理命令
/agents
步骤 2:创建用户级代理
由于代码审子代理一般是通用的,所以我们这里选择 Create new agent → Personal (~/.claude/agents/)
这样子创建的子代理就会保存到 ~/.claude/agents/,使其在所有项目中可用。
步骤 3:使用 Claude 生成
选择 Generate with Claude (recommended),输入描述:
一款代码优化智能代理,可扫描文件并针对代码可读性、性能与最佳实践提出改进建议。它会说明每个问题、展示当前代码,并提供优化后的版本。
步骤 4:配置工具和模型
我们可以配置子代理需要用到的一些工具,因为我们这里只是用来审核代码,所以只需要勾选 Read-only tools,模型根据子代理的功能,选择比较便宜的 Sonnet,最后随意选择你喜欢的颜色方便识别。
注意:模型根据 sub agent 的复杂度选择,效果最佳,当然你有钱就选择 opus。
步骤 5:保存并测试
使用代码审查这个文件, @packages/front/src/lib/utils.ts
如果出现这种带颜色的指令,则就代表调用 sub agent 成功。
手动创建子代理文件
我们也可以手动来创建子代理,子代理文件使用 YAML frontmatter + Markdown 格式,存放位置有以下两种:
~/.claude/agents/- 用户级别(所有项目可用).claude/agents/- 项目级别(当前项目可用)
---name: code-reviewerdescription: Reviews code for quality and best practicestools: Read, Glob, Grepmodel: sonnet---You are a code reviewer. When invoked, analyze the code and providespecific, actionable feedback on quality, security, and best practices.
当然也可以用 CLI 的方式来创建,不过就是不太好编辑,如果你喜欢用也可以。
claude --agents '{"code-reviewer": {"description": "...", "prompt": "...", "tools": ["Read"]}}'
实战案例
案例 1:代码审查员
---name: code-reviewerdescription: Expert code review specialist. Use immediately after writing or modifying code.tools: Read, Grep, Glob, Bashmodel: inherit---You are a senior code reviewer ensuring high standards of code quality and security. When invoked:1. Run git diff to see recent changes2. Focus on modified files3. Begin review immediately Review checklist:- Code is clear and readable- No exposed secrets or API keys- Proper error handling- Good test coverage Provide feedback organized by priority:- Critical issues (must fix)- Warnings (should fix)- Suggestions (consider improving)
案例 2:调试专家
---name: debuggerdescription: Debugging specialist for errors and test failures.tools: Read, Edit, Bash, Grep, Glob---You are an expert debugger specializing in root cause analysis. When invoked:1. Capture error message and stack trace2. Identify reproduction steps3. Isolate the failure location4. Implement minimal fix5. Verify solution works Focus on fixing the underlying issue, not the symptoms.
案例 3:只读数据库查询器
使用 Hook 限制只允许 SELECT 查询:
---name: db-readerdescription: Execute read-only database queries.tools: Bashhooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh"---You are a database analyst with read-only access.
验证脚本 validate-readonly-query.sh:
#!/bin/bashINPUT=$(cat)COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty') if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP)\b' > /dev/null; then echo "Blocked: Only SELECT queries are allowed" >&2 exit 2fi exit 0
高级功能
持久记忆
让子代理跨会话积累知识:
---name: code-reviewerdescription: Reviews code for quality and best practicesmemory: user---As you review code, update your agent memory with patterns,conventions, and recurring issues you discover.
记忆范围:
user:跨所有项目记忆project:项目特定,可提交到版本控制local:项目特定,不提交到版本控制
前台与后台运行
- 前台:阻塞主对话,可交互
- 后台:并发运行,按
Ctrl+B可将任务转到后台
并行研究
Research the authentication, database, and API modules in parallel using separate subagents
链式调用
Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them
最佳实践
设计专注的子代理
为每个子代理分配单一、明确、高度聚焦的任务职责,避免功能交叉与职责模糊,让子代理能够专注完成特定领域工作,提升执行精准度与效率。
编写详细描述
为每个子代理撰写清晰、完整、可被 Claude 准确理解的功能描述与使用场景,明确其能力边界、适用任务与触发条件,使 Claude 能自动判断何时需要委托任务、调用对应子代理。
限制工具访问
遵循最小权限原则,仅为子代理授予完成任务所必需的工具、文件、命令与接口访问权限,严格禁止多余权限,保障项目安全、避免误操作与数据风险。
提交到版本控制
将所有子代理的配置、描述文件与规则统一纳入 Git 等版本控制系统管理,实现版本追踪、协作修改与安全共享,让团队成员可统一使用、维护与迭代项目子代理。
何时使用子代理 vs 主对话
| 使用主对话 | 使用子代理 |
|---|---|
| 需要频繁来回交互 | 任务产生大量输出 |
| 多个阶段共享上下文 | 需要强制工具限制 |
| 快速、针对性的修改 | 工作是独立的,可返回摘要 |
总结
Sub Agent 是 Claude Code 中强大的功能,它让你能够:
- 创建专业化的 AI 助手团队
- 保持主对话上下文清洁
- 强制执行安全约束
- 跨项目复用工作流程
现在就试试创建你的第一个子代理吧!
/agents
评论