Has visto las capturas de pantalla. Cinco, diez, quince agentes Claude Code corriendo en tmux, cada uno trabajando en una parte diferente de la misma codebase. Parece productivo. Parece emocionante. Y si has intentado replicarlo, sabes que se ve mucho mas facil de lo que es.
Ejecutar un agente Claude Code es sencillo. Le das una tarea, escribe codigo, tu revisas. Dos son manejables pero introducen un nuevo problema: podrian pisar los cambios del otro. Cinco requieren un sistema. Diez sin sistema es caos con factura mensual.
Esta guia trata sobre ese sistema. No la teoria de arquitecturas multi-agente. El workflow real y practico para ejecutar multiples agentes Claude Code en una codebase real sin que todo se desmorone.
Por que un agente no es suficiente
Un solo agente Claude Code puede manejar una cantidad sorprendente de trabajo. Pero es secuencial. Mientras implementa un endpoint de backend, tu frontend esta parado. Mientras escribe tests, la documentacion se queda atras. Mientras depura un fallo de build, tres features nuevas esperan en la cola.
La matematica cambia cuando te das cuenta de que la mayor parte del trabajo de software es paralelizable. Un componente de frontend y un endpoint de API no comparten archivos. Una suite de tests y una actualizacion de documentacion tocan directorios diferentes. Una revision de arquitectura y un bugfix operan en escalas de tiempo completamente distintas.
El cuello de botella en desarrollo con un solo agente no es la velocidad del agente. Es la profundidad del pipeline. Un agente significa una cosa en progreso a la vez. Multiples agentes significan multiples cosas en progreso simultaneamente, y eso cambia lo que un solo desarrollador puede entregar en un dia.
Estrategias de division del trabajo
Antes de abrir un segundo panel tmux, necesitas decidir como dividir el trabajo. Tres patrones funcionan en la practica.
Division por componente
El enfoque mas simple. El Agente A es dueno de components/, el Agente B de server/, el Agente C de lib/. Cada agente trabaja en su territorio y nunca toca archivos fuera de el.
Esto funciona bien cuando tu codebase tiene limites arquitectonicos claros. Una app Next.js con componentes de frontend distintos, acciones de backend y librerias compartidas se divide naturalmente a lo largo de esas lineas.
La limitacion: trabajo transversal. Un feature que requiere cambios en la UI, la API y la capa de datos no encaja limpiamente en el territorio de un solo agente. Se resuelve desglosando el feature en subtareas con scope por componente y secuenciandolas.
Division por rol
En lugar de dividir por ubicacion de codigo, divide por funcion. Un agente escribe codigo. Otro escribe tests. Un tercero se encarga de documentacion. Un cuarto hace code review.
Esto refleja como trabajan los equipos humanos y produce mayor calidad porque el agente de tests no sabe (ni le importa) lo facil que fue escribir el codigo. Testea contra la spec, no contra las suposiciones del autor.
El compromiso es mas sobrecarga de coordinacion. El agente de tests necesita que el agente de implementacion termine primero. El agente de documentacion necesita ambos. Estas gestionando un pipeline, no solo workers paralelos.
Division por fase del ciclo de vida
Una version mas sofisticada de la division por roles. Un agente hace brainstorm y planifica. Otro implementa. Un tercero verifica. El trabajo fluye a traves de fases, y cada agente esta especializado para su fase.
Este es el patron que usamos en Beadbox. Nuestro agente arquitecto disena, nuestros agentes de ingenieria implementan, nuestros agentes de QA verifican de forma independiente. La misma tarea fluye a traves de multiples especialistas, y cada uno agrega una capa de calidad que los agentes generalistas no alcanzan. Escribi sobre el setup completo en Envio Software con 13 Agentes de IA.
La estrategia correcta depende de tu proyecto. Proyectos pequenos con limites de archivo claros van bien con division por componente. Proyectos mas grandes donde importa la calidad se benefician de la division por rol o ciclo de vida. La mayoria de los equipos terminan con un hibrido.
El patron de identidad CLAUDE.md
Aqui es donde la teoria se encuentra con la implementacion. Cada agente Claude Code recibe su propio archivo CLAUDE.md, y este archivo es la pieza mas importante del sistema multi-agente.
Un CLAUDE.md define cuatro cosas:
- Que es el agente. Su rol, especialidad y dominio.
- Que posee. Los archivos, directorios o responsabilidades que controla.
- Que no debe tocar. Los limites explicitos que previenen conflictos.
- Como se comunica. Los protocolos para reportar trabajo y coordinar con otros agentes.
Aqui un ejemplo real. Dos agentes Claude Code con scopes complementarios:
# CLAUDE.md for Agent: frontend-eng
## Identity
Frontend engineer. You implement UI components, pages, and client-side
logic. You own everything under components/, app/, and hooks/.
## File Ownership
- components/** (you own these)
- app/** (you own these)
- hooks/** (you own these)
- lib/utils.ts (shared, read-only for you)
- server/** (DO NOT MODIFY — owned by backend-eng)
## Communication
When you need a backend change, create a task describing what API
you need. Do not implement it yourself.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
# CLAUDE.md for Agent: backend-eng
## Identity
Backend engineer. You implement server actions, API routes, and
data layer logic. You own everything under server/, actions/, and lib/.
## File Ownership
- server/** (you own these)
- actions/** (you own these)
- lib/** (you own these, except utils.ts is shared)
- components/** (DO NOT MODIFY — owned by frontend-eng)
- app/** (DO NOT MODIFY — owned by frontend-eng)
## Communication
When you change a data type in lib/types.ts, notify frontend-eng
by commenting on the relevant task.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
Nota las lineas explicitas "DO NOT MODIFY". Sin estas, los agentes se desvian. Ven una oportunidad de "ayudar" corrigiendo un typo en un archivo que no les pertenece, y de repente tienes conflictos de merge. O peor, refactorizan silenciosamente codigo del que otro agente dependia.
La seccion de identidad no es decoracion. Claude Code lee CLAUDE.md al inicio de cada sesion y la usa para delimitar su comportamiento. Un agente al que le dicen que es un "ingeniero frontend" resistira naturalmente hacer cambios de backend. Un agente al que le dicen que posee directorios especificos preguntara antes de modificar archivos fuera de ellos.
Evitando conflictos de merge
La propiedad a nivel de archivo, como se muestra en los ejemplos de CLAUDE.md arriba, es la primera linea de defensa. Pero no la unica.
Commitea y pushea frecuentemente. Un agente que trabaja 45 minutos sin commitear esta construyendo una bomba de tiempo de conflictos de merge. Instruye a los agentes (en su CLAUDE.md) a commitear despues de completar cada unidad logica de trabajo.
Pullea antes de empezar trabajo nuevo. Cada agente deberia ejecutar git pull --rebase antes de comenzar una nueva tarea. Esto es trivialmente facil de aplicar agregandolo al protocolo de inicio del agente en CLAUDE.md.
Usa feature flags para trabajo transversal. Cuando dos agentes necesitan modificar el mismo archivo, el enfoque mas seguro suele ser que un agente cree la interfaz o flag, commitee y pushee, y luego el segundo agente pullee y construya sobre eso. Secuencial gana sobre paralelo cuando la alternativa es una pesadilla de merges.
Branches separados para trabajo riesgoso. Si un agente esta haciendo algo experimental, dale su propio branch. Especialmente util para spikes de arquitectura o trabajo de refactoring que podria no prosperar.
En la practica, la combinacion de reglas de propiedad de archivos y commits frecuentes elimina el 90% de los conflictos de merge. El 10% restante ocurre en archivos compartidos como types.ts o package.json, y generalmente son triviales de resolver.
Comunicacion entre agentes
Los agentes Claude Code no pueden hablar entre si directamente. No hay memoria compartida, no hay bus de mensajes, no hay canal en tiempo real entre ellos. Esto es en realidad algo bueno. La comunicacion directa entre agentes crea acoplamiento, race conditions y pesadillas de depuracion.
En su lugar, la comunicacion ocurre a traves de artefactos. Tres patrones funcionan:
Comentarios en tareas
El patron mas confiable. El Agente A termina trabajo y comenta en una tarea compartida: "DONE: endpoint /api/users implementado. Retorna JSON. El schema esta en lib/types.ts." El Agente B lee el comentario y sabe exactamente que esta disponible.
Actualizaciones de estado
Cada tarea tiene un estado: open, in_progress, done, blocked. Cuando el Agente A marca un prerrequisito como done, el Agente B (o tu, o un coordinador) sabe que el trabajo dependiente puede comenzar.
Cambios en archivos
La forma mas simple. El Agente A escribe una interfaz TypeScript en lib/types.ts y commitea. El Agente B pullea y ve los nuevos tipos. No se necesita comunicacion explicita porque el codigo mismo es el mensaje.
Lo que NO funciona: intentar construir un sistema de paso de mensajes en tiempo real entre agentes. Si necesitas que el Agente A espere el output del Agente B, modela eso como una dependencia entre tareas, no como una llamada sincrona.
El bucle de dispatch
Alguien necesita dirigir el espectaculo. En un setup multi-agente de Claude Code, hay dos opciones: lo haces manualmente, o designas un agente coordinador.
Dispatch manual
Mantienes una lista de tareas. Asignas tareas a agentes. Verificas el progreso. Manejas blockers. Esto funciona hasta unos cinco agentes antes de que la sobrecarga de coordinacion empiece a comerse las ganancias de productividad.
Un ciclo tipico de dispatch manual se ve asi:
- Manana: Revisar que esta en progreso, que esta bloqueado, que esta listo para trabajar
- Asignar: Enviar a cada agente su siguiente tarea con contexto
- Monitorear: Cada 10-15 minutos, revisar el output del agente buscando senales de estar atascado
- Desbloquear: Cuando un agente tiene un problema, intervenir o reasignar
- Cierre: Al final del dia, revisar que se entrego y planificar manana
En tmux, esto se ve como recorrer paneles, leer output reciente y decidir que necesita cada agente. Herramientas como gp (espiar el output reciente de un agente sin interrumpirlo) ayudan, pero tu sigues siendo el cuello de botella.
Agente coordinador
Dedica un agente Claude Code a despachar trabajo a los demas. Este agente no escribe codigo. Lee el backlog de tareas, asigna trabajo a agentes disponibles, verifica el progreso y maneja el bucle de dispatch programaticamente.
Este es el patron que usamos. Nuestro agente "super" ejecuta un loop de patrulla: cada pocos minutos, revisa cada agente activo, verifica estados de tareas, identifica blockers y despacha nuevo trabajo cuando un agente queda idle. El humano (yo) toma las decisiones de prioridad y resuelve situaciones ambiguas. Super maneja la logistica.
Un agente coordinador necesita su propio CLAUDE.md:
# CLAUDE.md for Agent: super
## Identity
Dispatch coordinator. You assign work to agents, monitor progress,
and ensure the pipeline keeps moving. You do NOT write code.
## Responsibilities
- Maintain awareness of all active tasks and their statuses
- Assign ready tasks to idle agents
- Monitor agent progress every 5-10 minutes
- Escalate blockers to the human when agents can't self-resolve
- Verify agents follow the protocol: plan before code, test before done
## Communication
- To assign work: message the agent with task ID and priority
- To check progress: peek at agent's recent output
- To escalate: message the human with context and options
El patron de coordinador escala mucho mejor que el dispatch manual. Con 10+ agentes, la coordinacion manual es un trabajo de tiempo completo. Un agente coordinador maneja la logistica rutinaria y solo escala las decisiones que requieren juicio humano.
Layout tmux para trabajo multi-agente
El layout fisico importa mas de lo que pensarias. Aqui una configuracion tmux que funciona para ejecutar multiples agentes Claude Code:
# Create a new tmux session
tmux new-session -s agents -n super
# Split into panes for each agent
tmux split-window -h -t agents:super
tmux split-window -v -t agents:super.1
# Or create named windows (easier to manage at scale)
tmux new-window -t agents -n eng1
tmux new-window -t agents -n eng2
tmux new-window -t agents -n qa1
tmux new-window -t agents -n frontend
tmux new-window -t agents -n backend
Las ventanas con nombre superan a los paneles divididos una vez que pasas cuatro agentes. No puedes leer cinco paneles en una sola pantalla, pero puedes cambiar rapidamente entre ventanas con nombre. La convencion de nombres tambien importa. eng1, eng2, qa1 son inmediatamente escaneables. agent-1, agent-2, agent-3 no te dicen nada.
Inicia cada agente en su propio directorio de trabajo con su propio CLAUDE.md:
# In the eng1 window
cd ~/project
claude --claude-md ./agents/eng1/CLAUDE.md
# In the qa1 window
cd ~/project
claude --claude-md ./agents/qa1/CLAUDE.md
Un tip practico: manten una ventana "dashboard" que sea solo una shell. Usala para ejecutar git log --oneline -10, verificar estado de tareas, o espiar agentes sin interrumpir su trabajo. Se convierte en tu centro de comando.
Cuando las cosas salen mal
Los workflows multi-agente fallan de formas predecibles. Conocer los modos de fallo te ahorra aprenderlos por las malas.
Dos agentes editan el mismo archivo. Generalmente porque la propiedad de archivos en CLAUDE.md no fue lo suficientemente especifica. lib/utils.ts es un clasico iman de conflictos. Solucion: o asigna archivos utilitarios compartidos a un agente especifico, o hazlos de solo lectura para todos y enruta cambios a traves de un solo dueno.
Un agente se queda en silencio. Llego a un rate limit, un bucle de errores, o se quedo atascado en una cadena profunda de razonamiento. Revisa el output. Si esta reintentando el mismo comando fallido, mata la sesion y reinicia con instrucciones mas claras. Chequeos de salud periodicos (cada 10-15 minutos) atrapan esto antes de que pierdas una hora.
Los context windows se llenan. Agentes de larga duracion acumulan contexto y empiezan a rendir peor. El CLAUDE.md de cada agente deberia incluir un protocolo para esto: "Si has estado trabajando por mas de 90 minutos, guarda tu estado y solicita una sesion nueva." En la practica, esto significa que el agente commitea su trabajo, anota donde se quedo, y una nueva sesion de Claude Code retoma desde ese commit.
El trabajo se desvia de la spec. El agente construye algo que tecnicamente funciona pero no coincide con lo que se pidio. La solucion es el patron de planificar-antes-de-codear: antes de escribir cualquier codigo, el agente comenta su plan de implementacion. Revisas el plan en 60 segundos y detectas malentendidos antes de que se conviertan en diffs de 500 lineas.
El pipeline se estanca. El Agente B espera al Agente A, pero el Agente A espera una decision tuya. Mientras tanto, el Agente C termino su trabajo hace 30 minutos y esta idle. Esto es un fallo de coordinacion, no tecnico. El agente coordinador (o tu) necesita mantener el pipeline en movimiento monitoreando blockers y reasignando agentes idle.
Como resolvimos esto con Beads
Todo lo anterior funciona con notas adhesivas y buenas intenciones. Pero alrededor de cinco agentes, el enfoque informal empieza a agrietarse. Olvidas en que estaba trabajando el Agente C. Pierdes la pista de que tareas estan bloqueadas. No recuerdas si el endpoint de API que el Agente B necesita fue terminado o apenas comenzado.
Este es el problema que resuelve beads. Beads es un issue tracker open-source y local-first. Cada tarea es un "bead" con un ID unico, un estado, una descripcion, criterios de aceptacion, dependencias y un hilo de comentarios. Todo accesible a traves de un CLI llamado bd, lo que significa que tus agentes Claude Code pueden leer y escribir en el sin salir de la terminal.
Asi se ve el bucle de dispatch con beads:
# See what's ready for work
bd list --status open
# Assign a task to an agent
bd update bb-a1b2 --claim --actor eng1
# Agent reads its assignment
bd show bb-a1b2
# Agent comments its plan before coding
bd comments add bb-a1b2 --author eng1 "PLAN:
1. Add endpoint at /api/users
2. Define UserResponse type in lib/types.ts
3. Write integration test
Files: server/api/users.ts (new), lib/types.ts (modify)
Test: curl localhost:3000/api/users returns 200 with JSON array"
# Agent finishes and comments what it did
bd comments add bb-a1b2 --author eng1 "DONE: /api/users endpoint live.
Returns paginated JSON. Added UserResponse type.
Verification:
1. curl http://localhost:3000/api/users → 200, JSON array
2. curl http://localhost:3000/api/users?page=2 → 200, second page
3. pnpm test → all passing
Commit: 8f3c2a1"
# Agent marks the task done
bd update bb-a1b2 --status closed
Cada agente sigue este protocolo: reclamar, planificar, implementar, comentar DONE, actualizar estado. El hilo de comentarios en cada bead se convierte en un registro de auditoria completo de que paso, por que y como verificarlo.
Las dependencias previenen trabajo conflictivo:
# Create a task that depends on another
bd create --title "Build user list component" \
--deps bb-a1b2 \
--description "Frontend component that calls /api/users. Blocked until API is live."
La tarea dependiente permanece bloqueada hasta que bb-a1b2 este hecha. Ningun agente la tomara prematuramente. Nadie pierde tiempo construyendo un frontend para una API que aun no existe.
El comando bd list te da una instantanea de todo el pipeline:
bd list --status in_progress
# Shows what every agent is actively working on
bd blocked
# Muestra tareas esperando dependencias no terminadas
bd list --status open --priority p1
# Shows the highest-priority work that's ready to start
Esto reemplaza el modelo mental que tenias en la cabeza. El estado de cada tarea, el trabajo actual de cada agente, cada cadena de dependencias, todo consultable desde la linea de comandos.
Escalando la visibilidad
El CLI funciona. Pero a escala, hay un limite de cuanto puedes absorber ejecutando bd list en una terminal. Cuando tienes ocho agentes trabajando en tres epics con diecisiete tareas abiertas y una docena de dependencias, necesitas ver la forma del trabajo, no solo una lista.
Esta es la brecha que construimos Beadbox para llenar. Beadbox es un dashboard en tiempo real que se situa sobre beads y te muestra:
- Arboles de epics con barras de progreso, para ver como avanza cada feature a traves de todas sus subtareas
- Grafos de dependencias que muestran trabajo bloqueado antes de que detenga el pipeline
- Actividad de agentes mostrando que agente esta trabajando en que, con sus comentarios de plan y done visibles en contexto
- Actualizaciones en tiempo real porque el dashboard observa tu base de datos beads y se refresca cuando los agentes actualizan estados de tareas
Beadbox no reemplaza el CLI. Tus agentes siguen leyendo y escribiendo en beads a traves de bd. Beadbox te da la vision general para que puedas tomar las decisiones de juicio: que epic se esta atrasando, que agente necesita ayuda, donde se esta formando el cuello de botella.
Es gratis durante la beta. Si estas construyendo workflows como este, dale una estrella a Beadbox en GitHub.
Primeros pasos
No necesitas trece agentes para beneficiarte de esto. Aqui el setup minimo viable:
- Dos agentes Claude Code en ventanas tmux separadas, cada uno con su propio CLAUDE.md definiendo limites de propiedad de archivos.
- Una lista de tareas (incluso un archivo de texto funciona a esta escala) para que ambos agentes sepan en que estan trabajando y que sigue.
- Un protocolo de commits: ambos agentes commitean frecuentemente y pullean antes de empezar trabajo nuevo.
Una vez que eso se sienta natural, agrega un tercer agente para testing o documentacion. Luego considera un agente coordinador. Despues adopta beads para tracking estructurado de tareas. Escala el sistema cuando el dolor de coordinacion aumente, no antes.
Lo dificil no es el tooling. Es el cambio de mentalidad: de "estoy usando un asistente de IA" a "estoy dirigiendo un equipo." Los archivos CLAUDE.md, los protocolos de dispatch, los limites de propiedad: son practicas de gestion, no archivos de configuracion. Estas construyendo una organizacion, aunque los miembros del equipo corran sobre llamadas a APIs.
Empieza con dos agentes y limites claros. Todo lo demas se deriva de ahi.
