agent-teams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Coordinate teams of 2-3 Claude Code agents working in parallel on the same codebase. Each agent runs in its own terminal, its own git worktree, and its own context window. The team lead (you, the orchestrating Claude) decomposes work, spawns agents with focused prompts, monitors progress, and coordinates merges.

Key principle: Each agent is a fresh Claude session with zero shared memory. All coordination happens through files (WORKTREE_TASK.md, shared contracts) and git (branches, PRs). There is no runtime communication between agents. </objective>

<quick_start> Set the environment variable (one-time):

bash

export AGENT_TEAMS_MAX=3  # M1/8GB safe default

Spawn a 2-agent team:

"Set up a team: Agent 1 builds the API endpoints, Agent 2 builds the React components.
They share this contract: POST /api/tasks returns { id, title, status }."

What happens:

Team lead creates 2 worktrees via worktree-manager
Writes WORKTREE_TASK.md with focused prompt + contract to each
Launches each agent in its own Ghostty terminal
Agents work independently, team lead monitors and merges </quick_start>

<success_criteria> A team session is successful when:

Each agent completes its assigned task in its worktree
No merge conflicts between agent branches (or conflicts are trivially resolvable)
Each agent's context stays focused (no bloat, no re-reading unrelated code)
All agent work passes the project's test suite after merge
Total wall-clock time is less than sequential execution would take </success_criteria>

<setup>

<objective> 协调2-3个Claude Code Agent组成的团队并行处理同一代码库。每个Agent在独立的终端、独立的git worktree和独立的上下文窗口中运行。团队负责人（即作为协调者的你，Claude）负责分解工作、为Agent生成聚焦的提示词、监控进度并协调合并。

核心原则： 每个Agent都是全新的Claude会话，无共享内存。所有协调通过文件（WORKTREE_TASK.md、共享契约）和git（分支、PR）完成。Agent之间不存在运行时通信。 </objective>

<quick_start> 设置环境变量（仅需一次）：

bash

export AGENT_TEAMS_MAX=3  # M1/8GB设备的安全默认值

生成2-Agent团队：

"创建一个团队：Agent 1负责构建API端点，Agent 2负责构建React组件。
他们遵循以下共享契约：POST /api/tasks接口返回{ id, title, status }格式数据。"

执行流程：

团队负责人通过worktree-manager创建2个worktree
为每个worktree写入包含聚焦提示词和契约的WORKTREE_TASK.md文件
在独立的Ghostty终端中启动每个Agent
Agent独立工作，团队负责人监控进度并负责合并 </quick_start>

<success_criteria> 团队会话成功的判定标准：

每个Agent在其worktree中完成分配的任务
Agent分支之间无合并冲突（或冲突可轻松解决）
每个Agent的上下文保持聚焦（无冗余内容，无需读取无关代码）
合并后所有Agent的工作成果通过项目测试套件验证
总耗时少于串行执行的时间 </success_criteria>

<setup>

Prerequisites

前置条件

Required skill: worktree-manager — agent-teams delegates ALL worktree creation, port allocation, and terminal launching to worktree-manager. Install it first.

Recommended: Project has a

.claude/

directory with CLAUDE.md (dev commands, conventions). If the project also has

.claude/agents/

with custom subagents or

.claude/settings.json

with hooks/permissions, these are automatically propagated to each agent's worktree.

Environment check:

bash

undefined

必备技能： worktree-manager —— agent-teams将所有worktree创建、端口分配和终端启动操作委托给worktree-manager，请先安装它。

推荐配置： 项目包含

.claude/

目录及其中的CLAUDE.md文件（包含开发命令、约定规范）。如果项目还包含

.claude/agents/

目录（自定义子Agent）或

.claude/settings.json

文件（钩子/权限配置），这些内容会自动同步到每个Agent的worktree中。

环境检查：

bash

undefined

Agent teams config

Agent团队配置

echo "Max agents: ${AGENT_TEAMS_MAX:-3}"

Worktree manager available?

worktree-manager是否可用？

ls ~/.claude/skills/worktree-manager/ 2>/dev/null && echo "worktree-manager: OK" || echo "worktree-manager: MISSING"

ls ~/.claude/skills/worktree-manager/ 2>/dev/null && echo "worktree-manager: 可用" || echo "worktree-manager: 缺失"

Running agents (approximate)

运行中的Agent数量（近似值）

pgrep -f "claude.*--model" | wc -l | xargs echo "Active Claude processes:"

pgrep -f "claude.*--model" | wc -l | xargs echo "活跃Claude进程数："

Memory pressure

内存压力

vm_stat | grep "Pages free" | awk '{print "Free pages:", $3}'


<current_state>
Active agents:
!`pgrep -f "claude.*--model" 2>/dev/null | wc -l | tr -d ' '` Claude processes running

Worktree registry:
!`cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | select(.status == "active") | "\(.project)/\(.branch)"' | head -5`

Memory:
!`memory_pressure 2>/dev/null | head -1 || echo "Unknown"`

Git status:
!`git status --short --branch 2>/dev/null | head -3`
</current_state>

vm_stat | grep "Pages free" | awk '{print "空闲页面数:", $3}'


<current_state>
活跃Agent数：
!`pgrep -f "claude.*--model" 2>/dev/null | wc -l | tr -d ' '` 个Claude进程正在运行

Worktree注册表：
!`cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | select(.status == "active") | "\(.project)/\(.branch)"' | head -5`

内存状态：
!`memory_pressure 2>/dev/null | head -1 || echo "未知"`

Git状态：
!`git status --short --branch 2>/dev/null | head -3`
</current_state>

Hardware Constraints (M1/8GB)

M1/8GB设备硬件限制

Resource	Budget	Per Agent	System Reserved
RAM	8 GB	~1.5 GB	2 GB
CPU cores	8	Shared	—
Max agents	3	—	—

Rule of thumb: If

memory_pressure

reports "WARN" or higher, reduce to 2 agents.

</setup>

<when_to_use>

资源	总预算	每个Agent占用	系统预留
内存	8 GB	~1.5 GB	2 GB
CPU核心	8	共享	—
最大Agent数量	3	—	—

经验法则： 如果

memory_pressure

报告"WARN"或更高级别，将Agent数量减少至2个。

</setup>

<when_to_use>

When to Use Agent Teams

何时使用Agent团队

Use when:

Task naturally decomposes into 2-3 independent work streams
Each stream touches different files (low conflict risk)
Wall-clock speed matters more than token efficiency
You have clear contracts between components (API shape, shared types)

Don't use when:

Task is tightly coupled (every change touches the same files)
You're on battery with <30% charge (agents drain power fast)
Memory pressure is already high (check
```
memory_pressure
```
)
The codebase has no tests (merging blind is risky)

Decision heuristic:

Can I describe each agent's task in <50 words?
  YES → Good candidate for agent teams
  NO  → Break it down more, or do it sequentially

Lightweight alternative: For tasks where agents DON'T need file isolation (different files, read-only, reviews), use subagent-teams instead. It uses Claude's native Task tool for in-session parallel agents — faster startup, no worktrees needed. See also the Native Teams API section below.

</when_to_use>

适用场景：

任务可自然分解为2-3个独立工作流
每个工作流涉及不同文件（冲突风险低）
耗时优先级高于Token效率
组件之间有明确的契约（API格式、共享类型）

不适用场景：

任务耦合度高（每次修改都涉及相同文件）
设备电量低于30%（Agent会快速消耗电量）
内存压力已处于高位（通过
```
memory_pressure
```
检查）
代码库无测试用例（盲目合并风险高）

决策准则：

能否用少于50个词描述每个Agent的任务？
  是 → 适合使用Agent团队
  否 → 进一步拆分任务，或串行执行

轻量替代方案： 对于Agent无需文件隔离的任务（涉及不同文件、只读、评审），请使用subagent-teams。它使用Claude原生Task工具实现会话内并行Agent，启动速度更快，无需worktree。另请参阅下方的原生团队API章节。

</when_to_use>

Architecture

架构

┌──────────────────────────────────────────────────┐
│                   TEAM LEAD                       │
│            (this Claude session)                  │
│                                                   │
│  Responsibilities:                                │
│  • Decompose task into agent assignments          │
│  • Create worktrees (via worktree-manager)        │
│  • Write WORKTREE_TASK.md for each agent          │
│  • Monitor progress (git log, file checks)        │
│  • Coordinate merges back to main                 │
└─────────┬───────────────┬───────────────┬────────┘
          │               │               │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  AGENT 1  │   │  AGENT 2  │   │  AGENT 3  │
    │           │   │           │   │           │
    │ Worktree: │   │ Worktree: │   │ Worktree: │
    │ ~/tmp/wt/ │   │ ~/tmp/wt/ │   │ ~/tmp/wt/ │
    │ proj/br-1 │   │ proj/br-2 │   │ proj/br-3 │
    │           │   │           │   │           │
    │ Terminal: │   │ Terminal: │   │ Terminal: │
    │ Ghostty 1 │   │ Ghostty 2 │   │ Ghostty 3 │
    └───────────┘   └───────────┘   └───────────┘
         │               │               │
         └───── git branches ─────────────┘
                     │
               [main branch]

┌──────────────────────────────────────────────────┐
│                   团队负责人                       │
│            (当前Claude会话)                  │
│                                                   │
│  职责：                                │
│  • 将任务分解为Agent的分配任务          │
│  • 创建worktree（通过worktree-manager）        │
│  • 为每个Agent编写WORKTREE_TASK.md文件          │
│  • 监控进度（git日志、文件检查）        │
│  • 协调合并回主分支                 │
└─────────┬───────────────┬───────────────┬────────┘
          │               │               │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  AGENT 1  │   │  AGENT 2  │   │  AGENT 3  │
    │           │   │           │   │           │
    │ Worktree: │   │ Worktree: │   │ Worktree: │
    │ ~/tmp/wt/ │   │ ~/tmp/wt/ │   │ ~/tmp/wt/ │
    │ proj/br-1 │   │ proj/br-2 │   │ proj/br-3 │
    │           │   │           │   │           │
    │ Terminal: │   │ Terminal: │   │ Terminal: │
    │ Ghostty 1 │   │ Ghostty 2 │   │ Ghostty 3 │
    └───────────┘   └───────────┘   └───────────┘
         │               │               │
         └───── git分支 ─────────────┘
                     │
               [主分支]

Context Isolation

上下文隔离

Each agent is a completely separate Claude session. Agents:

Cannot read each other's context windows
Cannot send messages to each other
Share state ONLY through the filesystem and git
Read their task from
```
WORKTREE_TASK.md
```
on startup

每个Agent都是完全独立的Claude会话。Agent具备以下特性：

无法读取其他Agent的上下文窗口
无法向其他Agent发送消息
仅通过文件系统和git共享状态
启动时从
```
WORKTREE_TASK.md
```
读取任务

Coordination Through Files

通过文件实现协调

File	Purpose	Written By	Read By
`WORKTREE_TASK.md`	Agent's assignment + context	Team lead	Agent
`CONTRACT.md`	Shared API/interface definitions	Team lead	All agents
`.agent-status`	Agent self-reports progress	Agent	Team lead
`.claude/CLAUDE.md`	Project conventions, dev commands	Project	Agent (auto-loaded)
`.claude/settings.json`	Hooks (auto-format), permissions	Project	Agent (auto-loaded)
`.claude/agents/*.md`	Custom subagent definitions	Project	Agent (on dispatch)
Git commits	Work product	Agent	Team lead at merge

</architecture>

<display_modes>

文件	用途	编写者	读取者
`WORKTREE_TASK.md`	Agent的任务分配+上下文	团队负责人	Agent
`CONTRACT.md`	共享API/接口定义	团队负责人	所有Agent
`.agent-status`	Agent自我报告进度	Agent	团队负责人
`.claude/CLAUDE.md`	项目约定、开发命令	项目方	Agent（自动加载）
`.claude/settings.json`	钩子（自动格式化）、权限配置	项目方	Agent（自动加载）
`.claude/agents/*.md`	自定义子Agent定义	项目方	Agent（调度时加载）
Git提交记录	工作成果	Agent	团队负责人（合并时查看）

</architecture>

<display_modes>

Display Modes

显示模式

Mode	Terminal	How
`in-process`	Any terminal	All teammates in main terminal. `Shift+Down` to cycle, `Ctrl+T` for task list.
`split-pane`	tmux or iTerm2 only	Each teammate gets own pane. Click pane to interact.

Config:

"teammateMode": "auto"

~/.claude/settings.json

. CLI:

claude --teammate-mode in-process

. Ghostty requires tmux wrapper for split-pane.

模式	终端要求	操作方式
`in-process`	任意终端	所有团队成员在主终端中显示。按 `Shift+Down` 切换，按 `Ctrl+T` 查看任务列表。
`split-pane`	仅支持tmux或iTerm2	每个团队成员拥有独立面板。点击面板进行交互。

配置方式：在

~/.claude/settings.json

中设置

"teammateMode": "auto"

。命令行方式：

claude --teammate-mode in-process

。Ghostty需要通过tmux包装器实现分屏模式。

Split Pane Setup

分屏模式设置

tmux: Auto-detected when

$TMUX

is set. Each teammate gets a split pane. Navigate with

Ctrl+B

+ arrow keys.

iTerm2: Uses AppleScript automation. Teammates open in split panes within the current tab.

Limitations: Ghostty lacks programmatic pane splitting — use tmux wrapper:

ghostty -e "tmux new-session"

. Max 4 panes recommended (leader + 3 teammates). Each pane needs ~120 columns.

</display_modes>

<team_hooks>

tmux： 当

$TMUX

环境变量存在时自动检测。每个团队成员分配一个分屏面板。使用

Ctrl+B

+ 方向键导航。

iTerm2： 使用AppleScript自动化。团队成员在当前标签页的分屏面板中打开。

限制： Ghostty不支持程序化分屏——请使用tmux包装器：

ghostty -e "tmux new-session"

。建议最多4个面板（负责人+3个团队成员）。每个面板需要约120列宽度。

</display_modes>

<team_hooks>

Team Hooks

团队钩子

TeammateIdle Hook

TeammateIdle钩子

Fires when a teammate finishes its current turn and goes idle. Configure in

settings.json

json

{
  "hooks": {
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Teammate idle — check TaskList for unassigned work\" >&2'"
      }]
    }]
  }
}

Use cases: Auto-assign next task, log idle time, trigger cleanup. Exit code 2 blocks the idle transition (keeps teammate working). Does NOT support matchers — fires for all teammates.

当团队成员完成当前轮次并进入空闲状态时触发。在

settings.json

中配置：

json

{
  "hooks": {
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"团队成员已空闲——查看任务列表获取未分配工作\" >&2'"
      }]
    }]
  }
}

使用场景： 自动分配下一个任务、记录空闲时间、触发清理操作。退出码2会阻止进入空闲状态（保持团队成员工作状态）。不支持匹配器——对所有团队成员触发。

TaskCompleted Hook

TaskCompleted钩子

Fires when a task is marked complete via

TaskUpdate

. Use for auto-assignment pipelines:

json

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Task completed — assigning next unblocked task\" >&2'"
      }]
    }]
  }
}

Exit code 2 blocks task completion (keeps task in_progress). Does NOT support matchers.

当任务通过

TaskUpdate

标记为完成时触发。用于自动分配流水线：

json

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"任务已完成——分配下一个未阻塞任务\" >&2'"
      }]
    }]
  }
}

退出码2会阻止任务标记为完成（保持任务在进行中）。不支持匹配器。

Plan Approval Flow

计划审批流程

Teammates spawned with

mode: "plan"

must get plans approved before implementing:

Teammate calls
```
ExitPlanMode
```
→ sends
```
plan_approval_request
```
to team lead
Team lead reviews → sends
```
plan_approval_response
```
(approve or reject with feedback)
On approval: teammate exits plan mode, begins implementation
On rejection: teammate receives feedback and revises

javascript

// Approving a teammate's plan
SendMessage({
  type: "plan_approval_response",
  request_id: "abc-123",  // from plan_approval_request
  recipient: "architect",
  approve: true
})

</team_hooks>

以

mode: "plan"

模式启动的团队成员必须先获得计划审批才能开始实施：

团队成员调用
```
ExitPlanMode
```
→ 向团队负责人发送
```
plan_approval_request
```
团队负责人审核 → 发送
```
plan_approval_response
```
（批准或附带反馈拒绝）
批准后：团队成员退出计划模式，开始实施
拒绝后：团队成员接收反馈并修订计划

javascript

// 批准团队成员的计划
SendMessage({
  type: "plan_approval_response",
  request_id: "abc-123",  // 来自plan_approval_request
  recipient: "architect",
  approve: true
})

</team_hooks>

Workflows

工作流

Workflow	Purpose
1. Spawn a Team	Decompose → JSON roadmap → worktrees → task files → launch → monitor
2. Write WORKTREE_TASK.md	Context, assignment, file boundaries, contract, verification, completion protocol
3. Monitor Progress	`git log` per branch + `.agent-status` checks
4. Merge Agent Work	Merge in planned order, test after each, `--no-ff`
5. Async Handoff	`@claude` bot on GitHub PRs for long-running tasks
6. Plan Mode	Explore codebase read-only before committing to decomposition
7. Native Teams API	`TeamCreate` + `TaskCreate` + `SendMessage` for in-session teams without worktrees
8. Plan Approval	Teammates with `mode: "plan"` submit plans for lead approval before implementing

Native vs Worktree decision: Different files → Native Teams API. Same files → Worktrees. Real-time messaging → Native. Long-running processes → Worktrees.

See

reference/workflows-detailed.md

for step-by-step instructions, WORKTREE_TASK.md template, merge protocol, and Native Teams API examples.

</workflows>

<use_cases>

工作流	用途
1. 生成团队	任务分解→JSON路线图→worktree→任务文件→启动→监控
2. 编写WORKTREE_TASK.md	上下文、任务分配、文件边界、契约、验证、完成协议
3. 监控进度	每个分支的 `git log` + `.agent-status` 检查
4. 合并Agent工作成果	按计划顺序合并，每次合并后测试，使用 `--no-ff` 参数
5. 异步交接	在GitHub PR中使用 `@claude` 机器人处理长时间运行的任务
6. 计划模式	在确定任务分解前只读探索代码库
7. 原生团队API	使用 `TeamCreate` + `TaskCreate` + `SendMessage` 实现无worktree的会话内团队
8. 计划审批	以 `mode: "plan"` 启动的团队成员在实施前提交计划供负责人审批

原生模式vs Worktree模式决策： 涉及不同文件→原生团队API。涉及相同文件→Worktree模式。实时通信→原生模式。长时间运行进程→Worktree模式。

详细步骤、WORKTREE_TASK.md模板、合并协议和原生团队API示例，请参阅

reference/workflows-detailed.md

。

</workflows>

<use_cases>

Team Patterns

团队模式

Feature Parallel

功能并行

2-3 agents build independent features simultaneously. Lowest conflict risk. Best for: Sprint-style parallel feature work. See:

reference/prompt-templates.md#feature-parallel

for spawn prompts.

2-3个Agent同时构建独立功能。冲突风险最低。 最佳适用场景： 冲刺式并行功能开发。 参考：

reference/prompt-templates.md#feature-parallel

获取生成提示词。

Frontend / Backend

前端/后端

One agent builds the API, another builds the UI. Connected by a shared contract. Best for: Full-stack features where API and UI are clearly separable. See:

reference/prompt-templates.md#frontend-backend

for spawn prompts.

一个Agent构建API，另一个构建UI。通过共享契约连接。 最佳适用场景： API和UI可清晰分离的全栈功能。 参考：

reference/prompt-templates.md#frontend-backend

获取生成提示词。

Test / Implement (TDD Pair)

测试/实现（TDD配对）

Agent 1 writes tests first, commits and pushes. Agent 2 pulls tests and implements until they pass. Best for: High-quality code where test coverage matters. See:

reference/prompt-templates.md#test-implement

for spawn prompts.

Agent 1先编写测试用例，提交并推送。Agent 2拉取测试用例并实现直到测试通过。 最佳适用场景： 注重测试覆盖率的高质量代码开发。 参考：

reference/prompt-templates.md#test-implement

获取生成提示词。

Review / Refactor

评审/重构

Agent 1 refactors code. Agent 2 reviews the refactored code and writes improvement suggestions. Best for: Large refactoring tasks that benefit from a second perspective. See:

reference/prompt-templates.md#review-refactor

for spawn prompts.

</use_cases>

<best_practices>

Agent 1重构代码。Agent 2评审重构后的代码并提出改进建议。 最佳适用场景： 可从第二视角获益的大型重构任务。 参考：

reference/prompt-templates.md#review-refactor

获取生成提示词。

</use_cases>

<best_practices>

Best Practices

最佳实践

Isolate context per agent — only relevant info in WORKTREE_TASK.md, keep tasks to <50 words
Use external state —
```
.agent-status
```
, git commits,
```
WORKTREE_TASK.md
```
(agents have no shared memory)
Front-load instructions — most important info at TOP of task files
Contract-first — define shared API shapes in
```
CONTRACT.md
```
BEFORE spawning agents
Merge order matters — foundation (API) before consumer (UI), test after each, use
```
--no-ff
```
Project config inheritance —
```
.claude/
```
dir auto-copied gives agents CLAUDE.md, hooks, permissions, custom subagents
Team hooks —
```
TeammateIdle
```
and
```
TaskCompleted
```
hooks use exit code 2 to keep working / block completion

See

reference/best-practices-full.md

for context engineering, session harness patterns, permissions model, and hook configuration.

为每个Agent隔离上下文 —— WORKTREE_TASK.md中仅包含相关信息，任务描述控制在50词以内
使用外部状态 —— 依赖
```
.agent-status
```
、git提交记录、
```
WORKTREE_TASK.md
```
（Agent无共享内存）
前置关键指令 —— 最重要的信息放在任务文件顶部
契约优先 —— 在生成Agent前，先在
```
CONTRACT.md
```
中定义共享API格式
合并顺序很重要 —— 先合并基础组件（API），再合并消费端（UI），每次合并后测试，使用
```
--no-ff
```
参数
继承项目配置 ——
```
.claude/
```
目录自动同步，为Agent提供CLAUDE.md、钩子、权限和自定义子Agent
使用团队钩子 ——
```
TeammateIdle
```
和
```
TaskCompleted
```
钩子可通过退出码2保持工作状态/阻止任务完成

上下文工程、会话管理模式、权限模型和钩子配置的详细内容，请参阅

reference/best-practices-full.md

。

Limitations

限制

M1/8GB Constraints

M1/8GB设备限制

Max 3 agents — Beyond this, memory pressure causes thrashing
No GPU agents — All agents are CPU-bound Claude sessions
Startup time — Each agent takes 5-10s to initialize

最多3个Agent —— 超过此数量会导致内存压力过大，系统出现颠簸
无GPU加速Agent —— 所有Agent都是CPU绑定的Claude会话
启动时间 —— 每个Agent需要5-10秒初始化

Coordination Limits

协调限制

No real-time communication — Worktree agents can't message each other (but native Teams API agents can — see Workflow 7)
File conflicts — If two agents edit the same file, manual resolution needed
No shared context — Each agent starts fresh with only WORKTREE_TASK.md
Sequential dependency — If Agent 2 needs Agent 1's output, Agent 2 must wait

无实时通信 —— Worktree模式的Agent无法互相发送消息（但原生团队API的Agent可以——请参阅工作流7）
文件冲突 —— 如果两个Agent编辑同一文件，需要手动解决冲突
无共享上下文 —— 每个Agent从零开始，仅能获取WORKTREE_TASK.md中的信息
顺序依赖 —— 如果Agent 2需要Agent 1的输出，Agent 2必须等待

Native Agent Teams Constraints

原生Agent团队限制

Known constraints of Claude Code's native agent teams:

Limitation	Details
No session resumption	`/resume` does not restore in-process teammates. Only the lead agent resumes.
No nested teams	Teammates cannot spawn sub-teams. Only one level of team hierarchy.
One team per session	Clean up current team (TeamDelete) before starting a new one.
Lead is fixed	Cannot promote teammates or transfer leadership mid-session.
Permissions at spawn	Teammate permissions set at spawn time. Can adjust per-teammate after creation, not during spawn.
Shutdown can be slow	Teammates finish their current request before shutting down. Plan for graceful wind-down.

Claude Code原生Agent团队的已知限制：

限制	详情
无会话恢复	`/resume` 无法恢复进程内的团队成员，仅能恢复负责人Agent。
无嵌套团队	团队成员无法生成子团队。仅支持一级团队层级。
每个会话一个团队	开始新团队前需清理当前团队（使用TeamDelete）。
负责人固定	会话过程中无法提拔团队成员或转移负责人身份。
权限在生成时设置	团队成员的权限在生成时设置。生成后可逐个调整，但生成时无法设置。
关闭速度慢	团队成员会完成当前请求后再关闭。请规划优雅的关闭流程。

What This Skill Is NOT

本技能不具备的能力

Not a CI/CD pipeline — Use GitHub Actions for automated testing
Not a subagent framework — Subagents (Claude's built-in Task tool) run within one session. This skill coordinates SEPARATE sessions.
Not auto-scaling — You manually decide team size and assignments

</limitations> <troubleshooting>

不是CI/CD流水线 —— 请使用GitHub Actions进行自动化测试
不是子Agent框架 —— 子Agent（Claude内置Task工具）在单个会话中运行。本技能协调的是独立会话。
不支持自动扩容 —— 团队规模和任务分配需手动决定

</limitations> <troubleshooting>

Troubleshooting

故障排除

Agent not reading WORKTREE_TASK.md

Agent未读取WORKTREE_TASK.md

Cause: Agent started without

--dangerously-skip-permissions

or task file not in worktree root. Fix: Ensure worktree-manager writes the task file to the worktree root directory.

原因： Agent启动时未添加

--dangerously-skip-permissions

参数，或任务文件不在worktree根目录。 解决方法： 确保worktree-manager将任务文件写入worktree根目录。

Merge conflicts between agents

Agent之间出现合并冲突

Cause: Agents edited overlapping files despite file boundary instructions. Fix:

Check if boundaries were clear in WORKTREE_TASK.md
Resolve conflicts manually on main
Next time, use stricter file boundaries

原因： 尽管有文件边界说明，Agent仍编辑了重叠文件。 解决方法：

检查WORKTREE_TASK.md中的边界说明是否清晰
在主分支上手动解决冲突
下次使用更严格的文件边界

Agent runs out of context

Agent上下文耗尽

Cause: Agent's task was too broad, causing it to read too many files. Fix: Break the task into smaller pieces. Each agent should touch <10 files.

原因： Agent的任务范围过宽，导致读取过多文件。 解决方法： 将任务拆分为更小的部分。每个Agent应处理少于10个文件。

Memory pressure / system slowdown

内存压力过大/系统变慢

Cause: Too many agents for available RAM. Fix:

Reduce to 2 agents
Close non-essential applications
Check
```
memory_pressure
```
before spawning

原因： Agent数量超过可用内存承载能力。 解决方法：

将Agent数量减少至2个
关闭非必要应用
生成Agent前先检查
```
memory_pressure
```

Agent completes but work is wrong

Agent完成任务但工作成果错误

Cause: Insufficient verification steps in WORKTREE_TASK.md. Fix: Add explicit verification commands:

markdown

undefined

原因： WORKTREE_TASK.md中的验证步骤不足。 解决方法： 添加明确的验证命令：

markdown

undefined

Verification

验证步骤

Run: npm test -- --filter auth
Run: npx tsc --noEmit
Manually test: curl localhost:8100/api/auth/login


</troubleshooting>

<routing>

运行：npm test -- --filter auth
运行：npx tsc --noEmit
手动测试：curl localhost:8100/api/auth/login


</troubleshooting>

<routing>

Reference Files

参考文件

Load these on demand when you need deeper guidance:

Reference	Load When
`reference/workflows-detailed.md`	Step-by-step spawn, monitor, merge, async handoff, Native Teams API
`reference/best-practices-full.md`	Context engineering, session harness, contract-first, hooks config
`reference/context-engineering.md`	Designing agent prompts, optimizing context usage, delegation patterns
`reference/worktree-integration.md`	Coordinating with worktree-manager, port allocation, terminal strategies
`reference/prompt-templates.md`	Need ready-to-use spawn prompts for the 4 team patterns

</routing>

需要更深入的指导时按需加载以下文件：

参考文件	加载场景
`reference/workflows-detailed.md`	分步指导生成团队、监控、合并、异步交接、原生团队API
`reference/best-practices-full.md`	上下文工程、会话管理、契约优先、钩子配置
`reference/context-engineering.md`	Agent提示词设计、上下文使用优化、委托模式
`reference/worktree-integration.md`	与worktree-manager协调、端口分配、终端策略
`reference/prompt-templates.md`	获取4种团队模式的即用型生成提示词

</routing>