青雲的博客

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

· 16 分钟阅读
AI Claude Subagents 开发工具 AI编程助手 团队协作 自动化开发

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检查：
- 代码质量是否达标
- 测试是否通过
- 文档是否完整"

高阶用法

链式编排

flowchart LR
    A[原始数据] --> B[data-processor]
    B --> C[清理后数据]
    C --> D[data-analyzer]
    D --> E[分析结果]
    E --> F[report-generator]
    F --> G[可视化报告]
    
    style B fill:#e1f5fe
    style D fill:#e8f5e8
    style F fill:#fff3e0
# 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
---

并行编排

同时处理多个独立任务

flowchart TD
    A[项目代码库] --> B[test-runner]
    A --> C[doc-updater]
    A --> D[security-scanner]
    A --> E[performance-analyzer]
    
    B --> F[测试报告]
    C --> G[更新文档]
    D --> H[安全报告]
    E --> I[性能报告]
    
    style B fill:#e1f5fe
    style C fill:#e8f5e8
    style D fill:#ffebee
    style E fill:#fff3e0
# 明确指示需要并行处理
"同时进行以下任务：1) 用测试agent运行单元测试，2) 用文档agent更新README，3) 用安全agent检查漏洞"

条件分支编排

基于结果的动态编排。

flowchart TD
    A[代码库] --> B[code-analyzer]
    B --> C{复杂度检查}
    C -->|高复杂度| D[refactor-expert]
    C -->|低复杂度| E[optimizer]
    
    D --> F[重构建议]
    E --> G[性能优化]
    
    F --> H[优化后代码]
    G --> H
    
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#ffebee
    style E fill:#e8f5e8
"首先用@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"

flowchart TD
    A[项目需求] --> B[并行开发阶段]
    
    B --> C[frontend-dev]
    B --> D[backend-dev]
    B --> E[database-dev]
    
    C --> F[React组件]
    D --> G[REST API]
    E --> H[数据库模式]
    
    F --> I[集成阶段]
    G --> I
    H --> I
    
    I --> J[devops-agent]
    J --> K[开发环境]
    J --> L[CI/CD流水线]
    
    K --> M[完整Web应用]
    L --> M
    
    style B fill:#f3e5f5
    style I fill:#e8f5e8
    style M fill:#fff3e0

其他技巧

  1. 显式上下文传递
"用@data-processor处理数据后，将结果路径传递给@ml-trainer：'使用{data_processor_output_path}的数据训练模型'"
flowchart LR
    A[原始数据] --> B[data-processor]
    B --> C[处理结果]
    B -.-> D[输出路径信息]
    
    D --> E[ml-trainer]
    C --> E
    E --> F[训练好的模型]
    
    style B fill:#e1f5fe
    style D fill:#fff3e0,stroke:#ff9800,stroke-width:2px,stroke-dasharray: 5 5
    style E fill:#e8f5e8
  1. 错误处理和重试
"执行测试流程，如果@unit-tester失败，则：
1. 先用@debugger分析失败原因
2. 用@code-fixer修复问题  
3. 重新运行@unit-tester"
flowchart TD
    A[代码库] --> B[unit-tester]
    B --> C{测试结果}
    C -->|成功| D[测试通过]
    C -->|失败| E[debugger]
    
    E --> F[错误分析]
    F --> G[code-fixer]
    G --> H[修复代码]
    H --> B
    
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style E fill:#ffebee
    style G fill:#e8f5e8
    style D fill:#c8e6c9
  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 个工具脚本、高度可配

相关文章

Claude Code 使用技巧

既然 AI Coding 有了 IDE，为什么还要有 CLI？

从"AI编程助手"到"AI开发团队"：BMAD METHOD如何重新定义AI驱动开发

评论