Voce ja viu as capturas de tela. Cinco, dez, quinze agentes Claude Code rodando no tmux, cada um trabalhando em uma parte diferente da mesma codebase. Parece produtivo. Parece empolgante. E se voce tentou replicar, sabe que parece bem mais facil do que realmente e.
Rodar um agente Claude Code e simples. Voce da uma tarefa, ele escreve codigo, voce revisa. Dois sao gerenciaveis, mas introduzem um problema novo: podem pisar nos commits um do outro. Cinco exigem um sistema. Dez sem sistema e caos com fatura mensal.
Este guia trata desse sistema. Nao a teoria de arquiteturas multi-agente. O workflow real e pratico para rodar multiplos agentes Claude Code em uma codebase real sem que tudo desmorone.
Por que um agente nao basta
Um unico agente Claude Code da conta de uma quantidade surpreendente de trabalho. Mas e sequencial. Enquanto ele implementa um endpoint de backend, seu frontend fica parado. Enquanto escreve testes, a documentacao fica defasada. Enquanto depura uma falha de build, tres features novas esperam na fila.
A conta muda quando voce percebe que a maior parte do trabalho de software e paralelizavel. Um componente de frontend e um endpoint de API nao compartilham arquivos. Uma suite de testes e uma atualizacao de documentacao tocam diretorios diferentes. Uma revisao de arquitetura e um bugfix operam em escalas de tempo completamente distintas.
O gargalo no desenvolvimento com um unico agente nao e a velocidade do agente. E a profundidade do pipeline. Um agente significa uma coisa em andamento por vez. Multiplos agentes significam varias coisas em andamento simultaneamente, e isso muda o que um unico desenvolvedor consegue entregar em um dia.
Estrategias de divisao do trabalho
Antes de abrir um segundo painel tmux, voce precisa decidir como dividir o trabalho. Tres padroes funcionam na pratica.
Divisao por componente
A abordagem mais simples. O Agente A e dono de components/, o Agente B de server/, o Agente C de lib/. Cada agente trabalha em seu territorio e nunca toca em arquivos fora dele.
Funciona bem quando sua codebase tem fronteiras arquiteturais claras. Uma app Next.js com componentes de frontend distintos, actions de backend e bibliotecas compartilhadas se divide naturalmente ao longo dessas linhas.
A limitacao: trabalho transversal. Uma feature que exige mudancas na UI, na API e na camada de dados nao cabe perfeitamente no territorio de um unico agente. Resolve-se quebrando a feature em subtarefas com escopo por componente e sequenciando-as.
Divisao por papel
Em vez de dividir por localizacao de codigo, divida por funcao. Um agente escreve codigo. Outro escreve testes. Um terceiro cuida da documentacao. Um quarto faz code review.
Isso espelha o funcionamento de times humanos e produz maior qualidade porque o agente de testes nao sabe (nem se importa) o quao facil foi escrever o codigo. Ele testa contra a spec, nao contra as suposicoes do autor.
A contrapartida e mais sobrecarga de coordenacao. O agente de testes precisa que o agente de implementacao termine primeiro. O agente de documentacao precisa de ambos. Voce esta gerenciando um pipeline, nao apenas workers paralelos.
Divisao por fase do ciclo de vida
Uma versao mais sofisticada da divisao por papel. Um agente faz brainstorm e planeja. Outro implementa. Um terceiro verifica. O trabalho flui pelas fases, e cada agente e especializado na sua.
Esse e o padrao que usamos no Beadbox. Nosso agente arquiteto projeta, nossos agentes de engenharia implementam, nossos agentes de QA verificam independentemente. A mesma tarefa flui por multiplos especialistas, e cada um adiciona uma camada de qualidade que agentes generalistas nao alcancam. Escrevi sobre o setup completo em Eu Envio Software com 13 Agentes de IA.
A estrategia certa depende do seu projeto. Projetos pequenos com fronteiras de arquivo claras vao bem com divisao por componente. Projetos maiores onde qualidade importa se beneficiam de divisao por papel ou ciclo de vida. A maioria dos times acaba com um hibrido.
O padrao de identidade CLAUDE.md
Aqui a teoria encontra a implementacao. Cada agente Claude Code recebe seu proprio arquivo CLAUDE.md, e esse arquivo e a peca mais importante de todo o sistema multi-agente.
Um CLAUDE.md define quatro coisas:
- O que o agente e. Seu papel, especialidade e dominio.
- O que ele possui. Os arquivos, diretorios ou responsabilidades que controla.
- O que nao deve tocar. As fronteiras explicitas que previnem conflitos.
- Como se comunica. Os protocolos para reportar trabalho e coordenar com outros agentes.
Aqui um exemplo real. Dois agentes Claude Code com escopos complementares:
# 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>"
Note as linhas explicitas "DO NOT MODIFY". Sem elas, agentes derivam. Eles veem uma oportunidade de "ajudar" corrigindo um typo em um arquivo que nao lhes pertence, e de repente voce tem conflitos de merge. Ou pior, refatoram silenciosamente codigo do qual outro agente dependia.
A secao de identidade nao e decoracao. Claude Code le o CLAUDE.md no inicio de cada sessao e o usa para delimitar seu comportamento. Um agente que e informado de que e um "engenheiro frontend" vai naturalmente resistir a fazer mudancas de backend. Um agente que e informado de que possui diretorios especificos vai perguntar antes de modificar arquivos fora deles.
Evitando conflitos de merge
A propriedade em nivel de arquivo, como mostrado nos exemplos de CLAUDE.md acima, e a primeira linha de defesa. Mas nao a unica.
Faca commit e push frequentemente. Um agente que trabalha 45 minutos sem fazer commit esta construindo uma bomba-relogio de conflitos de merge. Instrua os agentes (no CLAUDE.md deles) a fazer commit apos completar cada unidade logica de trabalho.
Faca pull antes de comecar trabalho novo. Cada agente deve executar git pull --rebase antes de iniciar uma nova tarefa. Isso e trivialmente facil de garantir adicionando ao protocolo de inicializacao do agente no CLAUDE.md.
Use feature flags para trabalho transversal. Quando dois agentes precisam modificar o mesmo arquivo, a abordagem mais segura costuma ser um agente criar a interface ou flag, fazer commit e push, e entao o segundo agente fazer pull e construir em cima. Sequencial ganha de paralelo quando a alternativa e um pesadelo de merge.
Branches separados para trabalho arriscado. Se um agente esta fazendo algo experimental, de a ele seu proprio branch. Especialmente util para spikes de arquitetura ou trabalho de refatoracao que pode nao vingar.
Na pratica, a combinacao de regras de propriedade de arquivo e commits frequentes elimina 90% dos conflitos de merge. Os 10% restantes acontecem em arquivos compartilhados como types.ts ou package.json, e geralmente sao triviais de resolver.
Comunicacao entre agentes
Agentes Claude Code nao conseguem conversar diretamente entre si. Nao ha memoria compartilhada, barramento de mensagens ou canal em tempo real entre eles. Isso e na verdade uma coisa boa. Comunicacao direta entre agentes cria acoplamento, race conditions e pesadelos de depuracao.
Em vez disso, a comunicacao acontece por artefatos. Tres padroes funcionam:
Comentarios em tarefas
O padrao mais confiavel. O Agente A termina o trabalho e comenta em uma tarefa compartilhada: "DONE: endpoint /api/users implementado. Retorna JSON. O schema esta em lib/types.ts." O Agente B le o comentario e sabe exatamente o que esta disponivel.
Atualizacoes de status
Cada tarefa tem um status: open, in_progress, done, blocked. Quando o Agente A marca um pre-requisito como done, o Agente B (ou voce, ou um coordenador) sabe que o trabalho dependente pode comecar.
Mudancas em arquivos
A forma mais simples. O Agente A escreve uma interface TypeScript em lib/types.ts e faz commit. O Agente B faz pull e ve os novos tipos. Nenhuma comunicacao explicita necessaria porque o codigo em si e a mensagem.
O que NAO funciona: tentar construir um sistema de troca de mensagens em tempo real entre agentes. Se voce precisa que o Agente A espere a saida do Agente B, modele isso como uma dependencia entre tarefas, nao como uma chamada sincrona.
O loop de dispatch
Alguem precisa comandar o show. Em um setup multi-agente de Claude Code, ha duas opcoes: voce faz manualmente, ou designa um agente coordenador.
Dispatch manual
Voce mantem uma lista de tarefas. Voce atribui tarefas aos agentes. Voce verifica o progresso. Voce resolve blockers. Funciona ate uns cinco agentes antes que a sobrecarga de coordenacao comece a consumir os ganhos de produtividade.
Um ciclo tipico de dispatch manual se parece com isto:
- Manha: Revisar o que esta em andamento, bloqueado, pronto para trabalhar
- Atribuir: Enviar a cada agente sua proxima tarefa com contexto
- Monitorar: A cada 10-15 minutos, verificar a saida dos agentes buscando sinais de travamento
- Desbloquear: Quando um agente encontra um problema, intervir ou reatribuir
- Encerrar: No final do dia, revisar o que foi entregue e planejar o dia seguinte
No tmux, isso e percorrer paineis, ler a saida recente e decidir o que cada agente precisa. Ferramentas como gp (espiar a saida recente de um agente sem interrompe-lo) ajudam, mas voce continua sendo o gargalo.
Agente coordenador
Dedique um agente Claude Code para despachar trabalho para os outros. Este agente nao escreve codigo. Ele le o backlog de tarefas, atribui trabalho a agentes disponiveis, verifica o progresso e gerencia o loop de dispatch programaticamente.
Esse e o padrao que usamos. Nosso agente "super" roda um loop de patrulha: a cada poucos minutos, ele verifica cada agente ativo, checa status de tarefas, identifica blockers e despacha novo trabalho quando um agente fica ocioso. O humano (eu) toma as decisoes de prioridade e resolve situacoes ambiguas. Super cuida da logistica.
Um agente coordenador precisa de seu proprio 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
O padrao de coordenador escala muito melhor que o dispatch manual. Com 10+ agentes, coordenacao manual e um emprego de tempo integral. Um agente coordenador lida com a logistica de rotina e so escala as decisoes que exigem julgamento humano.
Layout tmux para trabalho multi-agente
O layout fisico importa mais do que voce imagina. Aqui uma configuracao tmux que funciona para rodar multiplos 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
Janelas nomeadas superam paineis divididos uma vez que voce passa de quatro agentes. Nao da para ler cinco paineis em uma unica tela, mas da para alternar rapidamente entre janelas nomeadas. A convencao de nomes tambem importa. eng1, eng2, qa1 sao imediatamente escaneaveis. agent-1, agent-2, agent-3 nao dizem nada.
Inicie cada agente em seu proprio diretorio de trabalho com seu proprio 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
Uma dica pratica: mantenha uma janela "dashboard" que e apenas um shell. Use para rodar git log --oneline -10, verificar status de tarefas ou observar agentes sem interromper o trabalho deles. Esse sera seu centro de comando.
Quando as coisas dao errado
Workflows multi-agente falham de formas previsiveis. Conhecer os modos de falha evita que voce os aprenda da maneira dificil.
Dois agentes editam o mesmo arquivo. Geralmente porque a propriedade de arquivos no CLAUDE.md nao era especifica o suficiente. lib/utils.ts e um classico ima de conflitos. Solucao: ou atribua arquivos utilitarios compartilhados a um agente especifico, ou torne-os somente leitura para todos e direcione mudancas por um unico proprietario.
Um agente fica em silencio. Bateu em um rate limit, um loop de erro, ou ficou preso em uma cadeia profunda de raciocinio. Verifique a saida. Se esta retentando o mesmo comando falhando, mate a sessao e reinicie com instrucoes mais claras. Verificacoes de saude periodicas (a cada 10-15 minutos) pegam isso antes que voce perca uma hora.
Context windows enchem. Agentes de longa duracao acumulam contexto e comecam a performar pior. O CLAUDE.md de cada agente deve incluir um protocolo para isso: "Se voce esta trabalhando ha mais de 90 minutos, salve seu estado e solicite uma nova sessao." Na pratica, isso significa que o agente faz commit do trabalho, anota onde parou, e uma nova sessao de Claude Code retoma daquele commit.
Trabalho desvia da spec. O agente constroi algo que tecnicamente funciona mas nao corresponde ao que foi pedido. A solucao e o padrao de planejar antes de codar: antes de escrever qualquer codigo, o agente comenta seu plano de implementacao. Voce revisa o plano em 60 segundos e pega mal-entendidos antes que se tornem diffs de 500 linhas.
O pipeline estagna. O Agente B espera o Agente A, mas o Agente A espera uma decisao sua. Enquanto isso, o Agente C terminou seu trabalho ha 30 minutos e esta ocioso. Isso e uma falha de coordenacao, nao tecnica. O agente coordenador (ou voce) precisa manter o pipeline em movimento monitorando blockers e reatribuindo agentes ociosos.
Tudo acima funciona com post-its e boas intencoes. Mas por volta de cinco agentes, a abordagem informal comeca a rachar. Voce esquece no que o Agente C estava trabalhando. Perde o rastro de quais tarefas estao bloqueadas. Nao lembra se o endpoint de API que o Agente B precisa foi finalizado ou apenas iniciado.
Esse e o problema que o beads resolve. Beads e um issue tracker open-source e local-first. Cada tarefa e um "bead" com um ID unico, um status, uma descricao, criterios de aceitacao, dependencias e um thread de comentarios. Tudo acessivel por um CLI chamado bd, o que significa que seus agentes Claude Code podem ler e escrever nele sem sair do terminal.
Veja como o loop de dispatch fica com 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 segue este protocolo: reivindicar, planejar, implementar, comentar DONE, atualizar status. O thread de comentarios de cada bead se torna um registro de auditoria completo do que aconteceu, por que e como verificar.
Dependencias previnem trabalho conflitante:
# 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."
A tarefa dependente permanece bloqueada ate que bb-a1b2 esteja concluida. Nenhum agente vai pega-la prematuramente. Ninguem perde tempo construindo um frontend para uma API que ainda nao existe.
O comando bd list da uma foto do pipeline inteiro:
bd list --status in_progress
# Shows what every agent is actively working on
bd blocked
# Mostra tarefas aguardando dependencias nao concluidas
bd list --status open --priority p1
# Shows the highest-priority work that's ready to start
Isso substitui o modelo mental que voce mantinha na cabeca. O estado de cada tarefa, o trabalho atual de cada agente, cada cadeia de dependencias, tudo consultavel pela linha de comando.
Escalando a visibilidade
O CLI funciona. Mas em escala, ha um limite para o quanto voce consegue absorver rodando bd list no terminal. Quando voce tem oito agentes trabalhando em tres epics com dezessete tarefas abertas e uma duzia de dependencias, voce precisa ver a forma do trabalho, nao apenas uma lista.
Essa e a lacuna que construimos o Beadbox para preencher. Beadbox e um dashboard em tempo real que fica sobre o beads e mostra:
- Arvores de epics com barras de progresso, para ver como cada feature avanca em todas as suas subtarefas
- Grafos de dependencias que revelam trabalho bloqueado antes que paralise o pipeline
- Atividade dos agentes mostrando qual agente esta trabalhando em que, com seus comentarios de plano e done visiveis no contexto
- Atualizacoes em tempo real porque o dashboard monitora sua base de dados beads e atualiza conforme agentes mudam status de tarefas
Beadbox nao substitui o CLI. Seus agentes continuam lendo e escrevendo no beads pelo bd. Beadbox te da a visao geral para que voce possa tomar as decisoes de julgamento: qual epic esta atrasando, qual agente precisa de ajuda, onde o gargalo esta se formando.
E gratuito durante a beta. Se voce esta construindo workflows como este, de uma estrela no Beadbox no GitHub.
Primeiros passos
Voce nao precisa de treze agentes para se beneficiar disso. Aqui o setup minimo viavel:
- Dois agentes Claude Code em janelas tmux separadas, cada um com seu proprio CLAUDE.md definindo fronteiras de propriedade de arquivos.
- Uma lista de tarefas (mesmo um arquivo de texto funciona nessa escala) para que ambos os agentes saibam no que estao trabalhando e o que vem a seguir.
- Um protocolo de commits: ambos os agentes fazem commit frequentemente e pull antes de iniciar trabalho novo.
Quando isso se tornar natural, adicione um terceiro agente para testes ou documentacao. Depois considere um agente coordenador. Depois adote beads para rastreamento estruturado de tarefas. Escale o sistema conforme a dor de coordenacao aumentar, nao antes.
O dificil nao e o tooling. E a mudanca de perspectiva: de "estou usando um assistente de IA" para "estou gerenciando um time." Os arquivos CLAUDE.md, os protocolos de dispatch, as fronteiras de propriedade: sao praticas de gestao, nao arquivos de configuracao. Voce esta construindo uma organizacao, mesmo que os membros do time rodem em chamadas de API.
Comece com dois agentes e fronteiras claras. Todo o resto vem dai.
