← Volver al listado de tecnologías ← Índice de Claude Code

Cap 11: Agent Teams y Worktrees

2 de marzo de 2026 Por: Artiko

claude-codeagent-teamsworktreesparalelo

Agent Teams

Los agent teams permiten ejecutar múltiples instancias de Claude Code trabajando en paralelo sobre diferentes partes de una tarea. Un agente líder coordina el trabajo.

Cómo funciona

El agente principal divide la tarea en subtareas
Lanza sub-agentes en paralelo (cada uno en su worktree)
Los sub-agentes trabajan de forma independiente
El agente principal recopila resultados y los integra

flowchart TD
    P["Agente Principal\n(coordinador)"]
    A1["Agente 1\nrefactor auth module\n[worktree-1]"]
    A2["Agente 2\nadd unit tests\n[worktree-2]"]
    A3["Agente 3\nupdate documentation\n[worktree-3]"]
    P --> A1 & A2 & A3

Límites de ejecución vigentes

En v2.1.217 hay dos límites que gobiernan cualquier agent team:

Límite	Valor por defecto	Variable de entorno
Profundidad de anidamiento de subagentes	1 (no generan subagentes anidados)	`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`
Subagentes concurrentes	20	`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`

Es decir: por defecto un subagente no puede lanzar más subagentes; la jerarquía es plana (líder → subagentes). Si necesitas más niveles hay que subir CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH explícitamente.

Ejecución en background

Desde v2.1.198 los subagentes corren en background por defecto y heredan la configuración de extended thinking de la sesión principal. En la misma versión, /agents dejó de abrir el asistente interactivo con pestañas Running/Library: la gestión del equipo se hace hoy desde la CLI (ver más abajo) y desde los archivos en .claude/agents/.

Git Worktrees

Un git worktree es una copia de trabajo adicional del repositorio. Permite tener múltiples branches checked out simultáneamente sin conflictos.

Cómo se usan en Claude Code

# Iniciar Claude en un worktree aislado
claude --worktree feature-auth

# Claude crea automáticamente:
# .claude/worktrees/feature-auth/

Ubicación de worktrees

flowchart TD
    P["proyecto/"]
    C[".claude/"]
    W["worktrees/"]
    W1["feature-auth/"]
    W2["fix-tests/"]
    W3["update-docs/"]
    M["directorio principal"]
    P --> C
    P --> M
    C --> W
    W --> W1 & W2 & W3

Worktrees en sub-agentes

Cuando un agente se define con isolation: "worktree", cada invocación crea un worktree temporal:

<!-- .claude/agents/feature-worker.md -->
---
name: feature-worker
description: Implementa una feature acotada en un worktree propio
isolation: worktree
background: true
model: inherit
effort: xhigh
maxTurns: 40
permissionMode: acceptEdits
tools: ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
disallowedTools: ["WebFetch"]
---

Implementa la feature asignada en tu worktree.
Commitea tus cambios cuando termines.

Los subagentes NO son una frontera de seguridad. La documentación es explícita: «subagents run in the same process as the parent session and use the same sandbox configuration». Un worktree más una lista de tools recortada te da aislamiento de contexto y restricción de herramientas, no una barrera de seguridad. Para eso están el sandbox y las reglas de permisos. Si quieres impedir por completo que se invoque un subagente, se deshabilita con Agent(NombreAgente) en permissions.deny.

Campos de frontmatter relevantes para agent teams

Campo	Para qué sirve
`background`	Ejecuta el subagente en segundo plano
`model`	`sonnet`, `opus`, `haiku`, `fable`, un ID completo o `inherit` (default)
`effort`	`low`, `medium`, `high`, `xhigh`, `max`
`maxTurns`	Tope de turnos del subagente
`permissionMode`	`default`/`manual`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`
`memory`	Memoria propia del subagente
`skills`	Skills disponibles para el subagente
`mcpServers`	Servidores MCP que puede usar
`hooks`	Hooks propios del subagente
`initialPrompt`	Prompt inicial fijo del subagente
`disallowedTools`	Herramientas prohibidas (complementa a `tools`)

Nota: los subagentes de plugin ignoran por seguridad hooks, mcpServers y permissionMode.

Teammate Mode

El flag --teammate-mode controla cómo se muestran los agentes del equipo:

Modo	Comportamiento
`auto`	Claude decide automáticamente (default)
`in-process`	Los teammates se ejecutan en el mismo proceso
`tmux`	Cada teammate se ejecuta en un panel tmux separado

# Usar paneles tmux para ver cada agente
claude --teammate-mode tmux

tmux mode

Con tmux, cada agente aparece en su propio panel de terminal, permitiendo ver su progreso en tiempo real:

flowchart LR
    subgraph tmux["Terminal tmux — 4 paneles simultáneos"]
        MA["Main Agent\nCoordinando..."]
        AT["Agent: tests\nEscribiendo tests\npara auth module..."]
        AD["Agent: docs\nActualizando\nREADME..."]
        AR["Agent: refact\nRefactorizando\nutils.ts..."]
    end
    MA -.->|coordina| AT & AD & AR

tmux es solo una de las vías de observación, y ya no es la principal: desde v2.1.198 el default es background. Para inspeccionar un equipo que corre en segundo plano se usan claude agents y sus subcomandos.

CLI de agent teams

# Listar los agentes en ejecución
claude agents

# Adjuntarse a la salida de uno concreto
claude agents attach <id>

# Detener un agente
claude agents stop <id>

# Relanzarlo
claude agents respawn <id>

# Ver sus logs
claude agents logs <id>

Flags relacionados:

Flag	Efecto
`--bg` / `--background`	Lanza la sesión en background
`--worktree` / `-w`	Crea/usa un worktree para la sesión
`--tmux`	Paneles tmux
`--teammate-mode`	`auto`, `in-process`, `tmux`
`--forward-subagent-text`	Reenvía el texto que producen los subagentes
`--agents`	Define subagentes inline en JSON para esa sesión

--agents tiene precedencia sobre .claude/agents/ y ~/.claude/agents/, pero por debajo de los managed settings de la organización.

Hooks del ciclo de vida

Además de TeammateIdle, hay eventos directamente ligados a subagentes, tareas y worktrees:

Evento	Cuándo se dispara
`SubagentStart`	Al arrancar un subagente
`SubagentStop`	Al terminar un subagente
`TaskCreated`	Al crearse una tarea
`TaskCompleted`	Al completarse una tarea
`WorktreeCreate`	Antes de crear un worktree
`WorktreeRemove`	Al eliminar un worktree
`TeammateIdle`	Cuando un teammate está a punto de quedar inactivo

En WorktreeCreate, cualquier código de salida distinto de 0 aborta la creación del worktree (no solo el exit 2 habitual de los hooks bloqueantes).

Dentro de un subagente, los campos de entrada del hook incluyen agent_id y agent_type, lo que permite discriminar quién disparó el evento.

TeammateIdle hook

El hook TeammateIdle se dispara cuando un teammate está a punto de quedar inactivo. Útil para reasignar trabajo:

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/reassign-work.sh"
          }
        ]
      }
    ]
  }
}

Ejemplo: Implementar feature con agent team

El antipatrón documentado de delegación son las instrucciones vagas: producen trabajo duplicado, huecos y fallos. Cada subagente necesita objetivo, formato de salida, guía de herramientas y fuentes, y límites claros.

# Lanzar el equipo en background con worktrees
claude --bg --worktree notificaciones

Prompt al agente líder:

Implementa el sistema de notificaciones lanzando 3 subagentes EN PARALELO
(una sola tanda, no en serie). Da a cada uno estas instrucciones completas:

Subagente "backend":
- Objetivo: endpoints POST /notifications y GET /notifications/:userId.
- Límites: solo toca src/api/notifications/**; no modifiques el schema
  de la base de datos ni otros módulos.
- Herramientas: Read, Edit, Write, Bash(bun test *). No uses WebFetch.
- Salida: resumen de <= 2.000 tokens con rutas de archivos tocados,
  firma de cada endpoint y salida real de `bun test`.

Subagente "frontend":
- Objetivo: componentes NotificationList y NotificationBadge.
- Límites: solo src/components/notifications/**; consume los endpoints
  ya definidos, no los redefinas.
- Herramientas: Read, Edit, Write. Fuente de verdad: el contrato de la API
  en docs/api/notifications.md.
- Salida: resumen de <= 2.000 tokens con props de cada componente
  y captura del render en Storybook.

Subagente "tests":
- Objetivo: tests de integración del flujo completo de notificación.
- Límites: solo tests/notifications/**; no edites código de producción.
- Herramientas: Read, Write, Bash(bun test *).
- Salida: resumen de <= 2.000 tokens con la lista de casos y la salida
  del runner (comando ejecutado + resultado, no una aserción de éxito).

Después integra los tres worktrees y ejecuta la suite completa.

Dos detalles del patrón canónico:

Paralelismo de dos niveles: el líder lanza 3-5 subagentes en paralelo (no en serie) y cada subagente usa varias herramientas en paralelo. Es lo que produce la reducción real de tiempo.
Resúmenes condensados: los subagentes devuelven al coordinador resúmenes de típicamente 1.000-2.000 tokens, no su transcripción completa. El trabajo pesado se guarda en archivos y se pasan referencias ligeras.

Worktrees manuales

También puedes crear worktrees manualmente para sesiones paralelas:

# Terminal 1
claude --worktree feature-a
# Trabaja en feature A

# Terminal 2
claude --worktree feature-b
# Trabaja en feature B simultáneamente

Otras vías de paralelización

Los worktrees no son la única forma documentada de correr trabajo en paralelo:

Vía	Cómo
Worktrees	`claude --worktree feature-auth`
App de escritorio	Varias sesiones en la misma máquina
Claude Code on the web	`claude --cloud` / `--remote` para crear la sesión, `--teleport` para traerla al terminal
Fan-out headless	Loop de `claude -p "..."` sobre una lista de archivos
Agent teams	Lo descrito en este capítulo

Ejemplo de fan-out headless para una migración:

for file in $(git ls-files 'src/**/*.ts'); do
  claude -p "Migrate $file to the new API. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

La recomendación es probar con 2-3 archivos antes de lanzar el set completo.

Patrón Writer/Reviewer

Un uso de dos sesiones paralelas que sí encaja bien con código: una sesión escribe y otra, con contexto fresco, revisa. La razón es concreta: un contexto fresco no está sesgado hacia el código que acaba de escribir.

# Terminal 1 — writer
claude --worktree feature-auth

# Terminal 2 — reviewer, contexto limpio sobre el mismo diff
claude -p "Revisa este diff contra el plan. Marca solo gaps que afecten
corrección o requisitos declarados."

Limpieza

Los worktrees se limpian automáticamente si el agente no hizo cambios. Si hay cambios, el worktree persiste y se te pregunta si quieres conservarlo al salir de la sesión.

Coste y cuándo NO usar agent teams

Antes de montar un equipo conviene mirar la economía medida por Anthropic:

Un agente usa aproximadamente 4x más tokens que una interacción de chat.
Un sistema multi-agente usa ~15x más tokens que un chat.
Subir de modelo rinde más que duplicar el presupuesto de tokens.

El antipatrón documentado es usar multi-agente cuando todos los agentes necesitan el mismo contexto o cuando hay fuertes interdependencias entre las subtareas — «como la mayoría de tareas de código». Los agentes tienen dificultad para coordinarse y delegar en tiempo real.

Multi-agente conviene cuando:

La tarea se paraleliza en direcciones independientes.
Los requisitos de información exceden una sola ventana de contexto.
El valor de la tarea paga el sobrecoste de tokens.

flowchart TD
    Q{"¿La tarea se divide en direcciones\nindependientes sin contexto compartido?"}
    Q -- No --> S["Sesión única\n(sube de modelo o de effort)"]
    Q -- Sí --> C{"¿El valor de la tarea paga\n~15x tokens?"}
    C -- No --> S
    C -- Sí --> M["Agent team + worktrees"]

Mejores prácticas

Tareas independientes: asigna subtareas que no se pisen entre sí
Commits frecuentes: cada agente commitea su progreso
Worktrees para aislamiento: evita conflictos de merge (aislamiento de contexto, no de seguridad)
Coordinator agent: un agente principal que orquesta
Tests después de merge: ejecutar la suite completa al integrar
Instrucciones completas por subagente: objetivo, formato de salida, herramientas/fuentes y límites
Lanza en paralelo, no en serie: 3-5 subagentes en una sola tanda
Evalúa primero si hace falta: si todos los agentes necesitan el mismo contexto, una sesión única con mejor modelo suele ganar

Siguiente: Ralph Wiggum Loop