Tabla de Contenidos
- Resumen
- Cuándo Usar
- Requisitos Previos
- Arquitectura del Protocolo
- Inicio Rápido
- Flujo de Coordinación
- Referencia de Módulos
- Integración con Conjure
- Solución de Problemas
- Criterios de Salida
Coordinación de Equipos de Agentes
Resumen
Claude Code Agent Teams permite que múltiples procesos CLI de Claude colaboren en trabajo compartido mediante un protocolo de coordinación basado en el sistema de archivos. Cada miembro del equipo se ejecuta como un proceso claude independiente en un panel de tmux, comunicándose a través de archivos JSON protegidos por bloqueos fcntl. Sin base de datos, sin demonio, sin capa de red.
Esta habilidad proporciona los patrones para orquestar equipos de agentes de manera efectiva.
Cuándo Usar
- Implementación en paralelo en múltiples archivos o módulos
- Revisión de código multiagente (un agente revisa, otro implementa correcciones)
- Refactorización grande que requiere cambios coordinados entre subsistemas
- Tareas con paralelismo natural que se benefician de agentes concurrentes
Cuándo NO Usar
- Cambios en un solo archivo o tareas pequeñas (la sobrecarga supera el beneficio)
- Tareas que requieren razonamiento secuencial estricto (los agentes se coordinan de forma libre)
- Cuando la CLI
claudeno está disponible o tmux no está instalado
Requisitos Previos
# Verificar CLI de Claude Code
claude --version
# Verificar tmux (necesario para modo de paneles divididos)
tmux -V
# Habilitar función experimental (configurada automáticamente por el spawner)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Arquitectura del Protocolo
~/.claude/
teams/<team-name>/
config.json # Metadatos del equipo + lista de miembros
inboxes/
<agent-name>.json # Cola de mensajes por agente
.lock # Bloqueo exclusivo fcntl
tasks/<team-name>/
1.json ... N.json # Archivos de tareas con numeración automática
.lock # Bloqueo exclusivo fcntl
Principios de diseño:
- El sistema de archivos es la base de datos: archivos JSON, escrituras atómicas mediante
tempfile+os.replace - Bloqueo fcntl: evita corrupción de lectura/escritura concurrente en bandejas de entrada y tareas
- Tareas numeradas: IDs auto-incrementales con nombres de archivo secuenciales
- Acoplamiento flexible: los agentes consultan su propia bandeja de entrada; sin notificaciones push
Inicio Rápido
1. Crear un Equipo
# Configuración programática del equipo (a través de MCP o API directa)
# La configuración del equipo se escribe en ~/.claude/teams/<team-name>/config.json
La configuración del equipo contiene:
name,description,created_at(marca de tiempo en ms)lead_agent_id,lead_session_idmembers[]— array de objetos LeadMember y TeammateMember
2. Generar Compañeros de Equipo
Cada compañero de equipo es un proceso CLI claude separado, lanzado con banderas de identidad:
claude --agent-id "backend@my-team" \
--agent-name "backend" \
--team-name "my-team" \
--agent-color "#FF6B6B" \
--parent-session-id "$SESSION_ID" \
--agent-type "general-purpose" \
--model sonnet
Consulta modules/spawning-patterns.md para la gestión de paneles de tmux y asignación de colores.
3. Crear Tareas con Dependencias
{
"id": "1",
"subject": "Implementar endpoints de API",
"description": "Crear endpoints REST para gestión de usuarios",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
Consulta modules/task-coordination.md para la máquina de estados y gestión de dependencias.
4. Coordinar mediante Mensajes
{
"from": "team-lead",
"text": "Los endpoints de API están listos para pruebas de integración",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API lista"
}
Consulta modules/messaging-protocol.md para tipos de mensajes y operaciones de bandeja de entrada.
Flujo de Coordinación
agent-teams:team-created— Inicializar configuración y directorios del equipoagent-teams:teammates-spawned— Lanzar agentes en paneles de tmuxagent-teams:tasks-assigned— Crear tareas con dependencias, asignar propietariosagent-teams:coordination-active— Los agentes reclaman tareas, intercambian mensajes, marcan finalizaciónagent-teams:team-shutdown— Apagado ordenado con protocolo de aprobación
Roles del Equipo
Cada miembro del equipo tiene un role que determina sus capacidades y compatibilidad con tareas. Se definen cinco roles: implementer (predeterminado), researcher, tester, reviewer y architect. Los roles restringen qué niveles de riesgo puede manejar un agente; consulta modules/crew-roles.md para la matriz completa de capacidades y la tabla de compatibilidad rol-riesgo.
Monitoreo de Salud
Los miembros del equipo pueden ser monitoreados para determinar su salud mediante mensajes de latido y vencimiento de reclamos. El líder consulta la salud del equipo cada 60s con un protocolo de detección de bloqueo de 2 etapas (sonda health_check + espera de 30s). Los agentes bloqueados liberan sus tareas y son reiniciados o reemplazados siguiendo la doctrina "reemplazar, no esperar". Consulta modules/health-monitoring.md para el protocolo completo y la máquina de estados.
Referencia de Módulos
- team-management.md: Ciclo de vida del equipo, formato de configuración, gestión de miembros
- messaging-protocol.md: Tipos de mensajes, operaciones de bandeja de entrada, patrones de bloqueo
- task-coordination.md: CRUD de tareas, máquina de estados, detección de ciclos de dependencia
- spawning-patterns.md: Generación de paneles tmux, banderas CLI, gestión de paneles
- crew-roles.md: Taxonomía de roles, matriz de capacidades, compatibilidad rol-riesgo
- health-monitoring.md: Protocolo de latido, detección de bloqueo, recuperación automatizada
Integración con Conjure
Agent Teams extiende el modelo de delegación de conjure:
| Patrón de Conjure | Equivalente en Agent Teams |
|---|---|
delegation-core:task-assessed | agent-teams:team-created |
delegation-core:handoff-planned | agent-teams:tasks-assigned |
delegation-core:results-integrated | agent-teams:team-shutdown |
| Ejecución LLM externa | Ejecución del agente compañero |
Usa Skill(conjure:delegation-core) primero para determinar si la tarea se beneficia de la coordinación multiagente frente a la delegación de un solo servicio.
Alternativa de Aislamiento por Worktree (Claude Code 2.1.49+)
Para agentes paralelos que modifican archivos, isolation: worktree proporciona una alternativa ligera a la coordinación basada en el sistema de archivos. Cada agente se ejecuta en su propio worktree temporal de git, eliminando la necesidad de bloqueos fcntl o evitación de conflictos basada en bandejas de entrada en archivos compartidos.
- Cuándo preferir worktrees sobre la mensajería de agent teams: Los agentes trabajan en archivos superpuestos pero no necesitan comunicación durante la ejecución
- Cuándo preferir la mensajería de agent teams: Los agentes necesitan coordinar descubrimientos o ajustar planes según el progreso de los demás
- Combinar ambos: Usa agent teams para la coordinación con
isolation: worktreepor compañero para seguridad del sistema de archivos
Solución de Problemas
Problemas Comunes
tmux no encontrado
Instálalo mediante el gestor de paquetes: brew install tmux / apt install tmux
Archivos de bloqueo obsoletos
Si un agente falla durante una operación, los archivos de bloqueo pueden persistir. Elimina los archivos .lock manualmente de ~/.claude/teams/<team>/inboxes/ o ~/.claude/tasks/<team>/
Tareas huérfanas
Las tareas reclamadas por un agente que falló permanecen en in_progress indefinidamente. Usa modules/health-monitoring.md para la detección de bloqueo basada en latidos y la liberación automática de tareas. El protocolo de monitoreo de salud detecta agentes que no responden dentro de una ventana de 60s + 30s de sonda y libera sus tareas para reasignación.
Orden de mensajes La resolución de marcas de tiempo del sistema de archivos varía (HFS+ = granularidad de 1s). Usa nombres de archivo numerados o nombres ordenados por UUID para evitar colisiones en ráfagas rápidas de mensajes.
Errores de modelo en Bedrock/Vertex/Foundry (antes de 2.1.39) Los agentes compañeros podían usar identificadores de modelo incorrectos en proveedores empresariales, causando errores 400. Actualiza a Claude Code 2.1.39+ para la calificación correcta del ID de modelo en todos los proveedores.
Protección de sesión anidada (2.1.39+)
Si claude se niega a lanzarse dentro de una sesión existente, asegúrate de usar la división de paneles de tmux (no invocación en subproceso). La protección es intencional; consulta modules/spawning-patterns.md para más detalles.
Criterios de Salida
- Equipo creado con configuración y directorios
- Compañeros de equipo generados y registrados en la configuración
- Tareas creadas con grafo de dependencias (sin ciclos)
- Agentes coordinándose mediante mensajes de bandeja de entrada
- Apagado ordenado completado