在使用 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 agentPersonal (~/.claude/agents/)

用户级代理
用户级代理

这样子创建的子代理就会保存到 ~/.claude/agents/,使其在所有项目中可用。

步骤 3:使用 Claude 生成

选择 Generate with Claude (recommended),输入描述:

一款代码优化智能代理,可扫描文件并针对代码可读性、性能与最佳实践提出改进建议。它会说明每个问题、展示当前代码,并提供优化后的版本。
Generate with Claude
Generate with Claude

步骤 4:配置工具和模型

我们可以配置子代理需要用到的一些工具,因为我们这里只是用来审核代码,所以只需要勾选 Read-only tools,模型根据子代理的功能,选择比较便宜的 Sonnet,最后随意选择你喜欢的颜色方便识别。

注意:模型根据 sub agent 的复杂度选择,效果最佳,当然你有钱就选择 opus。

Read-only tools
Read-only tools

步骤 5:保存并测试

使用代码审查这个文件, @packages/front/src/lib/utils.ts

如果出现这种带颜色的指令,则就代表调用 sub agent 成功。

sub agent 成功
sub agent 成功

手动创建子代理文件

我们也可以手动来创建子代理,子代理文件使用 YAML frontmatter + Markdown 格式,存放位置有以下两种:

  • ~/.claude/agents/ - 用户级别(所有项目可用)
  • .claude/agents/ - 项目级别(当前项目可用)
---
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.

当然也可以用 CLI 的方式来创建,不过就是不太好编辑,如果你喜欢用也可以。

claude --agents '{"code-reviewer": {"description": "...", "prompt": "...", "tools": ["Read"]}}'

实战案例

案例 1:代码审查员

---
name: code-reviewer
description: Expert code review specialist. 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
- 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: debugger
description: 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 trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
 
Focus on fixing the underlying issue, not the symptoms.

案例 3:只读数据库查询器

使用 Hook 限制只允许 SELECT 查询:

---
name: db-reader
description: Execute read-only database queries.
tools: Bash
hooks:
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/bash
INPUT=$(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 2
fi
 
exit 0

高级功能

持久记忆

让子代理跨会话积累知识:

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: 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