Claude Code Sub-agents 核心要点总结

什么是 Sub-agents

Sub-agent 不是简单的角色扮演，而是拥有独立上下文窗口（200k）、独立思考空间和专属工具箱的专家。

核心优势

• 上下文保护：独立的 200k 上下文窗口，避免干扰
• 专业化能力：可以写几百行系统提示词，灌输专业知识
• 可重复使用：一次创建，所有项目复用

Sub-agent 定义结构

---
# YAML 配置区（重要：主Agent根据这里决定是否调用）
name: agent-name
description: 功能描述（建议加入MUST BE USED等强制词语）
tools: [read, grep, glob]
model: claude-3-5-sonnet-20240620
color: yellow
---

# 系统提示词区

你是一名 xxx 专家...
（详细的专业指令和最佳实践）

存储位置

• 项目级：.claude/agents/ - 团队共享，优先级更高
• 用户级：~/.claude/agents/ - 个人通用工具箱

实战经验教训

1. 放弃自动路由，使用显式调用

• ❌ 自动路由极度不可靠：AI 经常"偷懒"不调用 sub-agent
• ✅ 显式调用：使用 @agent-name 或 use agent-name... 语法

2. 多 Agent 协作：文件系统通信

由于上下文隔离，agents 无法直接交流，解决方案：通过文件当中介

工作流示例：
1. @planner 规划需求 → 写入 .claude/docs/spec.md
2. @coder 读取spec.md → 编写代码
3. @reviewer 审查代码 → 检查是否符合spec.md要求

3. 适用场景判断

适合使用 Sub-agents：

• 复杂多步骤任务
• 需要专业化处理
• 团队协作标准化

不适合使用 Sub-agents：

• 简单单一任务
• 需要全局上下文的任务
• Token 和时间开销敏感的场景

4. MCP 使用建议

• 简单操作：使用 MCP（如"打开网页截图"）
• 复杂任务：让 Sub-agent 编写完整脚本，用 bash 执行更稳定

实用资源

开箱即用的 Sub-agents 模板

1. https://github.com/hesreallyhim/awesome-claude-code
2. https://www.aitmpl.com/
3. https://github.com/VoltAgent/awesome-claude-code-subagents
4. https://github.com/wshobson/agents
5. https://github.com/vanzan01/claude-code-sub-agent-collective