# Claude Code 子代理使用指南

你是否遇到过这样的场景：让 Claude Code 同时审查代码和调试报错，结果上下文塞满了审查结果，调试时关键信息已被压缩丢失？或者主会话越来越慢，因为之前读取的大量文件占据了上下文？子代理正是为解决这些问题而生——它拥有独立上下文，不污染主对话，可并行处理专项任务，是复杂开发场景下的提效关键。

## 一、子代理核心概念

子代理是 Claude Code 中可独立执行专项开发任务的”细分角色”，拥有独立上下文（不污染主对话），可被主代理自动调用或用户手动触发，核心作用是拆分复杂开发任务、提升效率，同时通过权限控制保障操作安全。

主代理与子代理分工明确：主代理统筹全局、拆分任务、汇总结果；子代理专注单一专项（如代码审查、调试），独立执行并返回结果，两者协同实现“专业+高效”的开发体验。

### 1.1 Sub Agent 工作原理

Sub Agent（子代理）的工作核心是“主从协同+独立隔离”，本质是主代理通过 Task 工具 spawn 的独立 AI 实例，完整工作流程清晰可分为4步：

1. 触发阶段：主代理根据任务类型（如代码审查、调试）或用户手动命令，匹配并触发对应子代理；

2. 初始化阶段：子代理加载自身配置（工具权限、模型、系统提示），创建独立上下文窗口，与主代理上下文完全隔离，避免相互污染；

3. 执行阶段：子代理依据系统提示和任务要求，调用授权工具完成专项任务，过程中可独立进行多轮交互，无需依赖主代理干预；

4. 结果反馈阶段：子代理完成任务后，将执行结果（如审查报告、调试方案）汇总给主代理，自身上下文可按需保存或销毁，不占用主对话资源。

该机制既解决了单一会话上下文有限的问题，也实现了任务并行处理，大幅提升开发效率。

### 1.2 Sub Agent 核心价值

子代理核心是解决复杂开发任务中"效率低、专业性不足、上下文污染"三大痛点，具体体现在4个方面：

- 并行加速：多个子代理可同时执行无依赖子任务（如同时审查多模块代码、分析日志+调试报错），理论上可实现多倍吞吐量提升，避免串行处理的时间浪费；

- 专业化分工：每个子代理聚焦单一专项领域，通过配置精准匹配任务需求（如前端审查、后端调试），相比通用主代理，输出质量更高、针对性更强；

- 故障隔离：单个子代理执行失败（如调试报错、工具调用异常），不影响其他子代理或主代理正常运行，降低任务整体失败风险；

- 资源优化：可根据任务复杂度灵活选择适配模型（简单日志分析用 Haiku，复杂调试用 Opus），兼顾效率与成本，同时独立上下文避免主对话冗余。

### 1.3 子代理工作流程图

```mermaid
flowchart TD
    A[主代理接收任务] --> B{任务类型判断}
    B -->|代码审查| C[触发 Code Review 子代理]
    B -->|调试| D[触发 Debug 子代理]
    B -->|探索| E[触发 Explore 子代理]
    
    C --> F[加载专属配置]
    D --> F
    E --> F
    
    F --> G[创建独立上下文]
    G --> H[调用授权工具执行]
    H --> I[返回结果摘要]
    
    I --> J[主代理汇总结果]
```

### 1.4 Sub Agent 与 Skills 的区别

两者均为提升子代理能力的核心要素，但定位、作用完全不同，核心区别可概括为“主体与工具”的关系，具体差异如下：

|对比维度|Sub Agent（子代理）|Skills（技能）|
|---|---|---|
|定位|独立的执行主体，拥有自身配置、上下文和工具权限，是完整的 AI 助手|辅助能力模块，预定义的技能集合，无法独立执行任务，仅提供能力支撑|
|作用|统筹专项任务全流程（如代码审查：读取文件→检查问题→输出报告）|提升子代理专项能力（如配置 frontend-code-conventions，精准识别前端规范问题）|
|使用方式|可持久化配置或临时创建，支持手动/自动调用，有明确调用命令|无需独立调用，配置中添加技能名称即可自动加载，是子代理的“能力插件”|

简单总结：Skills 是子代理的“技能包”，子代理是 Skills 的“载体”，只有将 Skills 配置给子代理，才能让子代理的专项能力更精准、高效。

## 二、内置子代理（开箱即用）

理解了子代理的核心定位后，先看 Claude Code 自带了哪些子代理——无需手动配置，主代理会根据任务自动调用。

Claude Code 内置3类核心子代理及多个辅助子代理，无需手动配置，主代理会根据任务自动调用，降低使用门槛。

### 2.1 核心内置子代理

#### 2.1.1 Explore（探索代理）

只读代理，主打快速、低成本，适用于无需修改的代码探索、文件查找场景，核心信息如下：

- 模型：固定 Haiku（响应快、成本低）

- 权限：仅只读工具（Read、Grep、Glob），禁止写入操作

- 用途：文件发现、代码搜索、目录结构分析、依赖梳理

- 触发：任务仅需“查看、分析”时自动调用

#### 2.1.2 Plan（规划代理）

研究型代理，适用于项目启动、功能开发前的前置调研和方案梳理，核心信息如下：

- 模型：继承主对话模型（保证逻辑一致）

- 权限：仅只读工具，专注研究不修改

- 用途：代码库研究、需求拆解、技术方案规划

- 触发：运行 `/plan`命令、进入计划模式时自动调用

#### 2.1.3 General（通用代理）

功能最全面，适用于复杂多步骤任务，支持探索与修改结合，核心信息如下：

- 模型：继承主对话模型，可切换 Sonnet/Opus

- 权限：所有工具可用（只读、写入、Bash 等）

- 用途：跨文件开发、代码实现与调试结合、复杂多步骤任务

- 触发：任务需“探索+修改”“多工具协同”时自动调用

### 2.2 辅助内置子代理

|子代理名称|模型|核心用途|触发时机|
|---|---|---|---|
|Bash 代理|继承主对话|独立窗口执行终端命令，不污染主对话|用户执行 Bash 命令时|
|statusline-setup 代理|Sonnet|配置状态行，优化界面显示|运行 `/statusline` 命令时|
|Claude Code Guide 代理|Haiku|解答功能使用问题，提供操作指引|用户询问功能用法时|

## 三、快速创建自定义子代理

内置子代理满足通用场景，但项目专属需求（如前端规范审查、后端调试）需要自定义子代理。以下3种方式覆盖新手到进阶用户。

内置子代理仅满足通用场景，自定义子代理可精准适配项目/团队需求，以下3种方式覆盖新手到进阶用户，步骤清晰、可直接操作。

### 3.1 交互式创建（新手首选）

操作简单，无需手动编写配置，全程引导式创建，步骤如下：

1. 运行 `/agents` 命令，打开子代理管理界面；

2. 选择作用域：用户级（全局所有项目可用）或项目级（仅当前项目可用，支持团队共享）；

3. 输入子代理描述（明确角色+任务，例：“前端代码审查，只读，按严重问题/警告/建议三级输出”），Claude 自动生成基础配置；

4. 按“最小权限”原则，配置工具权限，选择适配模型（Haiku/Sonnet/Opus）；

5. 保存配置后，通过命令测试（例：`使用 code-reviewer 审查 src/Button.tsx`）。

### 3.2 手动文件创建（进阶，灵活度高）

每个子代理对应一个 Markdown 文件，包含“YAML 元数据+系统提示”，可自由定制，核心信息如下：

- 存储路径：用户级（`~/.claude/agents/`）、项目级（`.claude/agents/`）；

- YAML 元数据：配置名称、描述、工具、模型等核心参数；

- 系统提示：定义子代理角色、执行流程和输出格式。

简化示例（前端代码审查子代理）：

```markdown
---
name: code-reviewer
description: 前端代码审查，只读，按严重问题/警告/建议输出，重点检查 React 规范和 TypeScript 类型。
tools: Read,Grep,Glob
model: sonnet
permissionMode: dontAsk
---
# 系统提示
你是前端代码审查员，仅只读审查，重点检查代码规范、类型定义和安全漏洞，按三级分类输出问题及修复方案。

```

### 3.3 CLI 临时创建（临时测试，不持久化）

无需持久化配置，启动 Claude Code 时传递 `--agents` 参数即可创建，仅当前会话有效，适合快速测试配置，示例如下：

```bash
claude --agents '{
  "temp-log-analyzer": {
    "name": "temp-log-analyzer",
    "description": "临时分析日志，提取错误和性能瓶颈",
    "tools": ["Read", "Grep"],
    "model": "haiku",
    "prompt": "分析日志，按类型统计错误，输出简单分析报告"
  }
}'
```

## 四、子代理作用域与优先级

创建自定义子代理时，放在哪里决定了谁可以使用——作用域与优先级规则避免配置冲突。

子代理按作用域分为4类，优先级从高到低排列，同名子代理高优先级覆盖低优先级，避免配置冲突，具体如下表：

|作用域|适用范围|存储/创建方式|典型场景|
|---|---|---|---|
|CLI --agents 参数|仅当前会话|启动参数传递，不存入磁盘|临时测试、短期专项任务|
|项目级|仅当前项目|.claude/agents/，可提交 Git 共享|团队共享、项目专属规范|
|用户级|所有项目|~/.claude/agents/，全局存储|个人常用、通用任务|
|插件自带|启用插件的项目|插件自带目录，无需手动配置|插件专属专项任务|

## 五、核心配置项详解

明确了作用域，接下来看配置文件中的具体字段——哪些必选、哪些按需，避免过度配置。

子代理配置分为必选和可选字段，核心配置决定其行为和权限，无需冗余配置，按需选择即可，清晰分类如下：

### 5.1 必选字段（缺一不可）

- name：子代理唯一标识，建议用“小写+横杠”（例：code-reviewer），避免同名冲突；

- description：明确角色+任务+触发场景，是主代理自动调用的核心依据（例：“前端代码审查，用户修改代码后自动调用”）。

### 5.2 常用可选字段（高频配置）

- tools/disallowedTools：工具白名单/黑名单，遵循“最小权限”原则（例：审查代理仅配置 Read、Grep）；

- model：选择适配模型（Haiku：快/低成本；Sonnet：平衡；Opus：高精度；inherit：继承主模型）；

- permissionMode：权限模式（default：需用户批准；acceptEdits：自动接受编辑；dontAsk：只读；plan：规划模式）；

- skills：预加载技能，提升任务效率（例：api-conventions、react-debugging）。

### 5.3 进阶可选字段（按需使用）

- contextTTL：上下文存活时间（单位：分钟），短期任务设短，长期任务设长；

- maxTokens：最大令牌限制，避免成本失控；

- hooks：生命周期钩子，用于日志、通知等增强功能（新手可暂不配置）。

## 六、子代理高级能力

掌握基础配置后，以下高级能力可进一步提升开发效率——主代理与子代理的协同模式、手动调用与参数传递、上下文管理。

掌握基础用法后，可通过子代理的高级能力进一步提升开发效率，适配复杂场景，核心能力如下：

### 6.1 主代理与子代理协同

协同核心是“任务拆分与结果汇总”，分为两种模式，适配不同场景：

- 链式协同（串行）：多个子代理按顺序执行，前一个子代理的结果作为后一个的输入（例：规划→开发→审查→测试）；

- 并行协同：多个子代理同时执行不同子任务（例：同时审查代码、分析日志、性能测试），大幅提升效率。

### 6.2 手动调用与参数传递

除主代理自动调用外，用户可手动调用子代理，还可临时传递参数修改配置，灵活适配临时需求：

手动调用格式：`/agent [子代理名称] [任务描述]`

参数传递示例：

```bash
# 临时切换模型，加快审查速度
/agent code-reviewer 审查 src/Input.tsx --model=haiku
# 临时禁用编辑权限，仅定位报错
/agent debugger 定位报错 --permissionMode=dontAsk
```

### 6.3 上下文管理与权限管控

- 上下文管理：可查看、保存、恢复子代理上下文，便于追溯执行记录、继续未完成任务；

- 权限管控：可细分工具操作路径（例：仅允许读取 src 目录），启用审计日志，保障企业级使用安全。

## 七、实战场景（可直接复用）

以下场景覆盖高频开发需求，配置精简、可直接修改使用，聚焦实用，无需额外调整：

### 7.1 前端代码审查（团队共享，项目级）

```markdown
---
name: frontend-code-reviewer
description: 团队前端审查，只读，按严重问题/警告/建议输出，聚焦 React/TypeScript 规范，提交代码后自动调用。
tools: Read,Grep,Glob
model: sonnet
permissionMode: dontAsk
skills: [frontend-code-conventions, typescript-type-check]
tags: [frontend, code-review, team-shared]
---
# 系统提示
仅只读审查 src 目录下前端文件，重点检查组件命名、类型定义、安全漏洞和可读性，按三级分类输出问题、代码示例和修复方案，格式标准化。

```

调用命令：`/agent frontend-code-reviewer 审查 src/pages/Home.tsx`

### 7.2 后端报错调试（个人常用，用户级）

交互式创建描述：“个人 Node.js 调试代理，可编辑、执行 Bash，定位报错根因，给出修复方案并验证，遇到后端报错自动调用。”

核心配置：tools: Read,Edit,Grep,Bash；model: opus；permissionMode: acceptEdits

调用方式：直接输入报错信息，或 `/agent nodejs-debugger 调试报错："Cannot find module 'express'"`

### 7.3 临时日志分析（CLI 临时代理）

```bash
claude --agents '{
  "temp-log-analyzer": {
    "name": "temp-log-analyzer",
    "description": "临时分析日志，提取错误和慢请求，输出简单报告",
    "tools": ["Read", "Grep"],
    "model": "haiku",
    "permissionMode": "dontAsk",
    "prompt": "分析指定日志，统计错误类型和出现次数，推测根因，给出优化建议"
  }
}'
```

调用命令：`/agent temp-log-analyzer 分析 ./logs/app.log`



## 八、总结

子代理的核心价值是"独立上下文+专项分工"——通过隔离执行环境避免主会话污染，通过专业化配置提升输出质量，通过并行处理加速任务完成。建议从团队共享的代码审查子代理入手，熟悉配置规则后，再尝试创建调试、安全审查等专项子代理；复杂任务可采用链式协同或并行协同模式，最大化提升效率。



你是否遇到过这样的场景：让 Claude Code 同时审查代码和调试报错，结果上下文塞满了审查结果，调试时关键信息已被压缩丢失？或者主会话越来越慢，因为之前读取的大量文件占据了上下文？子代理正是为解决这些问题而生——它拥有独立上下文，不污染主对话，可并行处理专项任务，是复杂开发场景下的提效关键。

搞懂这 5 个子代理核心玩法，Claude Code 开发效率翻 3 倍，90% 的开发者都浪费了

Claude Code 子代理实战指南：从内置代理到自定义配置，掌握独立上下文、并行处理、Skills 协同等核心玩法，提升开发效率

开发专家

开发工具

编程语言

架构设计

ClaudeCode子代理是解决复杂开发任务中效率低、上下文污染等痛点的关键工具。它拥有独立上下文，不干扰主对话，可并行处理专项任务如代码审查、调试报错等。通过主代理拆分任务、子代理专注执行，实现高效协同。支持自定义配置，适配前端规范审查、后端调试等场景，提升开发效率与代码质量。操作简单，新手可交互式创建，进阶用户支持手动配置和CLI临时调用。

日志分析

性能测试

TypeScript

ES特惠专场，新客首购1折起！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

ClaudeCode子代理是解决复杂开发任务中效率低、上下文污染等痛点的关键工具。它拥有独立上下文，不干扰主对话，可并行处理专项任务如代码审查、调试报错等。通过主代理拆分任务、子代理专注执行，实现高效协同。支持自定义配置，适配前端规范审查、后端调试等场景，提升开发效率与代码质量。操作简单，新手可交互式创建，进阶用户支持...

搞懂这 5 个子代理核心玩法，Claude Code 开发效率翻 3 倍，90% 的开发者都浪费了-腾讯云开发者社区-腾讯云

搞懂这 5 个子代理核心玩法，Claude Code 开发效率翻 3 倍，90% 的开发者都浪费了

搞懂这 5 个子代理核心玩法，Claude Code 开发效率翻 3 倍，90% 的开发者都浪费了

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐