Claude Code 入门实战 5：子代理（Subagent）使用指南

sensen111111

1644人浏览 · 2026-03-12 14:15:29

sensen111111 · 2026-03-12 14:15:29 发布

前言

子代理（Subagent）是 Claude Code 中一项强大的高级特性。它允许你将特定类型的任务委派给运行在独立上下文中的专用 AI 助手，从而实现更好的上下文隔离、更精确的行为约束和更高效的任务执行。

本文将从概念、配置、实战到优化，系统讲解子代理的使用方法，帮助你充分利用这一特性来提升开发效率。

1. 什么是子代理？

子代理本质上是一个拥有独立上下文窗口的专用 AI 实例。当你在 Claude Code 主对话中下达任务时，Claude 可以判断该任务是否适合委派给某个子代理，由子代理独立完成后将结果摘要返回主对话。

每个子代理拥有：

独立的系统提示词 — 定义子代理的角色、行为和工作流程
独立的上下文窗口 — 与主对话隔离，不会互相污染
指定的模型 — 可以选择 Haiku / Sonnet / Opus，或继承主对话
受限的工具权限 — 可精确控制子代理能使用哪些工具
独立的权限模式 — 控制操作确认的行为
生命周期钩子 — 在特定时机触发自定义脚本

2. 为什么需要子代理？

痛点	子代理如何解决
探索性任务消耗大量上下文	子代理在独立上下文中完成，只有摘要返回主对话
需要严格约束某类操作（如只读审查）	通过 `tools` 字段限制子代理只能使用只读工具
团队中不同角色需要不同 AI 行为	为每种角色创建专用子代理，各有专属提示词
简单任务不想消耗昂贵的 Opus 额度	将简单任务路由到 Haiku，复杂任务才用 Sonnet/Opus
某些规范 Claude 总是犯错	在子代理提示词中写死约束，比口头提醒更可靠

一句话总结：子代理 = 职责明确、权限受限、上下文隔离的专用 AI 助手。

3. 子代理运行机制

3.1 生命周期

一个子代理从创建到结束，经历以下阶段：

任务匹配 → 实例创建 → 独立执行 → 结果回传 → 实例销毁

任务匹配：当你在主对话中提出请求时，Claude 会将请求内容与所有已注册子代理的 description 字段进行语义匹配。你也可以在对话中显式指定子代理名称来跳过匹配过程。
实例创建：匹配成功后，Claude Code 为该子代理创建一个全新的 AI 实例，拥有独立的上下文窗口，加载子代理配置中定义的系统提示词，并按照 tools 字段初始化工具权限。
独立执行：子代理在自己的上下文窗口中自主工作，可以调用被授权的工具（读取文件、执行命令、编辑代码等），直到完成任务。
结果回传：子代理完成任务后，将工作成果以摘要形式返回主对话（精炼后的结论和关键信息，而非全部中间步骤）。
实例销毁：结果回传后，子代理实例即被释放。下次调用时会创建一个全新的实例。

3.2 上下文隔离模型

┌──────────────────────────────────────────────┐
│                   主对话                     │
│  上下文窗口：保留完整的用户对话历史            │
│                                              │
│  用户："审查 src/auth 模块的代码质量"          │
│                  ↓ 任务委派                   │
│  ┌───────────────────────────────────────┐   │
│  │          子代理：code-reviewer        │    │
│  │  独立上下文窗口（与主对话完全隔离）     │    │
│  │                                       │    │
│  │  系统提示词 → 工具调用 → 多轮推理       │    │
│  │  Read(auth.ts) → Grep(漏洞模式) → ...  │    │
│  │  ↓                                    │    │
│  │  生成审查报告                          │    │
│  └──────────────┬────────────────────────┘    │
│                 ↓ 仅返回摘要                   │
│  Claude："审查完成，发现 3 个问题：……"          │
└────────────────────────────────────────────────┘

这种隔离模型带来三个关键好处：

上下文保护：子代理的中间数据全部留在子代理上下文中，不会挤占主对话的 Token 预算。
行为可控：子代理只能看到自己的系统提示词和被授权的工具，不受主对话中其他无关信息干扰。
故障隔离：即使子代理执行出错或超时，也不会破坏主对话的状态。

3.3 与主对话的协作方式

通道	方向	说明
任务指令	主对话 → 子代理	主对话将任务描述和必要的上下文传递给子代理
结果摘要	子代理 → 主对话	子代理将工作成果以精炼摘要的形式返回
文件系统	双向共享	子代理对文件的读写操作会直接作用于项目的真实文件系统（除非使用 `isolation: worktree`）
权限确认	子代理 → 用户	前台子代理执行敏感操作时，权限确认提示会正常弹出给用户

注意：子代理对文件系统的修改是即时生效的。如果需要连文件系统也隔离，可以使用 isolation: worktree 让子代理在独立的 git worktree 中工作。

4. 内置子代理

Claude Code 已经内置了多种子代理，在日常使用中会自动调用，无需手动配置。

子代理	模型	工具权限	用途	自动触发场景
Explore	Haiku	只读（禁止 Write/Edit）	文件搜索、代码结构分析、定义查找	需要阅读代码但不修改时
Plan	继承主对话	只读（禁止 Write/Edit）	Plan Mode 下的项目调研	进入 Plan Mode 后
General-purpose	继承主对话	全部工具	复杂的多步骤研究与修改	需要综合分析 + 代码修改时
Bash	继承主对话	终端命令	在独立上下文中执行命令	需要运行 shell 命令时
Claude Code Guide	Haiku	只读	回答 Claude Code 使用问题	咨询 Claude Code 功能时

其中 Explore 子代理支持三种探索深度：

quick — 快速定向查找，适合已知目标
medium — 平衡探索，适合一般性搜索
very thorough — 全面分析，适合复杂的跨模块调研

5. 创建自定义子代理

5.1 方式1：使用 `/agents` 命令（推荐）

/agents 提供交互式界面，是创建和管理子代理最便捷的方式：

> /agents

进入后可以：

查看所有子代理（内置、用户级、项目级）
创建新子代理（支持 Claude 自动生成或手动编写）
编辑已有子代理
删除自定义子代理

创建流程：

运行 /agents → 选择 Create new agent
选择作用域（User-level 全局可用 / Project-level 仅当前项目）
选择 Generate with Claude，输入需求描述，例如：

一个代码审查代理，扫描最近的代码变更，
从可读性、安全性、性能三个角度给出改进建议，
并附上修改示例。

Claude 自动生成系统提示词和初始配置
按 e 可手动编辑，按回车确认
选择工具权限（只读 / 可写 / 全部）
选择模型（Haiku / Sonnet / Opus）
保存 — 立即生效，无需重启会话

5.2 方式2：手动创建文件

子代理配置文件是带 YAML 前置元数据的 Markdown 文件，放在指定目录即可生效：

# 创建项目级子代理（仅当前项目可用，可提交到 Git 共享给团队）
mkdir -p .claude/agents

# 创建用户级子代理（所有项目可用）
mkdir -p ~/.claude/agents

然后在目录中创建 .md 文件，例如 .claude/agents/code-reviewer.md。

注意：手动创建的文件需要重启会话或运行 /agents 才能被加载。

5.3 方式3：CLI 参数传入（临时使用）

适合临时测试或在自动化脚本中使用：

claude --agents '{
  "code-reviewer": {
    "description": "代码质量与安全审查专家。在代码变更后主动使用。",
    "prompt": "你是一名资深代码审查工程师...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

6. 配置文件详解

6.1 基本结构

---
name: code-reviewer
description: 代码质量审查专家。在编写或修改代码后主动使用，检查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名资深代码审查工程师。

被调用时：
1. 运行 git diff 查看最近的代码变更
2. 聚焦已修改的文件
3. 按优先级反馈问题：严重 → 警告 → 建议

--- 之间是 YAML 前置元数据（配置部分），--- 之后是系统提示词（行为定义）。

6.2 完整字段说明

字段	必填	类型	说明
`name`	是	string	唯一标识符，使用小写字母和连字符（如 `code-reviewer`）
`description`	是	string	关键字段：描述子代理的用途，Claude 据此决定是否委派任务
`tools`	否	string/list	允许使用的工具列表，省略则继承所有工具
`disallowedTools`	否	string/list	明确禁止的工具
`model`	否	string	使用的模型：`haiku` / `sonnet` / `opus` / `inherit`（默认 inherit）
`permissionMode`	否	string	权限模式（见下文）
`maxTurns`	否	number	子代理最大交互轮次
`skills`	否	list	启动时预加载的技能列表
`mcpServers`	否	list	可用的 MCP 服务器
`hooks`	否	object	生命周期钩子配置
`memory`	否	string	持久化记忆范围：`user` / `project` / `local`
`background`	否	boolean	设为 `true` 则始终在后台运行
`isolation`	否	string	设为 `worktree` 则在独立 git worktree 中运行

6.3 `description` 字段：自动委派的关键

Claude 决定是否将任务委派给子代理，主要依据 description 字段。编写技巧：

# 好的写法：明确、具体，包含主动触发词
description: "代码审查专家。在编写或修改代码后主动使用（proactively）。分析代码质量、安全性和可维护性。"

# 差的写法：模糊、宽泛
description: "一个帮助处理代码的助手。"

关键词：在 description 中使用 主动使用、proactively、immediately、must use when 等词汇，可以提高子代理被自动调用的概率。

你也可以在对话中显式调用：

> 使用 code-reviewer 子代理检查最近的提交
> 让 security-auditor 审计 src/auth 目录

6.4 工具权限配置

允许列表（推荐，最安全）

明确列出允许使用的工具，未列出的一律禁止：

# 只读子代理：只能看，不能改
tools: Read, Grep, Glob

# 研究型子代理：可以看代码 + 搜索网络
tools: Read, Grep, Glob, WebFetch, WebSearch

# 开发型子代理：完整的读写能力
tools: Read, Write, Edit, Bash, Grep, Glob

禁止列表

从继承的全部工具中排除特定工具：

# 继承所有工具，但禁止写入和编辑
disallowedTools: Write, Edit

省略（继承全部）

不指定 tools 字段时，子代理将继承主对话的所有工具权限（包括 MCP 工具）。

限制子代理的子代理生成能力

使用 Task(agent_type) 语法限制可委派的子代理类型：

# 协调者只能生成 worker 和 researcher，不能生成其他类型
tools: Task(worker, researcher), Read, Bash

按角色推荐的工具配置

角色	推荐工具	说明
代码审查员	Read, Grep, Glob, Bash	Bash 用于执行 git diff
安全审计员	Read, Grep, Glob, Bash	Bash 用于检查依赖漏洞
测试运行器	Read, Edit, Bash, Grep, Glob	需要 Edit 来修复失败的测试
文档生成器	Read, Write, Grep, Glob	需要 Write 来生成文档文件
数据分析师	Bash, Read, Write	Bash 用于执行 SQL 等数据操作
只读研究员	Read, Grep, Glob	最小权限，纯粹的信息收集

6.5 权限模式

permissionMode 字段控制子代理在执行操作时的确认行为：

模式	行为	适用场景
`default`	正常的权限确认提示	通用场景
`acceptEdits`	自动接受文件编辑，其他操作仍需确认	信任的代码生成子代理
`dontAsk`	自动拒绝所有未预授权的操作	严格受控的生产环境
`bypassPermissions`	跳过所有权限检查	仅用于完全可信的子代理
`plan`	只读规划模式，禁止任何写操作	方案设计阶段

安全警告：bypassPermissions 会跳过所有安全检查，只应用于你完全信任且工具权限已严格限制的子代理。

6.6 作用域与优先级

优先级	位置	作用域	典型用途
1（最高）	CLI `--agents` 参数	当前会话	临时测试、自动化脚本
2	`.claude/agents/`	当前项目	项目专用，提交到 Git 团队共享
3	`~/.claude/agents/`	所有项目	个人通用工具
4（最低）	插件的 `agents/` 目录	插件作用域	第三方插件提供的子代理

实践建议：

项目级子代理（.claude/agents/）：与代码一起提交到 Git，团队成员自动共享。适合放项目专属的审查规则、测试流程等。
用户级子代理（~/.claude/agents/）：跨项目复用个人偏好工具，如个人常用的代码审查风格、日志分析方式等。
CLI 临时子代理：适合在 CI/CD 流水线或一次性脚本中使用。

7. 执行模式：前台与后台

7.1 前台执行（默认）

子代理在前台运行时会阻塞主对话，直到任务完成。运行期间的权限确认提示会正常弹出。

7.2 后台执行

在配置中设为始终后台运行：

background: true

或者在运行中按 Ctrl+B 将当前前台子代理切换到后台。

后台执行的限制：

无法向用户提问（AskUserQuestion 调用会静默失败，但子代理会继续执行）
无法使用 MCP 工具
不支持需要用户交互的权限确认（Claude Code 会在启动前预请求所需权限）
如果因权限不足导致失败，需要在前台恢复

7.3 并行执行

可以同时启动多个子代理并行工作：

> 使用子代理并行分析以下三个模块的代码质量：
> 1. src/auth — 认证模块
> 2. src/database — 数据库层
> 3. src/api — API 路由层

Claude 会为每个模块创建独立的子代理实例，并行执行并分别返回结果。

8. 持久化记忆

子代理默认每次调用都是全新实例。通过 memory 字段可以启用跨会话的持久化记忆，让子代理积累经验。

8.1 记忆范围

范围	存储位置	是否提交到 Git	适用场景
`user`	`~/.claude/agent-memory/<name>/`	否	个人积累，跨所有项目（推荐默认选择）
`project`	`.claude/agent-memory/<name>/`	可以	项目知识库，团队共享
`local`	`.claude/agent-memory-local/<name>/`	否	项目特定但不共享的知识

8.2 工作机制

启用 memory 后：

子代理的系统提示词自动注入读写记忆目录的指令
启动时自动加载 MEMORY.md 的前 200 行
超过 200 行时会提示子代理精简内容
自动启用 Read、Write、Edit 工具以管理记忆文件

8.3 使用示例

---
name: smart-reviewer
description: 具备学习能力的代码审查员，跨会话积累项目模式和规范经验。
memory: user
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一个能够持续学习和改进的代码审查工程师。

开始审查前：
1. 查阅你的记忆文件，回顾之前发现的模式和规范
2. 审查当前的代码变更
3. 结合积累的经验和当前分析给出反馈

完成审查后：
- 将新发现的模式更新到记忆中
- 记录反复出现的问题和项目特有的编码规范

在对话中引导子代理使用记忆：

> 使用 smart-reviewer 审查这次提交，查看你的记忆中是否有之前发现的相关模式
> 审查完成后，把这次发现的新模式保存到记忆中

9. 生命周期钩子（Hooks）

子代理支持通过钩子在特定时机触发自定义脚本，实现更精细的行为控制。

9.1 子代理内部定义钩子

在子代理的 YAML 前置元数据中配置，仅在该子代理活跃时生效：

---
name: safe-coder
description: 带自动代码检查的安全编码代理。在编写或修改代码时主动使用。
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

9.2 支持的钩子事件

事件	匹配器输入	触发时机
`PreToolUse`	工具名称	子代理调用工具之前
`PostToolUse`	工具名称	子代理调用工具之后
`Stop`	无	子代理完成时

9.3 在项目设置中响应子代理事件

在 settings.json 中可以监听子代理的生命周期事件：

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-resources.sh" }
        ]
      }
    ]
  }
}

9.4 实战示例：数据库只读查询守卫

通过钩子强制子代理只能执行 SELECT 查询，拦截所有写操作：

---
name: db-reader
description: 数据库只读查询代理。用于数据分析和报表生成时主动使用。
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

你是一名具有只读权限的数据库分析师。
使用 SELECT 查询来回答关于数据的问题。
如果被要求执行 INSERT、UPDATE、DELETE 或修改表结构的操作，
请拒绝并说明你只有只读权限。

配套的验证脚本 ./scripts/validate-readonly-query.sh：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# 拦截 SQL 写操作（不区分大小写）
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "已拦截：不允许执行写操作，只能使用 SELECT 查询。" >&2
  exit 2  # exit code 2 = 阻止操作并将错误信息反馈给子代理
fi

exit 0

9.5 钩子的已知限制

PostToolUse 钩子的反馈只返回到当前子代理，不会传播到父级主对话
同一会话中的多个子代理共享 session_id，SubagentStop 无法区分具体是哪个子代理完成
上述限制可通过临时文件或 Git 状态间接传递信息来变通

10. 子代理的恢复与上下文管理

10.1 恢复已完成的子代理

每次调用会创建新的子代理实例，但你可以基于之前的对话历史恢复继续：

> 使用 code-reviewer 审查认证模块
[子代理完成审查]

> 继续刚才的 code-reviewer 分析，重点看授权逻辑部分
[Claude 恢复子代理，保留完整对话历史]

10.2 上下文存储

子代理的对话记录存储在：

~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

主对话压缩不影响子代理记录
子代理记录在会话内持久存在
默认 30 天自动清理

10.3 自动压缩

子代理支持独立的上下文自动压缩，默认在约 95% 容量时触发。可通过环境变量调整阈值：

# 在 50% 容量时提前压缩
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

11. 实战配置模板

以下模板均可直接保存为 .claude/agents/xxx.md 或 ~/.claude/agents/xxx.md 使用。

说明：name 字段保留英文，因为它是系统内部使用的唯一标识符，不影响子代理的中文交互能力。系统提示词使用中文编写，子代理会以中文进行工作和输出。

11.1 代码审查员

---
name: code-reviewer
description: 代码质量审查专家。在编写或修改代码后主动使用（proactively），检查代码质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名资深代码审查工程师，负责确保代码质量达到高标准。

被调用时：
1. 运行 `git diff` 查看最近的代码变更
2. 聚焦已修改的文件
3. 立即开始审查

审查清单：
- 命名是否清晰且一致
- 是否存在重复逻辑
- 错误处理是否完善
- 是否暴露了密钥或 API Key
- 系统边界处是否做了输入校验
- 是否存在性能隐患

按优先级分类反馈：
- **严重** — 合并前必须修复
- **警告** — 建议修复，存在潜在风险
- **建议** — 可以考虑优化

每个问题都要附上具体的修复代码示例。

11.2 安全审计员

---
name: security-auditor
description: 安全分析专家。主动用于审计代码中的安全漏洞、敏感信息暴露和安全最佳实践。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名专注于代码安全审计的安全专家。

被调用时：
1. 扫描硬编码的凭证、API 密钥、Token 等敏感信息
2. 审查认证（Authentication）和授权（Authorization）流程
3. 检查输入校验和数据净化（Sanitization）
4. 评估依赖包的已知漏洞（执行 `npm audit` 或对应的包管理器命令）
5. 审查 CORS、CSP 等安全头配置

报告格式：
- **严重** — 需要立即处理（如：暴露的密钥）
- **高危** — 下次发版前必须修复（如：SQL 注入风险）
- **中危** — 下个迭代中处理（如：缺少请求频率限制）
- **低危** — 最佳实践建议

11.3 测试运行器

---
name: test-runner
description: 主动用于运行测试并修复失败用例。支持单元测试、集成测试和覆盖率分析。
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

你是一名测试自动化专家。

被调用时：
1. 检测项目使用的测试框架（Jest、Vitest、pytest、JUnit 等）
2. 运行完整测试套件或指定的测试用例
3. 分析失败原因 — 判断是测试用例有误还是业务代码有 bug
4. 用最小改动修复问题
5. 重新运行测试验证修复结果

每次必须汇报：
- 测试总数：通过 / 失败 / 跳过
- 覆盖率（如果可用）
- 所做修复的摘要说明

11.4 文档生成器

---
name: doc-generator
description: 技术文档专家。主动用于生成 README、API 文档、代码注释和技术文档。
tools: Read, Write, Grep, Glob
model: haiku
---

你是一名技术文档专家。

被调用时：
1. 分析代码库结构
2. 识别公开的 API、导出函数和关键类
3. 生成清晰、完整的文档
4. 遵循项目已有的文档风格

文档标准：
- 每个公开 API 都要有代码使用示例
- 参数类型和说明
- 返回值文档
- 异常/错误说明

11.5 重构专家（带 Worktree 隔离）

---
name: refactorer
description: 安全的代码重构代理。在独立的 worktree 中运行，避免与主工作区冲突。
tools: Read, Write, Edit, Bash, Grep, Glob
isolation: worktree
model: inherit
---

你是一名代码重构专家，在隔离的环境中工作。

由于你运行在独立的 git worktree 中，可以自由修改代码而不影响主工作区。

被调用时：
1. 理解重构需求
2. 分析变更的影响范围
3. 执行重构操作
4. 运行测试确保没有引入回归问题
5. 汇报所有变更内容

如果重构后测试失败，先尝试修复再汇报。

11.6 带持久记忆的项目顾问

---
name: project-advisor
description: 项目架构顾问，跨会话积累项目知识。在做架构决策或评估技术方案时主动使用。
memory: user
tools: Read, Grep, Glob, WebSearch
model: sonnet
---

你是一名资深软件架构师，能够随时间积累项目知识。

回答问题前：
1. 查阅你的记忆，寻找关于该项目的相关上下文
2. 审查相关的代码和架构
3. 基于积累的知识和当前分析给出建议

完成分析后：
- 将关键的架构决策保存到记忆中
- 记录项目特有的模式和规范
- 记录技术选型及其背后的理由

12. 典型使用模式

12.1 模式一：隔离高输出任务

将产生大量输出的任务交给子代理，只接收摘要结果，保护主对话上下文：

> 使用子代理运行完整的测试套件，只返回失败的用例和错误信息

12.2 模式二：并行研究

同时启动多个子代理，分别调研不同模块：

> 并行使用子代理分析以下三个模块的代码质量：
> 1. src/auth — 认证模块
> 2. src/database — 数据库层
> 3. src/api — API 路由层

12.3 模式三：串联子代理

先用一个子代理发现问题，再用另一个修复：

> 先用 code-reviewer 子代理找出代码问题，然后用 refactorer 子代理逐一修复

12.4 模式四：大规模批量操作

将大任务拆分为多个子代理并行处理：

> 这个项目需要弃用 legacyRequest 函数，它在 75 个文件中被使用。
> 为每个文件生成子代理，将 legacyRequest 替换为新的 httpClient 封装。

12.5 模式五：三阶段流水线

在企业级场景中，按流水线编排子代理：

> 阶段 1：使用 spec-writer 子代理将需求文档转化为技术规格
> 阶段 2：使用 architect 子代理审查规格并生成架构设计文档
> 阶段 3：使用 implementer 子代理根据设计文档实现代码和测试

13. 限制与注意事项

限制	说明	变通方案
子代理不能生成子代理	防止无限嵌套	从主对话链式调用，或使用 Skills 替代
手动创建的文件不会立即生效	需要重启会话或运行 `/agents`	使用 `/agents` 命令创建可立即生效
后台子代理无法交互	无法提问、无法使用 MCP 工具	改为前台执行，或预授权所需权限
多个子代理消耗主对话上下文	返回的摘要仍占用 Token	控制并行数量，要求子代理精简输出

常见问题排查

子代理没有被自动调用：检查 description 字段是否准确描述了触发场景；尝试在 description 中加入“主动使用”等主动触发词；确认文件已被加载（运行 /agents 查看列表）。
子代理输出不符合预期：系统提示词要具体，包含明确的步骤和约束；附上输出格式示例；检查工具权限是否足够完成任务。
后台子代理执行失败：检查是否因权限不足被拒绝；改为前台运行以查看具体错误；确认任务不依赖 MCP 工具或用户交互。

14. 成本优化策略

子代理的模型选择直接影响使用成本。合理的模型分层可以在保证质量的同时大幅降低开销。

14.1 模型分层路由

任务类型	推荐模型	说明
文件搜索、简单代码阅读	Haiku	速度快、成本低
代码审查、测试分析、常规开发	Sonnet	最佳性价比，覆盖 90% 场景
架构决策、复杂推理	Opus	最高质量，按需使用

14.2 实际成本对比

业界实测数据表明：

1 个 Sonnet 主代理 + 34 个 Haiku 子代理的方案，相比全部使用 Sonnet，成本降低 85–96%
单次 Haiku 子代理调用约 $0.03，Sonnet 约 $0.75，Opus 约 $2.00

14.3 优化建议

简单探索用 Haiku：文件搜索、定义查找、文档生成等低复杂度任务
核心开发用 Sonnet：代码审查、测试修复、功能实现等日常任务
关键决策用 Opus：架构设计、复杂 bug 分析等需要深度推理的场景
隔离高输出操作：将测试运行、日志分析等产生大量输出的任务委派给子代理，避免撑满主对话上下

15. 最佳实践总结

从 /agents 命令开始 — 使用 Claude 自动生成初版配置，然后根据实际效果迭代优化。
每个子代理只专注一件事 — 职责越单一，输出越可控。避免创建「什么都能干」的万能子代理。
最小权限原则 — 只授予子代理完成任务所必需的工具，减少误操作风险。
description 要精准 — 这是自动委派的唯一依据，模糊的描述会导致该触发时不触发，不该触发时乱触发。
系统提示词要具体 — 包含明确的步骤、约束和输出格式要求，比笼统的角色描述更有效。
项目级子代理提交到 Git — 团队共享，保持一致的 AI 辅助行为。
善用模型分层 — 不是所有任务都需要最强模型，合理分配可以显著降低成本。
善用持久记忆 — 对于需要积累经验的子代理（如项目审查员），启用 memory 让它越用越好。

结语

子代理是 Claude Code 中一项极具价值的高级特性。通过合理的设计和配置，你可以将复杂任务拆解为由多个专业 AI 助手协同完成的流水线，同时保持主对话上下文的清爽和可控。掌握子代理的使用，意味着你真正开始以「系统工程」的思维来驾驭 AI，让工具为人所用，发挥最大效能。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

2026 AI全领域深度报告：国内外模型争霸、内容革命与产业未来

AtomGit开源社区

贾子科学定理（Kucius Science Theorem）：一种基于绝对确定性真理的科学划界及哲学批判框架

AtomGit开源社区

把 Catalog 放进正确的角色里：深入理解 SAP Fiori 的 Authorizations、PFCG 与管理员权限边界

AtomGit开源社区

所有评论(0)

查看更多评论

sensen111111

@sensen111111

已为社区贡献5条内容

Claude Code 入门实战 5：子代理（Subagent）使用指南

sensen111111

前言

1. 什么是子代理？

2. 为什么需要子代理？

3. 子代理运行机制

3.1 生命周期

3.2 上下文隔离模型

3.3 与主对话的协作方式

4. 内置子代理

5. 创建自定义子代理

5.1 方式1：使用 /agents 命令（推荐）

5.2 方式2：手动创建文件

5.3 方式3：CLI 参数传入（临时使用）

6. 配置文件详解

6.1 基本结构

6.2 完整字段说明

6.3 description 字段：自动委派的关键

6.4 工具权限配置

允许列表（推荐，最安全）

禁止列表

省略（继承全部）

限制子代理的子代理生成能力

按角色推荐的工具配置

6.5 权限模式

6.6 作用域与优先级

7. 执行模式：前台与后台

7.1 前台执行（默认）

7.2 后台执行

7.3 并行执行

8. 持久化记忆

8.1 记忆范围

8.2 工作机制

8.3 使用示例

9. 生命周期钩子（Hooks）

9.1 子代理内部定义钩子

9.2 支持的钩子事件

9.3 在项目设置中响应子代理事件

9.4 实战示例：数据库只读查询守卫

9.5 钩子的已知限制

10. 子代理的恢复与上下文管理

10.1 恢复已完成的子代理

10.2 上下文存储

10.3 自动压缩

11. 实战配置模板

11.1 代码审查员

11.2 安全审计员

11.3 测试运行器

11.4 文档生成器

11.5 重构专家（带 Worktree 隔离）

11.6 带持久记忆的项目顾问

12. 典型使用模式

12.1 模式一：隔离高输出任务

12.2 模式二：并行研究

12.3 模式三：串联子代理

12.4 模式四：大规模批量操作

12.5 模式五：三阶段流水线

13. 限制与注意事项

常见问题排查

14. 成本优化策略

14.1 模型分层路由

14.2 实际成本对比

14.3 优化建议

15. 最佳实践总结

结语

所有评论(0)

sensen111111

5.1 方式1：使用 `/agents` 命令（推荐）

6.3 `description` 字段：自动委派的关键