Claude Code 子代理 – 自学教程

简介

子代理（Subagents）是 Claude Code 的任务拆分能力，用于把大型复杂任务拆解成多个独立的专项小代理，每个子代理专注单一职责，并行或串行执行任务。
当项目任务庞大（大型重构、多模块开发、全量代码审计），单一 Claude 会话容易上下文超限、注意力分散，此时就适合使用子代理。
子代理定义文件统一放置在 .claude/subagents/ 目录。

核心概念

主代理：顶层 Claude Code 会话，负责任务规划、分发工作、汇总所有子代理结果、整合输出。
子代理：独立的小型代理实例，拥有自己的上下文、权限、指令，只负责分配到的专项工作。
隔离性：子代理之间上下文互相隔离；子代理默认继承项目基础配置（CLAUDE.md、.claude/ignore），但可以单独配置专属指令与权限。

前置条件

Claude Code CLI / IDE插件已安装
项目已存在 .claude 目录
在 .claude/subagents/ 目录新建子代理定义文件（Markdown格式）

子代理定义文件写法

文件路径：.claude/subagents/agent-name.md
文件名就是子代理名称，调用时直接使用该名称。

示例 .claude/subagents/lint-reviewer.md

# 子代理：lint-reviewer
职责：代码静态检查，检查代码规范、TypeScript类型错误、ESLint警告
权限：只读src目录，禁止修改任何文件
输出要求：
1. 列出所有问题文件与行号
2. 给出简短修复建议
3. 不直接修改代码，仅输出报告

示例 .claude/subagents/api-designer.md

# 子代理：api-designer
职责：设计后端接口、定义请求/响应TS类型
权限：可读src/api目录，允许修改类型定义文件
约束：必须遵循项目CLAUDE.md内的编码规范

调用子代理

在主会话对话中直接调用，语法示例：

调用子代理 lint-reviewer，检查src目录代码规范问题

调用子代理 api-designer，为用户模块新增分页查询接口类型定义

主代理会自动唤起对应子代理，分配任务，等待子代理完成，最后汇总子代理返回结果。

子代理配置项

子代理md文件内可配置：

职责描述：子代理目标，明确能做什么、不做什么
权限范围：读写/只读目录、是否允许执行终端命令
专属指令：独立编码规则、输出格式要求
资源限制：上下文约束，任务边界

权限优先级：子代理自身权限规则，不能高于项目 .claude/rules 全局权限限制。项目rules是底线。

使用场景

✅ 推荐使用子代理场景

大型项目重构，拆分为：代码审计、接口设计、组件开发、测试编写多个子代理
代码审查：独立子代理专门做静态检查、漏洞扫描
多模块并行任务：一个子代理处理前端，一个处理后端类型
分离“方案设计”和“代码实现”，减少单一会话上下文压力

❌ 不推荐

简单小功能、单行bug修复，没必要启用子代理，增加开销
极短一次性任务，直接在主会话完成

子代理生命周期

主代理收到需求，判断是否需要子代理
加载 .claude/subagents/ 对应的子代理定义
启动子代理实例，分配任务，传入指定文件上下文
子代理独立执行任务，生成结果返回主代理
主代理汇总全部结果，生成最终方案或代码变更
子代理会话销毁，不污染主代理上下文

常用斜杠命令

/subagent list       # 列出所有已定义子代理
/subagent reload     # 重新加载子代理配置（修改子代理md文件后使用）

最佳实践

子代理职责单一，一个子代理只负责一类工作，避免职责臃肿
子代理尽量设置最小权限：代码审计类子代理设置只读权限
子代理输出标准化报告，方便主代理汇总
子代理数量不宜过多，避免任务拆分过度、管理复杂
子代理定义文件提交Git，团队共享

常见问题

修改子代理md文件，调用没有生效
执行 /subagent reload，或者 /clear 新建会话加载配置。
子代理尝试修改禁止的文件
检查 .claude/rules 项目权限，项目全局规则优先级高于子代理配置。
子代理看不到项目CLAUDE.md规范
子代理默认继承项目CLAUDE.md；可在子代理定义内补充专属约束。

安全提示

子代理依然会读取项目代码，敏感文件必须在 .claude/ignore 屏蔽
给子代理设置最小权限原则：只开放任务必需的目录权限
生产项目，子代理执行文件修改/终端命令，依然会遵循当前会话交互模式（Manual模式下需要审批）

简介