Cap 11: Agent Teams y Worktrees

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

1. El agente principal divide la tarea en subtareas
2. Lanza sub-agentes en paralelo (cada uno en su worktree)
3. Los sub-agentes trabajan de forma independiente
4. 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

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

proyecto/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/     ← worktree 1
│       ├── fix-tests/        ← worktree 2
│       └── update-docs/      ← worktree 3
└── (directorio principal)

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
isolation: worktree
tools: ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
---

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

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

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

# Iniciar con teammate mode en tmux
claude --teammate-mode tmux

# Prompt al agente principal
"Implementa el sistema de notificaciones. Divide el trabajo:
- Un agente para el backend (API endpoints)
- Un agente para el frontend (componentes React)
- Un agente para los tests
Coordina el trabajo y presenta un resumen al final."

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

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.

Mejores prácticas

1. Tareas independientes: asigna subtareas que no se pisen entre sí
2. Commits frecuentes: cada agente commitea su progreso
3. Worktrees para aislamiento: evita conflictos de merge
4. Coordinator agent: un agente principal que orquesta
5. Tests después de merge: ejecutar la suite completa al integrar

---

Siguiente: Ralph Wiggum Loop