一、总结如何创建和使用子代理：
什么是子代理（Sub-agents）
子代理是 Claude Code 中的专门 AI 助手，可以处理特定类型的任务。它们能够提供特定任务的配置，包括自定义系统提示、工具和独立的上下文窗口，实现更高效的问题解决。
创建子代理的方法
1. 使用 /agents 命令（推荐）
使用 /agents 命令可以通过交互式界面管理子代理，这会列出所有可用的工具，包括任何已连接的 MCP 服务器工具。
2. 手动创建子代理文件
子代理是带有 YAML 前置内容的 Markdown 文件，存储在两个位置：
-
项目级子代理:
.claude/agents/目录（项目特定） -
用户级子代理:
~/.claude/agents/目录（全局可用）
当名称冲突时，项目特定的子代理会覆盖全局子代理。
子代理文件格式示例：
---
name: test-runner
description: 专门运行测试的子代理。在代码更改后主动使用。
tools: Read, Edit, Write, Grep, Glob, Bash
model: inherit # 可选：sonnet, opus, haiku 或 inherit
---
你是一个测试专家，负责：
1. 理解测试需求
2. 编写高效的测试代码
3. 运行测试并分析结果
4. 修复失败的测试
5. 清晰地展示发现
关键实践：
- 在代码更改后主动运行适当的测试
- 如果测试失败，分析失败原因并修复
- 保持原始测试意图不变
在 Claude Code 中使用子代理
自动调用
Claude Code 遇到与子代理专长匹配的任务时，可以自动委托给专门的子代理工作。
手动调用
你也可以在对话中明确请求特定的子代理：
> 使用 test-runner 子代理来修复失败的测试
> 让 code-reviewer 子代理查看我最近的更改
> 请 debugger 子代理调查这个错误
最佳实践
从 Claude 生成开始：强烈建议先让 Claude 生成初始子代理，然后根据具体需求进行迭代定制。
设计专注的子代理：创建具有单一、明确职责的子代理，而不是试图让一个子代理处理所有任务。
-
工具权限控制：
- 可以省略 tools 字段以继承主线程的所有工具（默认）
- 或指定特定工具列表进行精细控制
-
使用描述性名称和说明：
- 在 description 字段中包含"use PROACTIVELY"或"MUST BE USED"等短语，可以鼓励更主动的子代理使用。
实际应用示例
你可以创建各种专门的子代理：
- code-reviewer: 代码审查专家
- test-runner: 测试运行和修复
- debugger: 调试和错误分析
- database-expert: 数据库和迁移专家
- frontend-developer: 前端开发专家
- security-auditor: 安全审计专家
优势
- 独立的上下文窗口：每个子代理在自己的上下文中运行，避免主对话的上下文污染
- 领域专业知识：每个子代理都有针对其专业领域的定制指令
- 项目间共享：创建后可在不同项目中使用，也可与团队成员共享
- 精细的工具权限：可为不同任务类型配置特定的工具访问权限
这种子代理系统使 Claude Code 能够像管理一个专业团队一样工作，每个成员都有自己的专长领域，大大提高了开发效率和代码质量。
二、怎么使用自定义 agents
根据 Claude Code 的文档，配置 agents 后，你可以通过以下方式使用它们：
1. 通过命令行直接调用
# 使用特定 agent
claude --agent <agent-name> "你的请求"
# 或者使用短格式
claude -a <agent-name> "你的请求"
2. 在交互模式中切换
当你运行 claude 进入交互模式后，可以使用：
/agent <agent-name> # 切换到指定的 agent
/agents # 列出所有可用的 agents
3. Agent 配置示例
你的 agent 配置文件（通常在 ~/.claude/agents/ 或系统配置目录）应该类似这样：
name: python-expert
description: Python 编程专家
instructions: |
你是一个 Python 编程专家，专注于编写高质量、高效的 Python 代码。
遵循 PEP 8 规范，使用类型提示，编写清晰的文档字符串。
model: claude-opus-4-1-20250805 # 可选，指定模型
4. 实际使用示例
# 使用 Python 专家 agent 来优化代码
claude --agent python-expert "帮我优化这段代码：[你的代码]"
# 使用数据分析 agent
claude -a data-analyst "分析这个 CSV 文件的数据趋势"
5. 设置默认 Agent
你也可以在配置文件中设置默认 agent：
# 在 ~/.claude/config.yaml 中
default_agent: python-expert
如果 /agents 命令已经能显示你的 agents，说明配置路径是正确的。现在你只需要使用上述命令来调用它们即可。
需要注意的是，agent 的名称应该与配置文件中定义的名称完全一致（区分大小写）。
如果你遇到具体的使用问题，可以告诉我错误信息，我会帮你进一步排查。你也可以查看官方文档 https://docs.claude.com/en/docs/claude-code 获取更详细的信息。
附：
- 代码审查员 code-reviewer
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.
- 调试器 debugger
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations
Focus on fixing the underlying issue, not just symptoms.
- 数据科学家
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---
You are a data scientist specializing in SQL and BigQuery analysis.
When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly
Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations
For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data
Always ensure queries are efficient and cost-effective.
参考：
