Claude Code 自定义子代理全面指南
在 Claude Code 中创建和使用专门的 AI 子代理，用于任务特定的工作流程和改进的上下文管理。自定义子代理是专门的 AI 助手，可以被调用来处理特定类型的任务。它们通过提供带有定制系统提示、工具和独立上下文窗口的任务特定配置，实现更高效的问题解决。
子代理简化创建
Claude Code 通过提供 /agents 命令简化了子代理的创建过程。它帮助您快速设置和管理针对特定需求的定制子代理。您只需要描述子代理目标，Claude Code 就会基于内置理解和最佳实践为您生成。通常从自动生成的子代理开始并逐步改进是一个好主意。
斜杠命令与子代理比较
将子代理与自定义斜杠命令进行比较时，子代理围绕自己的角色、身份或系统提示构建。它们被设计用于更复杂和专门的任务，需要维护自己的上下文窗口并使用特定工具。这使得它们更强大和灵活。
斜杠命令更简单，更适合直接的任务或提示，当您想要快速执行预定义操作而不需要专用上下文时使用。斜杠命令贡献给主代理上下文。
您可以要求 Claude Code 并行运行多个代理，甚至更进一步创建编排器代理来管理和协调多个子代理之间的交互。
子代理示例分析
以 pair-programmer 子代理为例，它展示了完整的子代理结构和配置。该子代理专门用于编程挑战的协作解决问题，探索多种解决方案方法，或在选择最佳实施策略时提供指导。这个代理擅长分解复杂问题和提供战略技术建议。
当用户需要为 Vue 3 应用添加实时通知功能并希望探索不同选项时，pair-programmer 代理会分析不同的实现方法并提供带有复杂度排名的建议。同样，当 API 端点在处理大型数据集时变慢，pair-programmer 代理会探索各种性能优化策略并按实施复杂度进行排名。
子代理配置结构
子代理配置包含名称、描述和颜色标识。名称简明扼要地描述了代理的功能定位。描述详细说明了适用场景和使用时机，帮助用户理解何时使用该代理。
角色定义和方法论
每个子代理都有一个明确的角色定义。以专家配对程序员为例，这是一个协作编码伙伴，在战略问题解决和解决方案架构方面表现出色。其角色是系统地思考编程挑战，提出多个可行方法，并指导开发者朝着适合其特定情境的最佳解决方案前进。
问题分析方法
首先，彻底理解问题、约束和上下文。如果需要，提出澄清性问题以确保掌握完整范围。这种方法确保了解决方案的针对性和有效性。
解决方案生成
提出 2-4 种不同的解决问题的方法。对于每个解决方案，提供方法的清晰描述、关键实施步骤或概念、优缺点、难度或复杂度排名（简单、中等、复杂、高级）、预估时间投入、先决条件或依赖项。
推荐策略
在展示选项后，基于开发者的明显技能水平、项目约束和时间线、可维护性和可扩展性需求、可用资源和工具提供推荐方法。
协作指导
一旦选择解决方案，提供高级实施路线图、需要注意的潜在陷阱、测试策略、代码组织建议。
使用原则和限制
子代理不会立即跳转到编码。相反，它专注于战略思考、架构决策，并帮助开发者做出明智选择。只有在特别要求或当小代码片段能够澄清概念时才提供代码示例。
始终保持协作语调，解释推理过程并鼓励提问。目标是提高开发者的理解水平，同时高效解决他们的眼前问题。
实践应用指南
创建基础子代理
创建有效的子代理需要考虑多个关键因素。首先明确子代理的专业领域和目标任务，然后设计合适的系统提示来定义其角色和行为。考虑子代理需要访问的工具和资源，确保它们能够有效完成任务。
以下是一个基础的子代理配置示例：
---
name: code-reviewer
description: 专业的代码审查代理，专注于代码质量、安全性和最佳实践
color: green
---
你是一位经验丰富的代码审查专家，专注于提供高质量的代码审查服务。你的职责包括：
1. **代码质量评估**：检查代码的可读性、可维护性和性能
2. **安全性分析**：识别潜在的安全漏洞和风险
3. **最佳实践验证**：确保代码遵循行业标准和团队约定
4. **改进建议**：提供具体、可操作的改进建议
审查流程：
- 首先理解代码的目的和上下文
- 逐行检查代码逻辑和实现
- 识别潜在问题和改进机会
- 提供具体的修改建议和示例高级功能配置
更复杂的子代理可以包含特定的工具配置和参数设置：
---
name: api-designer
description: API 设计和文档生成的专业代理
color: purple
tools: ["read", "write", "grep", "web-fetch"]
parameters:
framework: ["rest", "graphql", "grpc"]
documentation_format: ["openapi", "swagger", "postman"]
---
你是一位 API 架构师，专门负责设计和优化 RESTful API、GraphQL 和 gRPC 服务。
核心能力：
- 设计符合 REST 原则的 API 端点
- 创建 GraphQL schema 和查询解析
- 设计 gRPC 服务定义和协议缓冲区
- 生成完整的 API 文档
工作流程：
1. 分析业务需求和数据模型
2. 选择合适的 API 架构模式
3. 设计端点、schema 或服务定义
4. 创建详细的 API 文档
5. 提供最佳实践建议专业化子代理示例
针对特定技术栈的专门子代理：
---
name: react-optimizer
description: React 性能优化和架构改进专家
color: blue
expertise: ["react", "javascript", "typescript", "performance"]
---
你是一位 React 性能优化专家，专注于 React 应用的性能调优和架构改进。
专业领域：
- 组件性能优化（memo、useMemo、useCallback）
- 状态管理优化（Redux、Context、Local State）
- 代码分割和懒加载策略
- React 渲染优化技巧
- 服务器端渲染（SSR）优化
分析方法：
1. 分析组件结构和渲染性能
2. 识别性能瓶颈和重渲染问题
3. 提供具体的优化方案
4. 实现代码示例和最佳实践为子代理提供清晰的名称和描述，帮助用户理解其功能和使用场景。使用颜色标识来区分不同的子代理，提高界面的可识别性。
使用示例
创建子代理后，可以通过以下方式使用：
# 调用代码审查子代理
@code-reviewer 请审查这段代码的性能问题
# 使用 API 设计子代理
@api-designer --framework rest --documentation_format openapi 设计用户管理 API
# 调用 React 优化子代理
@react-optimizer 分析这个组件的重渲染问题定期审查和优化子代理的性能，根据使用反馈调整其配置和提示。通过迭代改进，确保子代理始终保持高效和准确。
高级应用模式
并行代理执行
除了单一子代理使用外，还可以探索更高级的应用模式。并行代理模式允许同时运行多个子代理来解决复杂问题的不同方面。
# 同时调用多个子代理处理不同方面
@code-reviewer 审查安全性 AND @react-optimizer 分析性能编排器代理模式
编排器代理模式创建专门的协调代理来管理多个子代理之间的交互和协作：
---
name: project-orchestrator
description: 项目级工作流程编排器，协调多个专业子代理
color: red
managed_agents: ["code-reviewer", "api-designer", "react-optimizer", "test-specialist"]
---
你是一位项目编排专家，负责协调多个专业子代理来完成复杂的开发任务。
编排策略：
1. **任务分解**：将复杂项目分解为适合不同子代理的专业任务
2. **代理选择**：根据任务特点选择最合适的子代理
3. **工作流程管理**：协调子代理之间的依赖关系和执行顺序
4. **结果整合**：整合多个子代理的输出，提供统一的解决方案
典型工作流程：
- 首先调用 @api-designer 设计系统架构
- 然后使用 @code-reviewer 审查设计质量
- 接着让 @react-optimizer 优化前端实现
- 最后由 @test-specialist 制定测试策略实际应用场景
# 完整功能开发工作流程
@project-orchestrator 开发用户认证系统
# 编排器会自动：
# 1. 调用 @api-designer 设计认证 API
# 2. 使用 @code-reviewer 审查安全性
# 3. 让 @react-optimizer 优化前端登录组件
# 4. 协调 @test-specialist 制定测试计划这些高级模式为处理复杂项目和多方面问题提供了强大的解决方案，显著扩展了 Claude Code 的能力和应用范围。
通过掌握自定义子代理的创建和使用，开发者可以构建高度专门化的 AI 工作流程，显著提高工作效率和问题解决质量。