Voce tem uma feature que precisa de tres coisas ao mesmo tempo. Voce pode spawnar subagentes dentro de uma unica sessao do Claude Code e deixa-los trabalhar em paralelo. Ou pode dividir o trabalho em tres tarefas independentes, entregar cada uma a um agente separado em seu proprio painel tmux, e deixa-los rodar sem saber nada um do outro.

Ambas as abordagens paralelizam trabalho. Resolvem problemas diferentes. Escolha a errada e voce vai queimar janela de contexto com overhead de coordenacao ou criar conflitos de merge que demoram mais para resolver do que a tarefa original.

Este e o framework de decisao que uso todo dia enquanto rodo 13 agentes Claude Code na mesma codebase. Nao e teorico. E o resultado de ter errado vezes suficientes para saber onde fica o limite.

Dois tipos de paralelismo

O Claude Code suporta duas formas distintas de executar trabalho concorrentemente.

Subagentes sao processos filhos spawnados dentro de uma unica sessao do Claude Code. O agente pai inicia multiplos subagentes, cada um aborda uma parte do problema, e depois coleta os resultados. Compartilham o mesmo diretorio de trabalho e o contexto do pai. Pense neles como threads em um unico processo.

Parent agent
  ├── Subagent A: "Search lib/ for all usages of parseConfig"
  ├── Subagent B: "Search server/ for all usages of parseConfig"
  └── Subagent C: "Search components/ for all usages of parseConfig"

Agentes separados rodam em sessoes independentes do Claude Code, tipicamente em paineis tmux separados. Cada um tem sua propria janela de contexto, seu proprio arquivo de identidade CLAUDE.md e sua propria visao da codebase. Nao compartilham memoria. Comunicam-se atraves de artefatos: comentarios em tarefas, atualizacoes de status, codigo commitado. Pense neles como processos separados sem estado compartilhado.

tmux pane 1: eng1 agent → "Build the REST endpoint"
tmux pane 2: eng2 agent → "Build the React component"
tmux pane 3: qa1 agent  → "Write integration tests for both"

O modelo mental importa porque determina como o trabalho flui entre as unidades. Subagentes podem passar dados ao pai de forma barata. Agentes separados passam dados pelo filesystem, git ou um task tracker externo.

Quando subagentes vencem

Use subagentes quando o trabalho compartilha estado e os resultados precisam convergir.

Pesquisa paralela. Voce precisa buscar um padrao em cinco diretorios, ler tres arquivos de documentacao e sintetizar as descobertas em uma recomendacao. Subagentes podem tomar cada caminho de busca, retornar resultados, e o pai pode combina-los sem overhead de serializacao.

Transformacoes independentes nos mesmos dados. Voce esta refatorando um modulo e precisa atualizar as definicoes de tipo, os testes e a documentacao em uma unica mudanca coerente. Cada subagente cuida de um arquivo, mas o pai garante que as mudancas sejam consistentes porque ve todos os tres resultados antes de commitar.

Exploracao rapida. Voce esta debugando e precisa verificar o git log, a saida de testes e a configuracao de runtime simultaneamente. Subagentes podem coletar os tres em paralelo e o pai sintetiza um diagnostico.

O padrao: distribuir, coletar, agir no resultado combinado. Se seu paralelismo termina com o pai precisando raciocinar sobre todos os outputs juntos, subagentes sao a ferramenta certa.

Onde subagentes falham: qualquer coisa que leve mais de poucos minutos por ramo, qualquer coisa que modifique arquivos em caminhos sobrepostos, ou qualquer coisa que precise de verificacao independente. Subagentes compartilham um diretorio de trabalho, entao dois subagentes escrevendo no mesmo arquivo corrompem o trabalho um do outro. E como compartilham contexto, um subagente de longa duracao consome a janela disponivel do pai.

Quando agentes separados vencem

Use agentes separados quando o trabalho pode ser verificado independentemente e nao precisa de um contexto compartilhado para fazer sentido.

Componentes diferentes da mesma feature. "Construir o endpoint de API" e "Construir o frontend que o chama" sao independentes ate a integracao. O engenheiro de API nao precisa do componente React em contexto. O engenheiro de frontend nao precisa do schema do banco de dados. Dar a cada um seu proprio agente com um CLAUDE.md delimitado mantem o contexto limpo e impede que a complexidade de um agente contamine o trabalho do outro.

Criterios de aceitacao diferentes. Se a tarefa A esta pronta quando o endpoint retorna 200 com o formato JSON correto, e a tarefa B esta pronta quando o componente renderiza os dados com estados de erro adequados, esses sao alvos de verificacao separados. Um agente QA pode validar cada um independentemente. Subagentes nao podem ser verificados independentemente porque produzem um output combinado.

Trabalho que toca diferentes partes da codebase. File ownership e a forma mais simples de prevenir conflitos de merge. Agente A possui server/, Agente B possui components/. Nenhum entra no territorio do outro. Se voce tentar isso com subagentes, o pai teria que gerenciar file locking, o que anula o proposito do paralelismo.

Tarefas com horizontes de tempo diferentes. Uma tarefa leva 10 minutos, a outra 2 horas. Com subagentes, o pai espera pelo filho mais lento. Com agentes separados, a tarefa curta completa, e verificada e shipada enquanto a tarefa longa ainda roda.

O padrao: lancar, esquecer, verificar separadamente. Se cada peca de trabalho se sustenta sozinha e pode ser checada sozinha, agentes separados com tarefas estruturadas sao mais limpos.

O problema do handoff

O verdadeiro ponto de decisao se resume aos handoffs.

Handoffs de subagentes sao baratos. O filho retorna dados ao pai no mesmo contexto. Sem serializacao, sem escritas em arquivo, sem espera por atualizacoes de status. O pai lanca tres subagentes, retornam tres resultados, o pai tem tudo que precisa.

Handoffs entre agentes separados sao caros mas duraveis. Agente A completa trabalho, commita codigo, atualiza status de tarefa e comenta o que fez. Agente B pega esse sinal (via coordenador ou fazendo polling do task tracker) e comeca seu trabalho dependente. O overhead e real: voce precisa de um sistema de tarefas, um protocolo de status e alguma forma para agentes descobrirem o que outros agentes fizeram.

A regra geral: se o trabalho requer mais de um handoff entre as unidades paralelas, use subagentes. Para um unico fan-out-and-gather, subagentes sao mais simples. Se o output do Agente A e o input do Agente B, que se torna o input do Agente C, o custo de coordenacao de agentes separados e justificado porque cada handoff produz um artefato verificado e commitado que nao sera perdido se um agente crashar ou atingir um limite de contexto.

Um exemplo concreto. Voce precisa:

Encontrar todos os endpoints de API que retornam dados de usuario
Adicionar rate limiting a cada um
Escrever testes para os novos rate limits
Atualizar a documentacao da API

Passos 1 e 2 sao fortemente acoplados. Os resultados da busca (passo 1) alimentam diretamente a modificacao (passo 2). Um subagente lida com a busca; o pai aplica as mudancas. Isso e um padrao de subagente.

Passos 3 e 4 sao independentes entre si mas dependem do passo 2. Os testes precisam do codigo real do endpoint. Os docs precisam da forma final da API. Essas sao tarefas separadas para agentes separados, cada uma com seus proprios criterios de aceitacao, cada uma verificavel por si so.

Decomposicao estruturada na pratica

Quando a resposta e "agentes separados," voce precisa de uma forma de decompor a feature em tarefas que possam rodar em paralelo sem se atrapalharem.

O processo de decomposicao:

1. Identificar o grafo de dependencias. Antes de dividir qualquer coisa, mapeie o que depende de que:

Feature: User profile page with activity feed

- API endpoint: GET /users/:id/profile     (no deps)
- API endpoint: GET /users/:id/activity     (no deps)
- React component: ProfileHeader            (depends on profile API)
- React component: ActivityFeed             (depends on activity API)
- Integration test: profile page end-to-end (depends on all above)

Os dois endpoints de API nao tem dependencias. Podem rodar em paralelo. Os dois componentes React dependem cada um de uma API. O teste de integracao depende de tudo.

2. Tracar os limites de propriedade. Cada tarefa recebe um escopo de arquivos. O agente do profile API possui server/routes/profile.ts e server/services/profile.ts. O agente do activity API possui server/routes/activity.ts e server/services/activity.ts. Nenhum toca nos arquivos do outro. Se uma utilidade compartilhada precisa de modificacao, um agente cria a mudanca e o outro espera.

3. Definir criterios de aceitacao por tarefa. Cada tarefa precisa de uma condicao "pronto" clara que possa ser verificada sem olhar as outras tarefas. "Profile API retorna 200 com a forma correta" e verificavel. "Pagina de perfil funciona" nao e, porque depende da integracao.

4. Especificar os artefatos de handoff. O que um agente downstream precisa de um upstream? Normalmente: codigo commitado em um branch conhecido, uma atualizacao de status e um comentario descrevendo o contrato de interface (forma da API, props do componente, assinaturas de funcoes).

Essa decomposicao transforma um vago "construir a pagina de perfil" em cinco tarefas discretas com dependencias explicitas e criterios de verificacao. Cada tarefa pode ser atribuida a um agente que tem exatamente o contexto que precisa e nada mais.

Beads para decomposicao estruturada

Aqui e onde ter um sistema de tarefas real importa. Voce nao pode rastrear cinco tarefas paralelas com post-its e output de terminal.

beads e um issue tracker local-first que modela essa decomposicao nativamente. Um epic representa a feature. Os filhos representam as subtarefas. As dependencias impedem agentes de comecar trabalho antes que os pre-requisitos estejam prontos.

Assim e a decomposicao na pratica:

# Create the epic
bd create --title "User profile page with activity feed" \
  --type epic --priority p2

# Create subtasks as children
bd create --title "GET /users/:id/profile endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "GET /users/:id/activity endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "ProfileHeader React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-api

bd create --title "ActivityFeed React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-activity-api

bd create --title "Profile page integration test" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-header,bb-activity-feed

A estrutura agora e explicita. Um agente executando bd show bb-profile-header ve que depende da tarefa do profile API. Se essa tarefa ainda nao esta pronta, o agente sabe que nao deve comecar. Quando o agente de API termina e marca sua tarefa como completa, a dependencia do agente frontend se resolve.

O workflow do agente segue um ciclo previsivel:

# Agent claims the task
bd update bb-profile-api --claim --actor eng1

# Agent comments its plan before writing code
bd comments add bb-profile-api --author eng1 "PLAN:
1. Create route handler at server/routes/profile.ts
2. Add service layer at server/services/profile.ts
3. Return shape: { id, name, avatar, bio, joinedAt }
4. Test: curl localhost:3000/users/1/profile returns 200"

# Agent implements, tests, commits
# ...

# Agent marks done with verification steps
bd comments add bb-profile-api --author eng1 "DONE: Profile endpoint implemented.
Returns { id, name, avatar, bio, joinedAt }.
Verified: curl returns 200 with correct shape.
Commit: abc1234"

bd update bb-profile-api --status ready_for_qa

Cada passo e registrado. O agente QA le o comentario DONE e sabe exatamente como verificar. O agente downstream le o comentario PLAN e conhece o contrato da API antes mesmo do codigo estar pronto.

Isso nao e overhead pelo prazer do processo. E a estrutura minima que impede cinco agentes paralelos de produzir cinco pecas de codigo incompativeis.

Escolhendo por padrao

Depois de meses rodando agentes paralelos em trabalho de producao, esta e a arvore de decisao que sigo:

Comece com subagentes quando:

A tarefa e pesquisa ou exploracao (buscar, ler, comparar)
Os resultados precisam convergir em uma unica acao
Todo o trabalho cabe em uma janela de contexto
Nao ha necessidade de verificacao independente de cada unidade paralela

Mude para tarefas separadas quando:

Diferentes partes do trabalho tocam diferentes arquivos
Cada peca tem seus proprios criterios de aceitacao
Voce quer que QA verifique pecas independentemente
O trabalho vai durar o suficiente para que uma peca termine horas antes de outra
Agentes precisam de contextos diferentes (um agente de frontend nao precisa dos internals do banco de dados)

A abordagem hibrida para features complexas: Use subagentes para a fase de pesquisa e planejamento (distribuir, coletar informacoes, sintetizar um plano), depois decomponha a implementacao em tarefas separadas para agentes independentes. O workflow de spec-driven development encaixa naturalmente aqui: um unico agente com subagentes escreve a spec, depois a spec se decompoe em tarefas para a frota multi-agente.

Visualizando a decomposicao

Uma vez que voce tem cinco ou dez tarefas estruturadas com dependencias entre elas, rastrear progresso no terminal fica dificil. bd list mostra uma lista plana. Nao mostra quais tarefas estao bloqueadas, quais estao prontas para comecar ou quanto o epic progrediu.

Este e o problema que Beadbox resolve. Ele le o mesmo banco de dados beads e renderiza arvores de epic com indicadores de progresso, relacoes de dependencia e atribuicoes de agentes. Voce ve quais subtarefas estao prontas, quais estao bloqueadas por pre-requisitos e quais estao prontas para um agente pegar. O grafo de dependencias que voce especificou com --deps se torna um mapa visual do seu trabalho paralelo.

Quando um agente termina uma tarefa e atualiza o status, Beadbox reflete a mudanca em tempo real. Sem refresh, sem rodar bd list de novo. A arvore atualiza, a barra de progresso avanca e tarefas bloqueadas se desbloqueiam conforme suas dependencias se resolvem.

Os mesmos dados. So que visiveis.

Se voce esta construindo workflows como esses, de uma estrela no Beadbox no GitHub.

Subagentes do Claude Code vs. decomposicao estruturada de tarefas: quando usar cada um