Subagents 完整参考指南

Subagents 是 Claude Code 可以委派任务的专用 AI 助手。每个 subagent 都有特定用途，使用独立于主对话的上下文窗口，并可以配置特定工具和自定义系统提示词。

目录

1. 概览
2. 主要优势
3. 文件位置
4. 配置
5. 内置 Subagents
6. 管理 Subagents
7. 使用 Subagents
8. 可恢复的 Agents
9. 串联 Subagents
10. Subagents 的持久记忆
11. 后台 Subagents
12. Worktree 隔离
13. 分叉的 Subagents
14. 限制可启动的 Subagents
15. claude agents CLI 命令
16. Agent Teams（实验性）
17. 插件 Subagent 安全
18. 架构
19. 上下文管理
20. 何时使用 Subagents
21. 最佳实践
22. 本目录中的示例 Subagents
23. 安装说明
24. 相关概念

概览

Subagents 通过以下方式实现 Claude Code 中的委派任务执行：

• 创建具有独立上下文窗口的隔离 AI 助手
• 提供自定义系统提示词以获得专业领域知识
• 实施工具访问控制以限制能力
• 防止复杂任务造成的上下文污染
• 实现多个专业任务的并行执行

每个 subagent 独立运行，拥有全新的上下文，只接收其任务所需的特定上下文，然后将结果返回给主 agent 进行综合处理。

快速开始：使用 /agents 命令交互式创建、查看、编辑和管理你的 subagents。

主要优势

文件位置

Subagent 文件可以存储在多个位置，具有不同的作用域：

当存在重复名称时，优先级更高的来源优先。

配置

文件格式

Subagents 在 YAML frontmatter 中定义，后跟 markdown 格式的系统提示词：

---
name: your-sub-agent-name
description: 描述何时应调用此 subagent 的时机
tools: tool1, tool2, tool3  # 可选 - 省略则继承所有工具
disallowedTools: tool4  # 可选 - 明确禁止的工具
model: sonnet  # 可选 - sonnet、opus、haiku 或 inherit
permissionMode: default  # 可选 - 权限模式
maxTurns: 20  # 可选 - 限制代理回合数
skills: skill1, skill2  # 可选 - 预加载到上下文的技能
mcpServers: server1  # 可选 - 可用的 MCP 服务器
memory: user  # 可选 - 持久记忆作用域（user、project、local）
background: false  # 可选 - 作为后台任务运行
effort: high  # 可选 - 推理努力程度（low、medium、high、max）
isolation: worktree  # 可选 - git worktree 隔离
initialPrompt: "首先分析代码库"  # 可选 - 自动提交的第一轮提示
hooks:  # 可选 - 组件作用域的钩子
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

你的 subagent 系统提示词放在这里。可以是多个段落，
应该清楚地定义 subagent 的角色、能力和解决问题的方法。

配置字段

主线程 Agent Frontmatter 支持（v2.1.117+/v2.1.119+）

当 agent 作为主线程 agent 调用时（通过 claude --agent <name> 或 --print 模式），以下 frontmatter 字段会被支持：

示例 — 带 mcpServers 和 permissionMode 的 agent：

---
name: secure-researcher
description: 具有作用域 MCP 访问和受限权限的研究 agent
permissionMode: acceptEdits
mcpServers:
  notion:
    type: http
    url: https://mcp.notion.com/mcp
  github:
    type: http
    url: https://api.github.com/mcp
tools: Read, Grep, Glob
---

你是一个研究 agent。你可以通过配置的 MCP 服务器查询 Notion 和 GitHub，
并读取本地文件，但你不能写入或执行接受编辑之外的命令。

运行方式：

claude --agent secure-researcher

工具配置选项

选项 1：继承所有工具（省略该字段）

---
name: full-access-agent
description: 拥有所有可用工具的 agent
---

选项 2：指定特定工具

---
name: limited-agent
description: 仅拥有特定工具的 agent
tools: Read, Grep, Glob, Bash
---

关于 Glob/Grep 的说明（v2.1.113+）： 在原生 macOS/Linux 构建中，Glob 和 Grep 作为 bfs/ugrep 通过 Bash 工具提供，而非独立工具。Windows 和 npm-JS 构建仍将其作为独立工具暴露。作者仍可在 allowedTools 中引用 Glob/Grep；后端替换是透明的。

选项 3：条件工具访问

---
name: conditional-agent
description: 具有过滤工具访问的 agent
tools: Read, Bash(npm:*), Bash(test:*)
---

基于 CLI 的配置

使用 --agents 标志和 JSON 格式为单个会话定义 subagents：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

--agents 标志的 JSON 格式：

{
  "agent-name": {
    "description": "必需：何时调用此 agent",
    "prompt": "必需：agent 的系统提示词",
    "tools": ["可选", "工具", "数组"],
    "model": "可选：sonnet|opus|haiku"
  }
}

Agent 定义优先级：

Agent 定义按以下优先级顺序加载（首次匹配生效）：

1. CLI 定义 - --agents 标志（仅会话，JSON）
2. 项目级 - .claude/agents/（当前项目）
3. 用户级 - ~/.claude/agents/（所有项目）
4. 插件级 - 插件 agents/ 目录

这允许 CLI 定义在单个会话中覆盖所有其他来源。

内置 Subagents

Claude Code 包含几个始终可用的内置 subagents：

通用 Subagent

使用场景：需要同时进行探索和修改的复杂推理任务。

Plan Subagent

使用场景：Claude 需要在呈现计划之前理解代码库时。

Explore Subagent

使用场景：搜索/理解代码而不进行更改时。

彻底程度级别 - 指定探索深度：

• “quick” - 最小探索的快速搜索，适合查找特定模式
• “medium” - 中等探索，平衡速度和彻底性，默认方法
• “very thorough” - 跨多个位置和命名约定的全面分析，可能需要更长时间

Bash Subagent

使用场景：运行需要隔离上下文的 shell 命令时。

Statusline Setup Subagent

使用场景：设置或自定义状态栏时。

Claude Code Guide Subagent

使用场景：用户询问 Claude Code 如何工作或如何使用特定功能时。

管理 Subagents

使用 /agents 命令（推荐）

/agents

这提供了一个交互式菜单，可以：

• 查看所有可用的 subagents（内置、用户和项目）
• 使用引导设置创建新的 subagents
• 编辑现有的自定义 subagents 和工具访问
• 删除自定义 subagents
• 查看存在重复时哪些 subagents 处于活动状态

直接文件管理

# 创建项目 subagent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: 主动运行测试并修复失败
---

你是一个测试自动化专家。当你看到代码更改时，主动运行适当的测试。
如果测试失败，分析失败原因并修复它们，同时保留原始测试意图。
EOF

# 创建用户 subagent（在所有项目中可用）
mkdir -p ~/.claude/agents

使用 Subagents

自动委派

Claude 根据以下内容主动委派任务：

• 你请求中的任务描述
• subagent 配置中的 description 字段
• 当前上下文和可用工具

要鼓励主动使用，请在 description 字段中包含 “use PROACTIVELY” 或 “MUST BE USED”：

---
name: code-reviewer
description: 专业代码审查专家。编写或修改代码后主动使用。
---

显式调用

你可以明确请求特定 subagent：

> 使用 test-runner subagent 修复失败的测试
> 让 code-reviewer subagent 查看我最近的更改
> 让 debugger subagent 调查这个错误

@提及调用

使用 @ 前缀保证调用特定 subagent（绕过自动委派启发式）：

> @"code-reviewer (agent)" 审查 auth 模块

会话级 Agent

在整个会话中使用特定 agent 作为主 agent：

# 通过 CLI 标志
claude --agent code-reviewer

# 通过 settings.json
{
  "agent": "code-reviewer"
}

列出可用 Agents

使用 claude agents 命令列出所有来源配置的 agents：

claude agents

可恢复的 Agents

Subagents 可以继续之前的对话，完整保留上下文：

# 初始调用
> 使用 code-analyzer agent 开始审查认证模块
# 返回 agentId: "abc123"

# 稍后恢复 agent
> 恢复 agent abc123 并分析授权逻辑

用例：

• 跨多个会话的长时间运行研究
• 迭代改进而不丢失上下文
• 维护上下文的多步骤工作流

串联 Subagents

按顺序执行多个 subagents：

> 首先使用 code-analyzer subagent 查找性能问题，
  然后使用 optimizer subagent 修复它们

这实现了复杂的工作流，其中一个 subagent 的输出可以馈送到另一个。

Subagents 的持久记忆

memory 字段为 subagents 提供一个跨对话持久化的目录。这允许 subagents 随时间积累知识，存储笔记、发现和在会话之间持久化的上下文。

记忆作用域

工作方式

• 记忆目录中的 MEMORY.md 的前 200 行会自动加载到 subagent 的系统提示词中
• Read、Write 和 Edit 工具会自动启用，供 subagent 管理其记忆文件
• subagent 可以根据需要在其记忆目录中创建额外文件

示例配置

---
name: researcher
memory: user
---

你是一个研究助手。使用你的记忆目录存储发现、跟踪跨会话的进度，
并随时间积累知识。

在每次会话开始时检查你的 MEMORY.md 文件以回忆之前的上下文。

    graph LR
    A["Subagent<br/>会话 1"] -->|写入| M["MEMORY.md<br/>(持久化)"]
    M -->|加载到| B["Subagent<br/>会话 2"]
    B -->|更新| M
    M -->|加载到| C["Subagent<br/>会话 3"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style M fill:#f3e5f5,stroke:#333,color:#333
  

后台 Subagents

Subagents 可以在后台运行，释放主对话以处理其他任务。

配置

在 frontmatter 中设置 background: true 以始终将 subagent 作为后台任务运行：

---
name: long-runner
background: true
description: 在后台执行长时间运行的分析任务
---

快捷键

禁用后台任务

设置环境变量以完全禁用后台任务支持：

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Worktree 隔离

isolation: worktree 设置为 subagent 提供自己的 git worktree，允许它独立进行更改而不影响主工作树。

配置

---
name: feature-builder
isolation: worktree
description: 在隔离的 git worktree 中实现功能
tools: Read, Write, Edit, Bash, Grep, Glob
---

工作方式

    graph TB
    Main["主工作树"] -->|生成| Sub["具有<br/>隔离 Worktree 的 Subagent"]
    Sub -->|在其中进行更改| WT["独立的 Git<br/>Worktree + 分支"]
    WT -->|无更改| Clean["自动清理"]
    WT -->|有更改| Return["返回 worktree<br/>路径和分支"]

    style Main fill:#e1f5fe,stroke:#333,color:#333
    style Sub fill:#f3e5f5,stroke:#333,color:#333
    style WT fill:#e8f5e9,stroke:#333,color:#333
    style Clean fill:#fff3e0,stroke:#333,color:#333
    style Return fill:#fff3e0,stroke:#333,color:#333
  

• subagent 在自己的 git worktree 中操作，位于单独的分支上
• 如果 subagent 没有进行任何更改，worktree 会被自动清理
• 如果存在更改，worktree 路径和分支名称会返回给主 agent 进行审查或合并

分叉的 Subagents

分叉的 subagents（context: fork）继承父 agent 在分叉时的完整对话上下文，而不是从全新状态开始。这对于探索替代路径而不丢失已完成的工作非常有用。

可用性：在 v2.1.117 中正式发布。在外部构建（非第一方发行版）上，设置 CLAUDE_CODE_FORK_SUBAGENT=1 以启用分叉。

配置

---
name: alternative-explorer
description: 在保留父上下文的同时探索替代实现路径
context: fork
tools: Read, Edit, Bash, Grep, Glob
---

你是一个分叉的 subagent。你继承父级的完整对话，
可以探索替代方法。返回你的发现，父级将决定是否采用它们。

在外部构建上启用

export CLAUDE_CODE_FORK_SUBAGENT=1
claude

何时使用分叉 vs 全新上下文

限制可启动的 Subagents

你可以通过在 tools 字段中使用 Agent(agent_type) 语法来控制给定 subagent 允许启动哪些 subagents。这提供了一种为委派设置白名单特定 subagents 的方法。

注意：在 v2.1.63 中，Task 工具重命名为 Agent。现有的 Task(...) 引用仍可作为别名使用。

示例

---
name: coordinator
description: 协调专业 agents 之间的工作
tools: Agent(worker, researcher), Read, Bash
---

你是一个协调 agent。你只能将工作委派给 "worker" 和
"researcher" subagents。使用 Read 和 Bash 进行自己的探索。

在这个示例中，coordinator subagent 只能启动 worker 和 researcher subagents。它不能启动任何其他 subagents，即使它们在其他地方定义。

claude agents CLI 命令

claude agents 命令按来源（内置、用户级、项目级）分组列出所有配置的 agents：

claude agents

此命令：

• 显示所有来源的所有可用 agents
• 按来源位置对 agents 进行分组
• 当高优先级的 agent 覆盖低优先级的 agent 时指示覆盖（例如，与用户级 agent 同名的项目级 agent）

Agent Teams（实验性）

Agent Teams 协调多个 Claude Code 实例共同处理复杂任务。与 subagents（委派子任务并返回结果）不同，team 独立工作，拥有自己的上下文窗口，并可以通过共享邮箱系统直接相互发消息。

官方文档：code.claude.com/docs/en/agent-teams

注意：Agent Teams 是实验性的，默认禁用。需要 Claude Code v2.1.32+。使用前请启用。

Subagents vs Agent Teams

启用 Agent Teams

设置环境变量或将其添加到 settings.json：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

或在 settings.json 中：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启动团队

启用后，在你的提示中要求 Claude 与 team 一起工作：

用户：构建认证模块。使用团队——一个 team 负责 API 端点，
      一个负责数据库模式，一个负责测试套件。

Claude 将创建团队、分配任务并自动协调工作。

显示模式

控制 team 活动的显示方式：

claude --teammate-mode tmux

你也可以在 settings.json 中设置显示模式：

{
  "teammateMode": "tmux"
}

注意：分屏模式需要 tmux 或 iTerm2。在 VS Code 终端、Windows Terminal 或 Ghostty 中不可用。

导航

在分屏模式下使用 Shift+Down 在 team 之间导航。

团队配置

团队配置存储在 ~/.claude/teams/{team-name}/config.json。

架构

    graph TB
    Lead["团队负责人<br/>(协调者)"]
    TaskList["共享任务列表<br/>(依赖关系)"]
    Mailbox["邮箱<br/>(消息)"]
    T1["Team 1<br/>(自己的上下文)"]
    T2["Team 2<br/>(自己的上下文)"]
    T3["Team 3<br/>(自己的上下文)"]

    Lead -->|分配任务| TaskList
    Lead -->|发送消息| Mailbox
    TaskList -->|接收工作| T1
    TaskList -->|接收工作| T2
    TaskList -->|接收工作| T3
    T1 -->|读取/写入| Mailbox
    T2 -->|读取/写入| Mailbox
    T3 -->|读取/写入| Mailbox
    T1 -->|更新状态| TaskList
    T2 -->|更新状态| TaskList
    T3 -->|更新状态| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333
  

关键组件：

• 团队负责人：创建团队、分配任务并协调的主要 Claude Code 会话
• 共享任务列表：具有自动依赖跟踪的同步任务列表
• 邮箱：team 用于通信状态和协调的 agent 间消息系统
• Teams：独立的 Claude Code 实例，每个都有自己的上下文窗口

任务分配和消息传递

团队负责人将工作分解为任务并分配给 team。共享任务列表处理：

• 自动依赖管理 — 任务等待其依赖项完成
• 状态跟踪 — team 在工作时更新任务状态
• Agent 间消息 — team 通过邮箱发送消息进行协调（例如 “数据库模式已就绪，你可以开始编写查询”）

计划审批工作流

对于复杂任务，团队负责人在 team 开始工作之前创建执行计划。用户审查并批准计划，确保团队的方法在进行任何代码更改之前符合预期。

团队相关 Hook 事件

Agent Teams 引入了两个额外的 hook 事件：

最佳实践

• 团队规模：保持团队在 3-5 个 team 以获得最佳协调
• 任务大小：将工作分解为每个 5-15 分钟的任务——足够小以并行化，足够大以有意义
• 避免文件冲突：将不同的文件或目录分配给不同的 team 以防止合并冲突
• 从简单开始：首次团队使用进程内模式；熟悉后切换到分屏
• 清晰的任务描述：提供具体、可操作的任务描述，以便 team 可以独立工作

限制

• 实验性：功能行为可能在未来版本中更改
• 无会话恢复：进程内 team 在会话结束后无法恢复
• 每个会话一个团队：无法在单个会话中创建嵌套团队或多个团队
• 固定领导：团队负责人角色不能转移给 team
• 分屏限制：需要 tmux/iTerm2；在 VS Code 终端、Windows Terminal 或 Ghostty 中不可用
• 无跨会话团队：team 仅存在于当前会话中

警告：Agent Teams 是实验性的。首先使用非关键工作进行测试，并监控 team 协调是否有意外行为。

插件 Subagent 安全

插件提供的 subagents 具有受限的 frontmatter 功能以确保安全。以下字段不允许在插件 subagent 定义中使用：

• hooks - 不能定义生命周期钩子
• mcpServers - 不能配置 MCP 服务器
• permissionMode - 不能覆盖权限设置

这防止插件通过 subagent 钩子升级权限或执行任意命令。

架构

高层架构

    graph TB
    User["用户"]
    Main["主 Agent<br/>(协调者)"]
    Reviewer["代码审查<br/>Subagent"]
    Tester["测试工程师<br/>Subagent"]
    Docs["文档<br/>Subagent"]

    User -->|请求| Main
    Main -->|委派| Reviewer
    Main -->|委派| Tester
    Main -->|委派| Docs
    Reviewer -->|返回结果| Main
    Tester -->|返回结果| Main
    Docs -->|返回结果| Main
    Main -->|综合| User
  

Subagent 生命周期

    sequenceDiagram
    participant User
    participant MainAgent as 主 Agent
    participant CodeReviewer as 代码审查<br/>Subagent
    participant Context as 独立的<br/>上下文窗口

    User->>MainAgent: "构建新的认证功能"
    MainAgent->>MainAgent: 分析任务
    MainAgent->>CodeReviewer: "审查这段代码"
    CodeReviewer->>Context: 初始化全新上下文
    Context->>CodeReviewer: 加载审查指令
    CodeReviewer->>CodeReviewer: 执行审查
    CodeReviewer-->>MainAgent: 返回发现
    MainAgent->>MainAgent: 整合结果
    MainAgent-->>User: 提供综合结果
  

上下文管理

    graph TB
    A["主 Agent 上下文<br/>50,000 tokens"]
    B["Subagent 1 上下文<br/>20,000 tokens"]
    C["Subagent 2 上下文<br/>20,000 tokens"]
    D["Subagent 3 上下文<br/>20,000 tokens"]

    A -->|全新状态| B
    A -->|全新状态| C
    A -->|全新状态| D

    B -->|仅结果| A
    C -->|仅结果| A
    D -->|仅结果| A

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#fff9c4
    style D fill:#fff9c4
  

关键点

• 每个 subagent 获得一个全新的上下文窗口，没有主对话历史
• 只有相关上下文被传递给 subagent 用于其特定任务
• 结果被提炼回主 agent
• 这防止了长时间项目的上下文 token 耗尽

性能考虑

• 上下文效率 - agents 保护主上下文，支持更长的会话
• 延迟 - subagents 从全新状态开始，可能会增加收集初始上下文的延迟

关键行为

• 无嵌套生成 - subagents 不能生成其他 subagents
• 后台权限 - 后台 subagents 自动拒绝任何未预先批准的权限
• 后台化 - 按 Ctrl+B 将当前运行的任务放到后台
• 转录 - subagent 转录存储在 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
• 自动压缩 - subagent 上下文在约 95% 容量时自动压缩（可通过 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 环境变量覆盖）

何时使用 Subagents

最佳实践

设计原则

应该：

• 从 Claude 生成的 agents 开始 - 使用 Claude 生成初始 subagent，然后进行迭代自定义
• 设计专注的 subagents - 单一、清晰的职责，而不是一个做所有事情
• 编写详细的提示 - 包括具体指令、示例和约束
• 限制工具访问 - 仅授予 subagent 目的所需的工具
• 版本控制 - 将项目 subagents 纳入版本控制以进行团队协作

不应该：

• 创建具有相同角色的重叠 subagents
• 给 subagents 不必要的工具访问
• 对简单、单步骤任务使用 subagents
• 在一个 subagent 的提示中混合关注点
• 忘记传递必要的上下文

系统提示词最佳实践

1. 明确角色

   你是一个专注于[特定领域]的专家代码审查员

2. 清晰定义优先级

   审查优先级（按顺序）：
   1. 安全问题
   2. 性能问题
   3. 代码质量

3. 指定输出格式

   对于每个问题，提供：严重程度、类别、位置、描述、修复、影响

4. 包含操作步骤

   被调用时：
   1. 运行 git diff 查看最近的更改
   2. 专注于修改的文件
   3. 立即开始审查

工具访问策略

1. 从限制开始：仅从基本工具开始
2. 仅在需要时扩展：根据需求添加工具
3. 尽可能只读：为分析 agents 使用 Read/Grep
4. 沙盒执行：将 Bash 命令限制为特定模式

本目录中的示例 Subagents

此文件夹包含可直接使用的示例 subagents：

1. Code Reviewer（code-reviewer.md）

用途：全面的代码质量和可维护性分析

工具：Read、Grep、Glob、Bash

专长：

• 安全漏洞检测
• 性能优化识别
• 代码可维护性评估
• 测试覆盖率分析

使用场景：需要专注于质量和安全的自动化代码审查时

2. Test Engineer（test-engineer.md）

用途：测试策略、覆盖率分析和自动化测试

工具：Read、Write、Bash、Grep

专长：

• 单元测试创建
• 集成测试设计
• 边缘情况识别
• 覆盖率分析（目标 >80%）

使用场景：需要全面测试套件创建或覆盖率分析时

3. Documentation Writer（documentation-writer.md）

用途：技术文档、API 文档和用户指南

工具：Read、Write、Grep

专长：

• API 端点文档
• 用户指南创建
• 架构文档
• 代码注释改进

使用场景：需要创建或更新项目文档时

4. Secure Reviewer（secure-reviewer.md）

用途：专注于安全的代码审查，具有最小权限

工具：Read、Grep

专长：

• 安全漏洞检测
• 认证/授权问题
• 数据暴露风险
• 注入攻击识别

使用场景：需要没有修改能力的安全审计时

5. Implementation Agent（implementation-agent.md）

用途：功能开发的完整实现能力

工具：Read、Write、Edit、Bash、Grep、Glob

专长：

• 功能实现
• 代码生成
• 构建和测试执行
• 代码库修改

使用场景：需要 subagent 端到端实现功能时

6. Debugger（debugger.md）

用途：调试专家，用于错误、测试失败和意外行为

工具：Read、Edit、Bash、Grep、Glob

专长：

• 根本原因分析
• 错误调查
• 测试失败解决
• 最小修复实现

使用场景：遇到 bug、错误或意外行为时

7. Data Scientist（data-scientist.md）

用途：SQL 查询和数据分析专家

工具：Bash、Read、Write

专长：

• SQL 查询优化
• BigQuery 操作
• 数据分析和可视化
• 统计洞察

使用场景：需要数据分析、SQL 查询或 BigQuery 操作时

8. Clean Code Reviewer（clean-code-reviewer.md）

用途：专注于代码整洁性的代码审查

工具：Read、Grep、Glob

专长：

• 代码整洁性审查
• 最佳实践检查
• 代码风格一致性
• 可维护性评估

使用场景：需要按照整洁代码原则审查代码时

安装说明

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

/agents

然后：

1. 选择 “Create New Agent”
2. 选择项目级或用户级
3. 详细描述你的 subagent
4. 选择要授予访问权限的工具（或留空以继承所有）
5. 保存并使用

方法 2：复制到项目

将 agent 文件复制到项目的 .claude/agents/ 目录：

# 导航到你的项目
cd /path/to/your/project

# 如果 agents 目录不存在则创建
mkdir -p .claude/agents

# 从此文件夹复制所有 agent 文件
cp /path/to/07-subagents/*.md .claude/agents/

# 删除 README（在 .claude/agents 中不需要）
rm .claude/agents/README.md

方法 3：复制到用户目录

对于在所有项目中可用的 agents：

# 创建用户 agents 目录
mkdir -p ~/.claude/agents

# 复制 agents
cp /path/to/07-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/07-subagents/debugger.md ~/.claude/agents/
# ... 根据需要复制其他文件

验证

安装后，验证 agents 是否被识别：

/agents

你应该看到安装的 agents 与内置的 agents 一起列出。

文件结构

project/
├── .claude/
│   └── agents/
│       ├── clean-code-reviewer.md
│       ├── code-reviewer.md
│       ├── data-scientist.md
│       ├── debugger.md
│       ├── documentation-writer.md
│       ├── implementation-agent.md
│       ├── secure-reviewer.md
│       └── test-engineer.md
└── ...

相关概念

相关功能

• 斜杠命令 - 快速用户调用的快捷方式
• Memory - 持久的跨会话上下文
• Skills - 可重用的自主能力
• MCP 协议 - 实时外部数据访问
• Hooks - 事件驱动的 shell 命令自动化
• Plugins - 打包的扩展包

与其他功能的比较

集成模式

    graph TD
    User["用户请求"] --> Main["主 Agent"]
    Main -->|使用| Memory["Memory<br/>(上下文)"]
    Main -->|查询| MCP["MCP<br/>(实时数据)"]
    Main -->|调用| Skills["Skills<br/>(自动工具)"]
    Main -->|委派| Subagents["Subagents<br/>(专家)"]

    Subagents -->|使用| Memory
    Subagents -->|查询| MCP
    Subagents -->|隔离| Context["全新上下文<br/>窗口"]
  

其他资源

• 官方 Subagents 文档
• CLI 参考 - --agents 标志和其他 CLI 选项
• Plugins 指南 - 将 agents 与其他功能打包
• Skills 指南 - 自动调用的能力
• Memory 指南 - 持久上下文
• Hooks 指南 - 事件驱动的自动化

最后更新：2026年5月9日 Claude Code 版本：2.1.138 来源：

• https://code.claude.com/docs/en/sub-agents
• https://code.claude.com/docs/en/agent-teams
• https://github.com/anthropics/claude-code/releases/tag/v2.1.117
• https://github.com/anthropics/claude-code/releases/tag/v2.1.131
• https://github.com/anthropics/claude-code/releases/tag/v2.1.138 兼容模型：Claude Sonnet 4.6、Claude Opus 4.7、Claude Haiku 4.5