1. Claude Code子代理系统概述
在代码分析和自动化处理领域,Claude Code的子代理系统是一个革命性的设计。这套系统通过将复杂任务分解给专门的"小助手"来完成,大幅提升了处理效率和专业性。想象一下,当你面对一个庞大的代码库时,不再需要自己逐行查找,而是有一组训练有素的助手各司其职——这正是子代理系统带来的核心价值。
子代理系统主要分为两大类型:内置子代理和自定义子代理。内置子代理是Claude Code预先配置好的专业助手,而自定义子代理则允许用户根据特定需求打造专属工具。这种架构设计使得系统既开箱即用,又具备高度可扩展性。
提示:子代理的核心设计理念是"专业分工"——每个子代理专注于单一职责,通过组合使用可以完成复杂任务。
2. 内置子代理详解
2.1 Explore子代理:代码库的导航专家
Explore子代理相当于代码库的专职导航员,它的核心能力是快速定位代码位置。当你在一个拥有数千个文件的代码库中寻找特定功能实现时,Explore子代理能像专业侦探一样高效工作。
技术实现上,Explore子代理使用了优化的代码索引和搜索算法。它不会简单地进行全文搜索,而是会分析代码结构、调用关系,甚至理解代码语义。例如,当询问"认证逻辑在哪里"时,它会优先检查常见的认证模块位置(如auth/目录),而不是盲目搜索整个代码库。
典型工作流程:
- 接收搜索请求(如"查找用户登录逻辑")
- 分析请求语义,确定可能的代码位置
- 使用Grep和Glob工具进行针对性搜索
- 对结果进行相关性排序
- 返回最可能匹配的代码片段
模式选择建议:
- quick模式:适用于简单定位,响应最快
- medium模式:平衡速度和准确性,日常推荐
- very thorough模式:全面搜索,用于关键任务
2.2 Plan子代理:变更设计的架构师
Plan子代理是代码修改前的规划专家。它会在实际改动前全面分析变更影响,避免"动手后发现改错了地方"的尴尬局面。这个子代理特别适合大型重构或复杂功能开发场景。
Plan子代理的工作方式类似于经验丰富的技术主管。它会:
- 收集相关代码的完整上下文
- 分析代码依赖关系
- 识别潜在风险点
- 生成分步实施计划
实际案例:
假设你要修改一个API接口的返回结构,Plan子代理会:
- 找出所有调用该API的客户端代码
- 检查是否有缓存需要同步更新
- 评估是否需要版本兼容处理
- 建议修改顺序和测试策略
注意:Plan子代理的一个重要限制是不能生成新的子代理,这是为了防止无限递归调用导致的系统资源耗尽。
2.3 General-purpose子代理:全能型开发助手
General-purpose子代理是Claude Code中的"瑞士军刀",它集成了代码读取、修改和系统操作等全方位能力。这个子代理最适合需要多步骤协作的复杂开发任务。
典型应用场景:
- 实现一个新功能,需要同时修改多个文件
- 修复涉及多个模块的复杂bug
- 执行需要代码修改和系统配置的部署任务
与专用子代理不同,General-purpose子代理可以自由使用完整的工具集,包括:
- 代码读写(Read/Write/Edit)
- 系统操作(Bash)
- 文件管理(Glob)
- 代码搜索(Grep)
使用技巧:
- 对于简单任务,优先使用专用子代理(更高效)
- 复杂任务开始时明确目标,避免子代理"迷失方向"
- 定期检查进展,必要时调整任务分解方式
3. 自定义子代理创建方法
3.1 子代理级别与优先级
自定义子代理可以设置不同的作用域级别,当多个级别的同名子代理存在时,系统会按照优先级选择。理解这个机制对于团队协作特别重要。
级别类型:
- 用户级(User-level):仅对当前用户可见
- 项目级(Project-level):对特定项目所有成员可见
- 会话级(Session-level):仅当前会话有效
优先级顺序为:会话级 > 项目级 > 用户级。这种设计允许用户在特定场景下临时覆盖团队共享的子代理配置。
3.2 交互式创建方法(推荐新手)
交互式创建是最直观的子代理定义方式,特别适合刚开始接触Claude Code的用户。整个过程就像有一个专业的向导在一步步引导你。
详细步骤解析:
-
启动创建流程:
在Claude Code界面输入/agents命令,系统会显示子代理管理菜单。 -
选择创建类型:
选择"Create new agent"选项,系统会询问是要创建全新子代理还是基于模板创建。 -
设置作用域:
需要决定子代理的可见范围:- User-level:个人使用,不会影响他人
- Project-level:团队共享,需要相应权限
-
定义功能:
选择"Generate with Claude"后,用自然语言描述你想要的子代理功能。例如:
"我需要一个专注于React组件性能优化的子代理,它能分析组件渲染次数、识别不必要的重渲染,并建议优化方案。" -
工具选择:
系统会根据功能描述推荐工具集,你可以调整:- 性能分析:Read、Grep
- 渲染跟踪:Bash(运行分析脚本)
- 不建议:Write、Edit(只读分析更安全)
-
模型选择:
对于性能分析这类需要精确度的任务,建议选择能力更强的模型(如Sonnet)。 -
保存配置:
确认所有设置后,系统会生成子代理的Markdown配置文件并保存到相应位置。
优势分析:
- 无需了解技术细节即可创建专业子代理
- 系统会自动生成优化的prompt和配置
- 即时反馈和调整,所见即所得
3.3 手动配置文件方法
对于高级用户,直接编辑配置文件可以提供更精细的控制。这种方法特别适合需要版本控制、团队共享或复用现有配置的场景。
文件结构规范:
- 存储位置:
.claude/agents/目录下 - 文件名:
[agent-name].md - 文件格式:YAML frontmatter + Markdown内容
配置示例:
markdown复制---
name: react-perf-analyzer
description: Analyze and identify React component performance issues, focusing on unnecessary re-renders and optimization opportunities. Use when performance tuning React applications.
tools: Read, Grep, Bash
model: sonnet
permissionMode: plan
skills:
- react-performance
- react-hooks-best-practices
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-perf-script.sh"
---
# React性能分析专家
## 工作流程
1. 识别目标组件
2. 分析渲染行为
3. 追踪状态变化
4. 识别优化机会
## 输出格式
### 分析结果
- 组件: [组件名]
- 渲染次数: [数字]
- 主要触发原因: [列表]
- 优化建议: [列表]
关键技巧:
- 使用版本控制系统管理配置文件
- 建立团队命名规范(如
[team]-[功能]-[环境]) - 开发共享配置库,避免重复劳动
- 添加充分的注释说明配置项用途
3.4 CLI临时创建方法
CLI方式适合自动化场景,比如CI/CD流水线中的定制化代码检查。这种方式创建的子代理不会持久化,特别适合一次性任务。
典型使用场景:
- 自动化测试中的专用检查
- 临时性的批量代码修改
- 特定环境下的诊断分析
使用示例:
bash复制claude-code --agents '{
"name": "security-scan",
"description": "Run security checks before deployment",
"tools": ["Read", "Grep"],
"model": "sonnet",
"permissionMode": "plan"
}'
优势分析:
- 无需预先配置,即时生效
- 完美集成到自动化流程中
- 不会污染正式环境配置
- 可以根据运行时参数动态调整
4. 子代理配置深度解析
4.1 description字段的设计艺术
description字段是子代理配置中最重要的部分,它决定了子代理何时以及如何被调用。一个好的description应该像精准的API文档一样清晰。
不良示例分析:
code复制description: A code reviewer
问题:过于模糊,系统无法确定何时应该调用这个子代理。
优化后的示例:
code复制description: Review JavaScript code for security vulnerabilities and best practices, with focus on React hooks usage and async operations. Automatically triggered after code changes or when user explicitly requests review.
这个优化的description:
- 明确了技术栈(JavaScript,特别是React)
- 指出了专注领域(安全性和最佳实践)
- 说明了触发条件(代码变更后或用户请求时)
- 包含了专业术语(hooks,async operations)帮助精准匹配
设计原则:
- 包含"做什么"和"何时用"两个关键信息
- 使用领域专业术语提高匹配精度
- 可以包含触发关键词如"proactively"、"automatically"
- 避免过于宽泛的描述
4.2 工具权限控制策略
工具权限管理是子代理安全使用的关键。Claude Code提供了灵活的白名单和黑名单机制,适应不同场景的需求。
白名单模式示例:
code复制tools: Read, Grep
适用场景:代码审查、静态分析等只读操作
黑名单模式示例:
code复制disallowedTools: Write, Edit, Bash
适用场景:需要大部分工具但排除高风险操作
工具组合建议:
| 任务类型 | 推荐工具组合 | 权限模式 |
|---|---|---|
| 代码审查 | Read, Grep | plan |
| 自动化测试 | Read, Write, Bash | execute |
| 部署脚本 | Read, Bash | execute |
| 性能分析 | Read, Grep, Glob | plan |
| 重构助手 | Read, Write, Edit, Grep | execute-review |
最小权限原则实践:
- 从最严格的权限开始(如只读)
- 只有当明确需要时才添加更多权限
- 定期审查权限配置,移除不再需要的工具
- 对高风险工具(如Bash)设置额外hook验证
4.3 模型选择策略
Claude Code支持为不同子代理选择不同的AI模型,合理的模型选择可以平衡性能和成本。
模型对比分析:
| 模型类型 | 处理能力 | 响应速度 | 适合场景 | 成本 |
|---|---|---|---|---|
| Haiku | 基础 | 最快 | 简单搜索、常规检查 | 低 |
| Sonnet | 平衡 | 中等 | 代码分析、复杂查询 | 中 |
| Opus | 最强 | 较慢 | 复杂设计、系统架构规划 | 高 |
选择建议:
- 对延迟敏感的任务选择轻量级模型
- 需要深度分析的任务选择能力更强的模型
- 可以先用小模型快速验证,必要时切换到更大模型
- 在配置中注明选择理由,方便后续优化
4.4 permissionMode详解
permissionMode提供了系统级的权限保障,比单纯依赖prompt约束更可靠。
模式对比:
| 模式 | 描述 | 适用场景 |
|---|---|---|
| plan | 完全只读,即使有写权限也无法修改 | 代码审查、分析 |
| execute-review | 可以执行但需要人工确认 | 高风险操作、生产环境变更 |
| execute | 直接执行 | 自动化测试、低风险任务 |
| inherit | 继承主对话权限 | 需要与主对话保持一致的场景 |
配置示例:
code复制permissionMode: execute-review
这种配置下,子代理可以提出修改建议,但实际执行前需要人工确认,完美平衡了效率和安全性。
4.5 skills预加载机制
skills字段允许子代理启动时就具备特定领域的专业知识,而不需要每次运行时重新学习。
典型skill类型:
- 领域知识(如React最佳实践)
- 公司规范(如代码风格指南)
- 技术栈细节(如内部框架文档)
- 历史经验(如常见错误案例)
配置技巧:
- 保持skill的单一职责原则
- 为skill设计清晰的版本号
- 建立skill文档,说明适用场景和内容概要
- 定期更新skill内容
示例:
code复制skills:
- react-performance-2024
- company-security-guidelines-v2
4.6 hooks安全机制
hooks为子代理提供了细粒度的行为控制,可以在关键操作前后插入验证逻辑。
常见hook类型:
- PreToolUse:工具使用前验证
- PostToolUse:工具使用后检查
- PreAgentCall:子代理调用前验证
- PostAgentCall:子代理调用后处理
高级应用示例:
code复制hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: regex
pattern: "^rm -rf"
action: reject
message: "Dangerous delete operation blocked"
- matcher: "Write"
hooks:
- type: path
pattern: "src/core/**"
action: require-review
message: "Core module modification requires approval"
这个配置实现了:
- 拦截危险的删除命令
- 对核心模块的修改要求额外审核
- 提供清晰的拦截反馈信息
5. 子代理设计最佳实践
5.1 职责单一原则
优秀的子代理应该像Unix哲学倡导的那样:做好一件事。避免创建"全能"子代理,而是通过组合多个单一职责的子代理来完成复杂任务。
反面案例:
code复制name: do-everything
description: Handle code review, refactoring, testing and deployment
优化方案:
- code-reviewer:专注代码审查
- refactoring-helper:负责重构建议
- test-automator:处理测试相关任务
- deployment-manager:管理部署流程
5.2 接口设计清晰
子代理的输入输出接口应该明确、简洁,便于其他子代理或主对话使用。
好的接口设计:
code复制## 输入规范
- 目标组件名称或文件路径
- 可选:特定分析维度(渲染性能、状态管理等)
## 输出格式
### 分析报告
- 组件: [名称]
- 问题: [描述]
- 严重程度: [高/中/低]
- 修复建议: [具体方案]
5.3 错误处理设计
完善的错误处理机制能让子代理更健壮,特别是在自动化流程中。
错误处理要素:
- 明确的错误代码体系
- 可操作的错误信息
- 恢复或重试建议
- 错误级别分类(警告、错误、致命)
示例:
code复制## 错误代码
- E001: 目标文件不存在
- E002: 缺少必要分析工具
- W001: 分析结果置信度低
## 处理建议
- E001: 检查文件路径是否正确
- E002: 安装缺失工具或切换分析模式
- W001: 建议人工复核分析结果
5.4 性能考量
子代理设计需要考虑执行效率,特别是会被频繁调用的子代理。
优化策略:
- 缓存常用查询结果
- 支持增量分析
- 提供快速/完整两种模式
- 记录性能指标持续优化
配置示例:
code复制---
name: fast-analyzer
description: Quick code analysis with caching
tools: Read, Grep
options:
cacheTTL: 300 # 5分钟缓存
fastMode: true # 优先速度而非精度
---
5.5 文档与示例
完善的文档能大幅提高子代理的可用性和维护性。
文档内容建议:
- 使用场景说明
- 典型输入输出示例
- 常见问题解答
- 版本变更记录
文档位置:
- 配置文件中的注释
- 项目Wiki页面
- 示例代码库
- 团队知识管理系统
6. 实战案例解析
6.1 代码审查子代理实现
让我们实现一个完整的代码审查子代理,展示如何应用前述各种技术。
配置文件:
markdown复制---
name: ts-code-reviewer
description: Review TypeScript code for common issues including type safety, async handling and error management. Trigger automatically on file save or when review is requested.
tools: Read, Grep
model: sonnet
permissionMode: plan
skills:
- typescript-best-practices
- common-ts-anti-patterns
hooks:
PreToolUse:
- matcher: "Grep"
hooks:
- type: rate-limit
callsPerMinute: 30
---
# TypeScript代码审查专家
## 审查重点
1. 类型安全(any滥用,隐式any等)
2. 异步处理(未捕获的Promise,await缺失等)
3. 错误处理(吞没错误,不完整的try-catch等)
4. 代码组织(循环复杂度,函数长度等)
## 工作流程
1. 识别变更文件
2. 分层级检查(语法→类型→逻辑)
3. 生成问题报告
4. 提供修复建议
## 输出示例
### 审查结果: user-service.ts
- 问题: 未处理的Promise (L45)
严重程度: 高
建议: 添加catch处理或使用try-catch包裹
- 问题: 隐式any类型 (L12)
严重程度: 中
建议: 明确定义参数类型
设计亮点:
- 限定了TypeScript特定场景
- 设置了速率限制防止滥用
- 内置了专业知识库
- 提供了清晰的输出格式
6.2 自动化测试子代理
这个子代理专注于自动化测试相关任务,展示如何平衡权限和安全。
配置文件:
markdown复制---
name: test-automator
description: Handle test-related tasks including running tests, generating test cases and analyzing coverage. Trigger when test files are modified or test command is issued.
tools: Read, Write, Bash
model: sonnet
permissionMode: execute-review
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: path
pattern: "test/**"
action: allow
- type: default
action: require-review
---
# 测试自动化专家
## 能力范围
1. 执行测试套件
2. 生成测试用例
3. 分析覆盖率
4. 识别测试漏洞
## 安全限制
- 只能直接操作test目录下的文件
- 其他目录操作需要人工确认
- 禁止系统级命令(如安装依赖)
## 使用示例
输入: "为UserService添加登录失败测试"
输出:
1. 生成3个测试用例
2. 修改user-service.test.ts
3. 执行相关测试
4. 报告覆盖率变化
安全设计:
- 限制Bash命令执行范围
- 关键操作需要确认
- 清晰的权限边界定义
- 操作完全可追溯
6.3 CI/CD集成子代理
这个案例展示如何在CI/CD流水线中使用临时子代理进行定制化检查。
CLI调用示例:
bash复制claude-code --agents '{
"name": "pre-deploy-check",
"description": "Run critical checks before production deployment",
"tools": ["Read", "Grep"],
"model": "sonnet",
"permissionMode": "plan",
"hooks": {
"PreToolUse": [
{
"matcher": "Grep",
"hooks": [
{
"type": "content",
"pattern": "TODO|FIXME",
"action": "reject",
"message": "Pending TODOs found, blocking deployment"
}
]
}
]
}
}' --task "verify release readiness"
流程说明:
- 创建临时子代理
- 扫描代码中的TODO/FIXME标记
- 发现即阻断部署
- 生成详细报告
集成优势:
- 无需预先配置
- 完全自动化
- 严格的检查标准
- 清晰的阻断原因
7. 常见问题与解决方案
7.1 子代理不被调用怎么办?
诊断步骤:
- 检查description是否清晰说明了使用场景
- 验证触发条件是否满足
- 查看是否有更高优先级的同名子代理
- 检查工具权限是否足够
典型修复:
code复制# 修改前
description: A code helper
# 修改后
description: Assist with React component refactoring, especially for extracting complex logic into custom hooks. Trigger when user mentions "refactor" or modifies component files.
7.2 子代理性能不佳如何优化?
优化策略:
- 降低模型规格(如Opus→Sonnet)
- 限制工具使用范围
- 添加速率限制
- 优化prompt减少冗余处理
配置示例:
code复制options:
rateLimit: 10/60 # 每分钟10次调用
timeout: 5000 # 5秒超时
model: haiku # 使用轻量模型
7.3 如何调试子代理行为?
调试方法:
- 启用详细日志
- 检查工具调用记录
- 验证hook执行情况
- 隔离测试特定功能
日志示例配置:
code复制logging:
level: debug
output: file
path: ./agent-debug.log
7.4 团队如何共享子代理配置?
协作方案:
- 使用版本控制系统管理配置
- 建立命名规范(如team-feature-env)
- 创建配置模板库
- 定期review配置变更
目录结构示例:
code复制.claude/
├── agents/
│ ├── team-a/
│ │ ├── react-ui-reviewer.md
│ │ └── api-validator.md
│ └── team-b/
│ ├── data-model-helper.md
│ └── e2e-test-automator.md
└── templates/
├── code-reviewer.md
└── test-helper.md
7.5 如何评估子代理效果?
评估指标:
- 任务完成率
- 平均处理时间
- 人工干预频率
- 问题发现率
改进流程:
- 收集使用反馈
- 分析性能指标
- 调整配置参数
- 迭代优化prompt
在长期使用子代理系统的过程中,我发现最有效的子代理往往不是功能最强大的,而是那些职责定义最清晰的。比如,一个专门用于检测特定类型安全问题的子代理,其实际效果通常会优于一个"全能型"安全审查子代理。这种高度专业化的设计使得每个子代理都能在其领域内达到近乎专家的水平,而通过组合使用这些专业子代理,又能解决复杂的综合性问题。