Claude Code自定义子代理开发指南

1. 为什么需要自定义子代理

在软件开发过程中，我们经常会遇到一些重复性的任务，比如代码审查、测试编写、文档生成等。Claude Code内置的通用子代理虽然能处理大部分基础任务，但当遇到需要特定领域知识的场景时，就显得力不从心了。

举个例子，假设你的团队使用特定的代码规范：

• 变量命名必须采用小驼峰式
• 每个函数前必须有详细的注释说明
• 数据库操作必须使用预编译语句
• 错误处理必须包含上下文信息

每次进行代码审查时，你都需要反复向Claude解释这些规则，效率低下且容易遗漏。自定义子代理就是为了解决这个问题而生的。

2. 自定义子代理的核心概念

2.1 什么是自定义子代理

自定义子代理本质上是一个Markdown文件，包含两部分内容：

1. YAML frontmatter：定义子代理的元信息
2. 系统提示词：指导子代理如何工作

这种设计有以下几个优点：

• 简单易用：不需要编写代码，只需编辑Markdown文件
• 版本可控：可以纳入Git管理，方便团队共享
• 灵活配置：可以根据不同场景定制不同的子代理

2.2 文件结构详解

一个典型的子代理文件结构如下：

markdown复制---
name: code-reviewer
description: 专注代码质量审查的子代理
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
permission: default
---

你是一个严格的代码审查员。审查时重点关注：
1. 安全漏洞：SQL注入、XSS等
2. 性能问题：N+1查询、内存泄漏等
3. 代码规范：命名、注释等
4. 可维护性：函数长度、复杂度等

输出分三级：
- 🔴 严重问题
- 🟡 警告
- 🔵 建议

3. 子代理的部署与管理

3.1 部署位置选择

自定义子代理可以部署在两个位置：

1. 项目级：.claude/agents/

   • 只对当前项目有效
   • 可以提交到代码仓库，团队共享
   • 适合项目特定的规则和流程

2. 全局级：~/.claude/agents/

   • 对所有项目有效
   • 适合个人常用的工具
   • 不会被提交到代码仓库

注意：项目级子代理会覆盖全局级同名子代理，这是有意设计的优先级规则。

3.2 临时加载方式

除了固定目录，还有两种临时加载方式：

1. 通过CLI参数：

bash复制claude --agents /path/to/custom-agents/

2. 通过插件分发：
   插件的agents/目录会被自动扫描，适合团队统一分发标准化的子代理集合。

4. Frontmatter配置详解

4.1 基本配置

• name：子代理的唯一标识符，用于调用时匹配
• description：描述子代理的功能，影响自动匹配的准确性
• model：指定使用的AI模型（sonnet/opus/haiku）

4.2 工具权限控制

yaml复制tools:
  - Read    # 读取文件
  - Glob    # 文件匹配
  - Grep    # 内容搜索
  - Edit    # 编辑文件
  - Bash    # 执行命令

工具配置遵循最小权限原则：

• 只授予必要的权限
• 例如代码审查子代理不需要Edit权限

4.3 权限级别

yaml复制permission: default       # 默认，需要确认
permission: acceptEdits   # 自动接受编辑
permission: dontAsk       # 不询问直接执行
permission: bypassPermissions  # 绕过所有检查
permission: plan          # 只规划不执行

根据子代理的用途选择合适的权限级别：

• 审查类：default
• 测试生成类：acceptEdits
• CI/CD类：dontAsk（需谨慎）

5. 实战案例：代码审查子代理

5.1 创建审查子代理

在项目根目录创建.claude/agents/code-reviewer.md：

markdown复制---
name: code-reviewer
description: 代码质量审查专家
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
---

你是一个专业的代码审查员，重点关注：
1. 安全漏洞
2. 性能问题
3. 代码规范
4. 可维护性

输出格式：
- 🔴 严重问题（必须修复）
- 🟡 警告（建议修复）
- 🔵 建议（优化项）

每个问题需包含：
- 文件路径
- 行号
- 问题描述
- 修复建议

5.2 测试审查功能

准备一个有问题的代码文件src/auth.py：

python复制def validate_user(input):
    # SQL注入风险
    query = f"SELECT * FROM users WHERE username = '{input}'"
    result = db.execute(query)
    return result is not None

def load_user_data(user_id):
    # N+1查询问题
    user = get_user(user_id)
    for item in user.items:
        item.details = get_item_details(item.id)
    return user

调用审查：

bash复制claude --agent code-reviewer
> 请审查src/auth.py

预期输出：

code复制🔴 安全漏洞：SQL注入风险
文件：src/auth.py 行号：3
问题：直接拼接用户输入到SQL查询
建议：使用参数化查询

🟡 性能问题：N+1查询
文件：src/auth.py 行号：9
问题：循环内执行数据库查询
建议：使用JOIN或批量查询

6. 实战案例：测试生成子代理

6.1 创建测试子代理

.claude/agents/test-writer.md：

markdown复制---
name: test-writer
description: 单元测试生成专家
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Edit
  - Bash
permission: acceptEdits
---

你是一个测试工程师，负责：
1. 识别测试框架（pytest/unittest等）
2. 分析函数输入输出
3. 生成完整测试用例
4. 确保测试通过

测试文件存放于：
- Python: __tests__/目录
- JavaScript: test/目录
- Go: _test.go文件

6.2 生成测试用例

对之前的auth.py生成测试：

bash复制claude --agent test-writer
> 为src/auth.py生成测试

预期行为：

1. 创建__tests__/test_auth.py
2. 生成测试用例
3. 自动运行测试
4. 报告测试结果

7. 高级用法与技巧

7.1 子代理协作

可以让不同子代理协同工作：

1. 先用code-reviewer审查代码
2. 手动修复发现的问题
3. 用test-writer生成测试
4. 再次用code-reviewer审查测试代码

7.2 隔离模式

yaml复制isolation: worktree

这个配置让子代理在独立的Git工作区操作，不会影响主代码库，适合尝试性修改。

7.3 后台运行

yaml复制background: true

让子代理在后台执行，不阻塞主对话，适合耗时任务。

8. 调用方式对比

选择建议：

• 日常简单任务：自然语言
• 重要任务：@提及
• 集中处理：全局模式

9. 最佳实践

1. 描述要具体：description字段写详细些，提高自动匹配准确率
2. 权限最小化：只授予必要的工具权限
3. 模型适配：简单任务用sonnet，复杂分析用opus
4. 版本控制：项目级子代理纳入Git管理
5. 定期优化：根据使用反馈调整提示词

10. 常见问题排查

1. 子代理不生效

   • 检查文件路径是否正确
   • 确认文件名与name字段一致
   • 查看是否有同名子代理冲突

2. 权限问题

   • 确认tools包含所需权限
   • 检查permission设置是否太严格

3. 输出不符合预期

   • 优化系统提示词
   • 尝试更换模型（如sonnet→opus）
   • 添加更具体的示例

自定义子代理是提升开发效率的利器，通过将领域知识固化到Markdown文件中，你可以打造出真正懂你项目、懂你团队的智能助手。从简单的代码审查开始，逐步扩展到更多场景，你会发现Claude Code变得越来越"懂你"。