subagent-teams

在单个 Claude Code 会话中编排由 Task 工具驱动的子 Agent 团队。与使用 worktree 和终端来运行完整并行会话的 agent-teams-skill 不同，此技能使用 Task 工具实现轻量级的会话内并行处理，并共享代码库访问权限。

<quick_start> 研究分发：

Launch 3 Explore agents in parallel:
- Agent 1: Search for authentication patterns
- Agent 2: Search for database schema
- Agent 3: Search for API endpoints

实现分发：

1. Plan agent designs architecture
2. 3 general-purpose agents build components in parallel
3. code-reviewer agent validates all changes

</quick_start>

<success_criteria>

• 使用正确的模型层级启动子 Agent（搜索／审查使用 Haiku，代码使用 Sonnet，架构设计使用 Opus）
• 并行 Agent 能够独立完成任务，且不会产生相互冲突的文件编辑
• 汇总整合能收集所有后台 Agent 的关键发现
• 并行 Agent 总数保持在 5–7 个以内，避免上下文溢出
• 使用 TaskCreate/TaskUpdate 跟踪进度，并显示实时 UI 旋转指示器 </success_criteria>

- “set up subagent team”、“fan out”、“parallel tasks”、“Task tool team” - “research in parallel”、“explore in parallel”、“review in parallel” - “spawn subagents”、“in-session agents”

---

何时使用此工具，而非 agent-teams

因素	subagent-teams（此工具）	agent-teams
隔离性	共享代码库、共享上下文	完全隔离的 worktree
开销	轻量——仅调用 Task 工具	较重——终端、Git 分支、端口
适用场景	研究、审查、文档更新	功能构建、文件编辑冲突
Agent 上限	5–7 个（上下文限制）	2–3 个（M1 8GB RAM 限制）
持续时间	分钟	小时
协调方式	TeamCreate + TaskList/TaskUpdate	WORKTREE_TASK.md + Git 分支

经验法则： 如果 Agent 会编辑相同文件 → 使用 agent-teams（worktree 隔离）。如果 Agent 只读或编辑不同文件 → 使用 subagent-teams（更快、更轻量）。

---

Task 工具参数（完整参考）

核心参数

{
  subagent_type: "Explore" | "general-purpose" | "Plan" | ...,
  model: "haiku" | "sonnet" | "opus",
  prompt: "...",
  description: "3-5 word summary",        // Required
  run_in_background: true,                 // For parallel execution
  team_name: "my-team",                    // Scope to a team's task list
  name: "agent-1",                         // Name for team messaging
  mode: "default"                          // Permission mode (see below)
}

Agent Frontmatter 字段（用于 .md Agent 文件）

字段	类型	用途
name	string	Agent 标识符
description	string	Agent 的工作内容（显示在路由信息中）
model	string	默认模型：haiku、sonnet、opus
tools	list	允许使用的工具（限制 Agent 的能力）
disallowedTools	list	明确禁止使用的工具
permissionMode	string	default、acceptEdits、dontAsk、plan
mcpServers	list	Agent 可用的 MCP 服务
hooks	object	事件驱动的自动化（PostToolUse 等）
maxTurns	number	停止前最多进行的 API 往返次数
skills	list	Agent 可用的技能
memory	object	持久状态（见下文“记忆范围”）

记忆范围

memory 字段为 Agent 提供跨会话的持久状态：

# User-scoped: shared across all projects for this user
memory:
  scope: user    # Stored in ~/.claude/agent-memory/

# Project-scoped: shared across sessions within one project
memory:
  scope: project # Stored in .claude/agent-memory/

# Local-scoped: private to this machine + project combo
memory:
  scope: local   # Stored in .claude/local/agent-memory/

使用场景： user 用于个人偏好／模式。project 用于团队共享知识。local 用于特定机器的路径或凭据。

后台执行

对于不会阻塞你下一步操作的 Agent，请使用 run_in_background: true：

// Launch in background — returns immediately with output_file path
Task({
  subagent_type: "Explore",
  prompt: "Search for all auth patterns",
  run_in_background: true  // Non-blocking
})

// Check results later
TaskOutput({ task_id: "agent-id", block: false })  // Non-blocking check
TaskOutput({ task_id: "agent-id", block: true })    // Wait for completion

前台与后台：

• 前台（默认）：需要先获得结果才能继续时使用，例如为后续步骤提供依据的研究
• 后台：有可并行开展的独立工作时使用，例如观察器、代码检查器、耗时较长的搜索

提示： 后台 Agent 非常适合 observer-lite/observer-full、安全扫描，以及稍后再汇总结果的并行研究。

权限模式

模式	行为
default	正常审批流程
acceptEdits	自动批准文件编辑，Bash 操作仍需提示
dontAsk	自动批准所有操作（用于受信任的 Agent）
plan	Agent 必须先获得计划批准才能实施
delegate	Agent 只能委派给子 Agent

派生限制

使用工具字段中的 Task(agent_type) 限制 Agent 可以派生的子 Agent：

tools:
  - Read
  - Glob
  - Task(Explore)        # Can only spawn Explore subagents
  - Task(code-reviewer)  # Can also spawn code reviewers

内置 Agent 类型及其工具访问权限：

Agent 类型	工具	适用场景
Explore	Glob、Grep、Read、LS、WebFetch、WebSearch	快速搜索代码库（只读）
Plan	Glob、Grep、Read、LS、WebFetch、WebSearch	架构设计（只读）
general-purpose	所有工具	实现、完整访问权限
feature-dev:code-reviewer	Glob、Grep、Read、LS、WebFetch	代码审查（只读）
feature-dev:code-explorer	Glob、Grep、Read、LS、WebFetch	深入分析功能（只读）
feature-dev:code-architect	Glob、Grep、Read、LS、WebFetch	架构蓝图（只读）
observer-lite	Read、Glob、Grep、Bash、Write	快速质量检查
observer-full	Read、Glob、Grep、Bash、Write	全面偏差检测

自定义 Agent： 在 .claude/agents/*.md 中使用 frontmatter 定义。引用时使用文件名（不带 .md）。

模型选择指南

任务	模型	原因
文件搜索、模式匹配	haiku	快速、便宜，足够胜任
代码审查、查找 Bug	haiku	模式匹配，而非生成
代码生成、重构	sonnet	代码质量很重要
架构决策	opus	需要复杂推理
文档编写	sonnet	需要理解上下文

---

团队模式

1. 研究团队（3 个 Explore Agent）

并行展开 3 种搜索策略，再汇总综合结果：

Task 1 (Explore, haiku): "Search for [pattern] in src/"
Task 2 (Explore, haiku): "Search for [pattern] in tests/"
Task 3 (Explore, haiku): "Search for [pattern] in docs/"
→ Fan-in: Synthesize findings into summary

适用场景： 探索不熟悉的代码库，了解某项功能如何跨层工作。

2. 实现团队（架构师 → 构建者 → 审查者）

采用顺序流水线，并行执行构建阶段：

Phase 1: Plan agent designs architecture (1 agent)
Phase 2: 2-3 general-purpose agents build components (parallel)
Phase 3: code-reviewer validates (1 agent)

适用场景： 构建包含多个独立组件的功能。

3. 审查团队（3 个审查者并行工作）

Task 1 (code-reviewer, haiku): "Review src/auth/ for security"
Task 2 (code-reviewer, haiku): "Review src/api/ for consistency"
Task 3 (code-reviewer, haiku): "Review src/db/ for performance"
→ Fan-in: Aggregate findings, deduplicate

适用场景： 对大型变更集进行 PR 前审查。

4. 探索团队（3 种搜索策略）

Task 1 (Explore, haiku): Glob for file patterns
Task 2 (Explore, haiku): Grep for code patterns
Task 3 (Explore, haiku): Read key entry points
→ Fan-in: Build mental model of codebase area

适用场景： 首次在代码库的新区域开展工作。

5. 文档团队（N 个独立文件更新者）

Task 1 (general-purpose, haiku): "Update README.md with new API"
Task 2 (general-purpose, haiku): "Update CHANGELOG.md"
Task 3 (general-purpose, haiku): "Update API docs"
→ No fan-in needed (independent files)

适用场景： 更新多个互相独立的文档文件。

---

进度呈现

原生进度（TaskCreate/TaskUpdate）

使用带有 activeForm 的 TaskCreate，在执行过程中显示实时 UI 加载动画：

// Create tasks for each agent's work
TaskCreate({ subject: "Search auth patterns", activeForm: "Searching auth patterns" })
TaskCreate({ subject: "Search DB schema", activeForm: "Searching DB schema" })
TaskCreate({ subject: "Search API endpoints", activeForm: "Searching API endpoints" })

// Track status transitions
TaskUpdate({ taskId: "1", status: "in_progress" })  // → shows spinner
TaskUpdate({ taskId: "1", status: "completed" })     // → shows checkmark

任务依赖（顺序阶段）

使用 addBlockedBy 对各阶段进行排序：

// Phase 1: Architecture (runs first)
TaskCreate({ subject: "Design architecture" })  // → task #1

// Phase 2: Implementation (blocked by Phase 1)
TaskCreate({ subject: "Build backend" })   // → task #2
TaskCreate({ subject: "Build frontend" })  // → task #3
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["1"] })

// Phase 3: Review (blocked by Phase 2)
TaskCreate({ subject: "Code review" })  // → task #4
TaskUpdate({ taskId: "4", addBlockedBy: ["2", "3"] })

摘要呈现（Markdown）

所有 Agent 完成后，呈现 Markdown 摘要：

## Research Complete: 3/3 agents finished

| Agent | Scope | Findings | Time |
|-------|-------|----------|------|
| Auth search | src/auth/ | 12 files, JWT + session | 8s |
| DB search | src/db/ | 8 tables, RLS policies | 5s |
| API search | src/api/ | 15 endpoints, REST | 6s |

### Key Insights
- [Synthesized finding 1]
- [Synthesized finding 2]

---

团队协调（原生 Agent Teams API）

对于复杂的多 Agent 工作，使用原生 Teams API：

// Create a team with shared task list
TeamCreate({ team_name: "research-sprint" })

// Spawn teammates into the team
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-1" })
Task({ subagent_type: "Explore", team_name: "research-sprint", name: "searcher-2" })

// Teammates coordinate via shared TaskList
// Send messages between teammates
SendMessage({ type: "message", recipient: "searcher-1", content: "Focus on auth/" })

// Shutdown when done
SendMessage({ type: "shutdown_request", recipient: "searcher-1" })

---

提示词模板

研究派生

Search the codebase for [PATTERN]. Look in [SCOPE].
Report: file paths, line numbers, and a 2-sentence summary of each match.
Do NOT modify any files.

构建派生

Implement [COMPONENT] in [FILE_PATH].
Requirements: [SPEC]
Follow existing patterns in [EXAMPLE_FILE].
Write code only — do not run tests.

审查派生

Review [FILE_PATH] for [CONCERN: security|performance|consistency].
Report only HIGH confidence issues.
Format: file:line — issue — suggestion

---

限制

• 最多并行 5-7 个 Agent — 超过此数量会占满上下文窗口
• 不得编辑相互冲突的文件 — 如果 Agent 可能编辑同一文件，请改用 agent-teams
• 汇总需手动完成 — 你（团队负责人）需要综合后台 Agent 的结果
• 后台 Agent 彼此不可见 — 设计任务时应确保每项任务都能独立完成

深入了解： 请参阅 reference/task-tool-guide.md、reference/team-patterns.md、reference/prompt-templates.md

输出结果 Sidecar 文件

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-subagent-teams.json：

{"ts":"[UTC ISO8601]","skill":"subagent-teams","version":"1.1.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"agents_spawned":[n],"tasks_completed":[n],"tasks_failed":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但仍产生了结果，请使用状态 "partial"。仅当未生成任何输出时，才使用 "error"。