子代理模式（Subagent Patterns）
概述
子代理是运行在独立上下文窗口中的专业 AI 助手，拥有自定义系统提示、特定工具权限和独立的权限模式。它们是 Claude Code 的核心扩展机制之一。
内置子代理
| 代理 | 模型 | 工具权限 | 用途 |
|---|---|---|---|
| Explore | Haiku | 只读 | 文件发现、代码搜索、代码库探索 |
| Plan | 继承 | 只读 | 代码库研究与规划 |
| general-purpose | 继承 | 全部工具 | 复杂研究、多步操作 |
| Bash | 继承 | 终端命令 | Shell 操作 |
| statusline-setup | Sonnet | 状态栏配置 | 自定义状态栏 |
| Claude Code Guide | Haiku | 功能查询 | Claude Code 使用问答 |
自定义子代理
在 .claude/agents/ 或 ~/.claude/agents/ 中创建 Markdown 文件定义自定义子代理：
---
name: code-reviewer
description: 专业代码审查员。用于审查 PR、检查代码质量和安全漏洞。
tools: Read, Grep, Glob, Bash(npm run lint *)
model: sonnet
permissionMode: default
maxTurns: 20
---
你是一名资深代码审查员。执行以下检查：
1. **代码质量**：命名规范、函数长度、单一职责
2. **安全性**：注入风险、敏感数据暴露、认证缺陷
3. **性能**：N+1 查询、无效渲染、内存泄漏
4. **可维护性**：重复代码、耦合度、测试覆盖
输出结构化的审查报告。
Frontmatter 字段
| 字段 | 必须 | 说明 |
|---|---|---|
name |
✅ | 唯一标识符（小写，连字符） |
description |
✅ | Claude 据此决定何时委派任务给该代理 |
tools |
❌ | 可使用的工具列表（省略则继承全部） |
disallowedTools |
❌ | 禁止使用的工具 |
model |
❌ | sonnet、opus、haiku、完整模型 ID 或 inherit |
permissionMode |
❌ | default、acceptEdits、dontAsk、bypassPermissions、plan |
maxTurns |
❌ | 最大代理轮数 |
skills |
❌ | 启动时预加载的技能列表 |
mcpServers |
❌ | 可用的 MCP 服务器（内联定义或字符串引用） |
hooks |
❌ | 作用域限定在此代理的生命周期 Hooks |
memory |
❌ | 持久记忆范围：user、project 或 local |
background |
❌ | 设为 true 始终作为后台任务运行 |
isolation |
❌ | 设为 worktree 在临时 Git 工作树中运行 |
子代理位置与优先级
| 位置 | 作用范围 | 优先级 |
|---|---|---|
--agents CLI 参数 |
当前会话 | 1（最高） |
.claude/agents/ |
当前项目 | 2 |
~/.claude/agents/ |
所有项目 | 3 |
插件的 agents/ |
启用插件时 | 4（最低） |
CLI 定义子代理
通过命令行参数定义临时子代理：
claude --agents '{
"code-reviewer": {
"description": "专业代码审查员",
"prompt": "你是一名资深代码审查员...",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'
持久记忆
为子代理启用跨会话记忆：
| 范围 | 存储位置 |
|---|---|
user |
~/.claude/agent-memory/<name>/ |
project |
.claude/agent-memory/<name>/ |
local |
.claude/agent-memory-local/<name>/ |
启用记忆后：
- 子代理获得读写记忆的指令
MEMORY.md的前 200 行在启动时加载- Read/Write/Edit 工具自动启用
工具限制
限制子代理可生成的子代理
tools: Agent(worker, researcher), Read, Bash
这只允许该子代理生成 worker 和 researcher 两个子代理。
MCP 服务器限定
mcpServers:
my-db:
command: npx
args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
为子代理定义专属的 MCP 服务器，实现工具级别的隔离。
前台 vs 后台
| 模式 | 特点 |
|---|---|
| 前台（默认） | 阻塞主对话，权限提示传递给用户 |
| 后台 | 并行运行，预先批准权限，自动拒绝未预批准的操作 |
工作树隔离
isolation: worktree
子代理在临时 Git 工作树中工作，拥有仓库的独立副本。适用于：
- 需要并行修改同一文件的场景
- 实验性更改（不影响主分支）
/batch技能内部的并行处理单元
实用模式
数据库查询代理
---
name: db-reader
description: 安全的只读数据库查询代理
tools: Bash(psql *)
model: haiku
maxTurns: 5
---
你只能执行 SELECT 查询。绝对不能执行 INSERT/UPDATE/DELETE/DROP。
每次查询前先解释你要查什么。
调研代理
---
name: researcher
description: 深入调研代码库的特定问题
tools: Read, Grep, Glob, WebSearch, WebFetch
model: sonnet
background: true
memory: project
---
你是一个调研专家。系统性地搜索代码库，找到完整的答案。
将你的发现保存到记忆中，以便未来参考。
安全审计代理
---
name: security-auditor
description: 安全审计——检查代码中的漏洞和安全问题
tools: Read, Grep, Glob, Bash(npm audit *)
model: opus
maxTurns: 30
---
执行全面安全审计：OWASP Top 10、依赖漏洞、密钥泄露、认证缺陷。
输出结构化报告，按严重程度排序。