Published on

Claude Code Subagents 指南：构建智能化开发团队的新范式

Authors
  • avatar
    Name
    青雲
    Twitter

Claude Code 的 Subagents（子代理） 功能，让你能从“单打独斗”的通用AI助手，转变为拥有一个专业化AI团队的“项目指挥官”。这对于处理复杂或多阶段的任务尤其有用。

Subagents 是什么？

Subagents 是 Claude Code 中可以由你自定义的、专注于特定任务的 AI 助手。每个子 agent 都拥有：

  • 独立的上下文窗口：与主对话隔离，专用于自己的任务，避免相互干扰。
  • 定制的系统提示词：根据其角色和任务进行精细调教，定义其专业知识、行为规范和工作流程。
  • 特定的工具权限：可以精确控制每个子代理能使用哪些工具（如文件读写、执行命令等），实现更精细的安全管理。
  • 明确的触发条件：通过描述字段定义何时调用，Claude 会根据任务内容自动路由，你也可以显式调用。

如何创建与管理 Subagents

创建和管理 Subagents 主要有两种方式：

  1. 使用交互式命令（推荐）：

在 Claude Code 中输入 /agents 命令，会打开一个交互式管理界面。在这里你可以查看、创建、编辑或删除子代理。

  1. 直接管理配置文件：

Subagents 本质上是存储在特定目录下的 Markdown 文件（带有 YAML frontmatter）。你可以手动创建或编辑这些文件。

  • 项目级子代理：存储在项目目录的 .claude/agents/ 下，仅对该项目有效。

  • 用户级子代理：存储在 ~/.claude/agents/ 下，对你的所有项目都有效。当名称冲突时，项目级Subagents优先于用户级。

一个子代理的配置文件通常如下所示：

---
name: code-reviewer # 唯一标识符
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Glob, Bash # 可选：指定可用的工具，省略则继承所有
model: sonnet # 可选：指定模型
color: blue # 可选：终端显示颜色
---

# 这里是系统提示词（System Prompt）
你是一个资深的代码审查专家，确保代码质量和安全性。

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

审查清单：
- 代码简单且可读
- 函数和变量命名良好
- 没有重复代码
- 适当的错误处理
- 没有暴露的密钥或API密钥
- 实施了输入验证
- 良好的测试覆盖率
- 考虑了性能问题

按优先级提供反馈：
- 关键问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

Subagents 的使用方式

  • 自动委派：Claude Code 会根据你请求中的任务描述、当前上下文以及各子代理配置中的 description 字段，自动判断并将任务委派给最合适的子代理。
  • 显式调用：你也可以在对话中明确指定使用某个子代理，例如：“让 code-reviewer 检查我最近的提交” 或 @code-reviewer 请审查这个函数的安全性 。

Subagents 的核心优势

  1. 上下文隔离与保护：这是最核心的优势之一。通过将特定任务隔离到独立的子代理中，可以防止主对话的上下文窗口被无关信息填满，让你的主会话始终聚焦于更高层次的战略目标，有效解决了大型项目中上下文混乱的问题。
  2. 专业化与高质量输出：每个子代理都可以通过精心设计的系统提示词，在特定任务上表现得远超通用模型，提供更专业、更准确的建议。
  3. 灵活的权限控制：你可以为不同子代理配置不同的工具访问权限。例如，只授予“代码审查”子代理读取文件的权限，而不给它执行代码或写入的权限，从而实现更精细化的安全管理。
  4. 可复用性与团队共享：一旦创建了一个高效的子代理，它就可以在不同的项目中重复使用。项目级的子代理还可以通过版本控制（如 Git）与团队成员共享，确保整个团队工作流的一致性和高效性。
  5. 并行处理潜力：理论上，可以启动多个子代理同时处理不同方面的任务，这在复杂项目开发中特别有用。

常见的 Subagents 类型与应用场景

你可以根据开发流程中的不同角色和任务创建各种子代理：

代理类型主要职责常用工具权限应用场景
strategic-planner不写代码，只输出需求、技术方案file_edit, web_search需求翻译、技术方案、任务拆解
code-reviewr检查代码质量、安全性、可维护性，提出改进建议Read, Grep, Glob提交前检查、代码复审
测试专家编写测试用例、运行测试、修复失败的测试Read, Write, Edit, Bash测试驱动开发、持续集成
FE 开发专家专注于UI组件、样式、交互逻辑开发Read, Write, Edit构建用户界面、响应式设计
后端/架构专家设计API、数据库结构、系统架构Read, Grep系统设计、技术选型
调试专家分析错误日志、诊断问题、应用修复Read, Bash, Grep故障排除、性能优化
文档工程师编写和维护技术文档、API文档、生成项目说明Read, Write项目文档化、知识管理

使用 Subagents 的注意事项

  1. Token 消耗：使用子代理通常会比普通对话消耗更多 Token，因为每个子代理都有独立的上下文和可能更长的提示词。但这往往能换来更专业的结果和更高的效率。
  2. 提示词质量：子代理的表现高度依赖其系统提示词的质量。提示词需要清晰、详细地定义角色、目标、工作流程和约束条件。
  3. 路由准确性：虽然 Claude 的自动路由机制大多时候很准确，但偶尔也可能选错子代理。在关键任务中，显式调用是更可靠的选择。
  4. 模型选择：对于复杂的架构设计或代码审查，可以使用能力更强的模型；对于简单的格式化或文档生成任务，可以使用更经济快速的模型以节省成本。

监控和调试

  1. 进度跟踪
"请报告各个agent的执行状态：
- @backend-dev 的API开发进度
- @frontend-dev 的UI组件完成情况  
- @tester 的测试覆盖率"
  1. 结果验证
"在所有agent完成后，用@validator检查：
- 代码质量是否达标
- 测试是否通过
- 文档是否完整"

高阶用法

链式编排

正在加载图表...
# 1. 数据处理 → 2. 分析 → 3. 报告生成
"首先用数据处理agent清理数据，然后用分析agent进行统计分析，最后用报告agent生成可视化报告"

实际配置示例：

# data-processor.md
---
name: data-processor
description: PROACTIVELY processes and cleans raw data files. MUST BE USED for any data preprocessing tasks.
tools: edit_file, create_file, run_command
---

# data-analyzer.md  
---
name: data-analyzer
description: PROACTIVELY performs statistical analysis on cleaned data. MUST BE USED after data preprocessing.
tools: run_command, create_file, edit_file
---

# report-generator.md
---
name: report-generator  
description: PROACTIVELY creates visual reports and summaries. MUST BE USED for final report generation.
tools: create_file, edit_file, run_command
---

并行编排

同时处理多个独立任务

正在加载图表...
# 明确指示需要并行处理
"同时进行以下任务：1) 用测试agent运行单元测试，2) 用文档agent更新README，3) 用安全agent检查漏洞"

条件分支编排

基于结果的动态编排。

正在加载图表...
"首先用@code-analyzer分析代码复杂度，如果复杂度高于阈值，则启用@refactor-expert进行重构建议，否则直接用@optimizer进行性能优化"

Web 应用开发流水线

创建专业方向的 agent

# frontend-dev.md
---
name: frontend-dev
description: PROACTIVELY handles React/Vue frontend development tasks
tools: create_file, edit_file, run_command
---

# backend-dev.md  
---
name: backend-dev
description: PROACTIVELY develops API endpoints and server logic
tools: create_file, edit_file, run_command
---

# database-dev.md
---
name: database-dev
description: PROACTIVELY designs and manages database schemas
tools: create_file, edit_file, run_command
---

# devops-agent.md
---
name: devops-agent
description: PROACTIVELY handles deployment and infrastructure setup
tools: run_command, create_file, edit_file
---

并发编排命令

"开始全栈开发：
1. 并行开发：
   - @frontend-dev 创建React组件和页面
   - @backend-dev 开发REST API
   - @database-dev 设计数据库模式
   
2. 集成阶段：
   - @devops-agent 配置开发环境和CI/CD"
正在加载图表...

其他技巧

  1. 显式上下文传递
"用@data-processor处理数据后，将结果路径传递给@ml-trainer：'使用{data_processor_output_path}的数据训练模型'"
正在加载图表...
  1. 错误处理和重试
"执行测试流程，如果@unit-tester失败，则：
1. 先用@debugger分析失败原因
2. 用@code-fixer修复问题  
3. 重新运行@unit-tester"
正在加载图表...
  1. 动态工具分配：根据任务复杂度分配工具
# simple-tasks.md
---
name: simple-tasks
description: Handles basic file operations and simple code changes
tools: edit_file, create_file
---

# complex-tasks.md
---  
name: complex-tasks
description: Handles complex development requiring full tool access
# 省略tools字段以继承所有工具
---

性能优化

  1. 合理分组并发任务

good

# 独立任务可以并发
"同时运行测试和生成文档"

bad

# 有依赖关系的任务不应并发
"同时编译代码和运行编译后的程序" # ❌ 错误
  1. 上下文管理

保持各sub agent职责清晰

# 明确指定每个agent的输入输出
"@analyzer处理data.csv并输出analysis.json，然后@reporter读取analysis.json生成report.html"
  1. 工具权限优化：最小权限原则
  • 只读任务的agent不需要写权限
  • 特定文件类型的agent限制相关工具

总结

通过这些编排策略，您可以充分发挥Claude Code subagents的协作能力，实现高效的并行开发和自动化工作流。关键是要根据任务的依赖关系合理安排串行和并行执行，同时确保各个agent之间的职责清晰和上下文传递准确。

开源 subagents

项目一句话定位代理数量/规模核心功能技术栈支持安装/使用方式特色亮点
wshobson/agents官方 75 个 Claude Code agents库75 个固定subagents（Haiku 15 / Sonnet 44 / Opus 15）按领域自动或显式调用；内置多代理工作流通用，覆盖开发、运维、数据、AI、业务等git clone 到 ~/.claude/agents/ 即用官方出品、模型分层、零配置开箱即用
awesome-claude-code-agents社区精选子代理 & 资源清单精选 8+ agents + 3 个编排框架收录优质第三方代理与 MCP 示例不限浏览 README，按需复制代理文件众包持续更新、MCP 友好、一键贡献
claude_code_agent_farm多 agents 代理集合默认 20，可扩至 50 并发bug 修复 / 最佳实践落地 / 协同重构34 条技术栈（Next.js、Python、Rust、Go…）./setup.sh 一键安装；claude-code-agent-farm 命令启动实时 tmux/HTML 监控、自动备份与锁机制、24 个工具脚本、高度可配
Discuss on Twitter • View on GitHub