"Estou usando o Claude Code, mas conforme a escala cresce, o contexto transborda e a precisão cai."
"No final, minhas próprias mãos dando instruções de correção para a IA se tornaram o maior gargalo."
Muitas pessoas provavelmente estão travadas neste ponto. Eu também estava no início, jogando código, testes e discussões de design tudo em uma mesma sessão, vendo a precisão do Claude cair conforme o histórico aumentava.
O que percebi recentemente é que o próprio Claude Code fornece oficialmente três mecanismos para executar múltiplas sessões em paralelo.
Além disso, esses três são semelhantes, mas distintos; confundi-los pode causar acidentes. Por outro lado, se você os dividir por função, pode passar para o "lado do comando" sem escrever uma única linha de código você mesmo.
Hoje, vou organizar esses três mecanismos e a maneira correta de fixar os limites das funções enquanto verifico as informações primárias da documentação oficial.
Especificamente, vou detalhar uma configuração onde 8 sessões são distribuídas em três camadas: Comando, Implementação e Qualidade.
Como bônus, também usarei informações primárias para explicar por que explicações comuns como "escrever IDs de função no CLAUDE.md para alternar" ou "compartilhar memória com SQLite" estão ligeiramente fora do mecanismo oficial.
Meu nome é tatsuki (@nobel_824).
Eu apoio a utilização de IA para pequenas e médias empresas, ajudando na implementação de negócios com Claude / Codex enquanto uso o Claude Code o dia todo. Operação paralela é uma área que eu trabalho todos os dias, tanto para projetos profissionais quanto pessoais.
Artigo Relacionado: Introdução ao Vibe Coding: 6 Passos para Não Programadores Criarem Apps com Claude. A Era da Produção Interna em um Final de Semana
https://note.com/nobel/n/n8192ec07d689
1. Por que "Colocar Tudo em Uma Única Sessão" Falha
A primeira armadilha é sobrecarregar uma única sessão com muita informação. Não importa o quão inteligente o modelo Claude seja, ele atinge limites estruturais.
Especificamente, você encontra estes três problemas:
- Contaminação de Contexto: Quando código de implementação, testes, histórico de debug e discussões de design se misturam no mesmo contexto, a base de raciocínio fica turva e a precisão cai.
- Conflito de Instruções: Se "implementar com prioridade de velocidade" e "ser rigoroso com segurança" existem no mesmo lugar, os julgamentos ficam pela metade.
- Inchaço de Tokens: Carregar um histórico massivo toda vez é um desperdício tanto de tempo quanto de custo.
A solução é a ideia de "se tornar um único comandante e alinhar Claudes especializados." É semelhante a um CTO ter um Tech Lead e um Backend Lead, mas o importante não é a vibe — é utilizar corretamente os mecanismos oficiais do Claude Code.
Uma ação que você pode tomar hoje: Pense na sua sessão atual e verifique se "implementação", "pesquisa" e "revisão" estão coexistindo em um único contexto. Se estiverem, esse é o seu ponto de partida para dividi-las.
2. Corrigindo os "Três Mecanismos Paralelos" Fornecidos Oficialmente
Este é o núcleo do artigo. O Claude Code tem três mecanismos para paralelismo, cada um com um escopo diferente.
O primeiro é subagent (uma IA auxiliar que é executada em um contexto separado da conversa principal). Ele executa tarefas secundárias como pesquisa ou revisões usando sua própria janela de contexto, prompt de sistema dedicado e permissões de ferramentas limitadas, retornando apenas um resumo dos resultados para a sessão principal. O ponto chave é que os subagents são executados dentro da mesma sessão, reportam apenas para o principal, e subagents não conversam entre si (Documentação Oficial).
O segundo é agent teams (um mecanismo onde múltiplas sessões do Claude Code colaboram como um time). Uma sessão se torna o líder do time e gera membros, colaborando através de uma lista de tarefas e um quadro de avisos compartilhados. Ao contrário dos subagents, os membros podem enviar mensagens diretamente uns aos outros. Este é um recurso experimental e está desabilitado por padrão. Você precisa definir CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 e usar Claude Code v2.1.32 ou superior (Documentação Oficial).
O terceiro é git worktree (um recurso do Git que permite múltiplos diretórios de trabalho a partir do mesmo repositório). Ao iniciar com claude --worktree feature-auth, o Claude é iniciado em um ambiente isolado em um branch/diretório diferente. Se você executar outro em um terminal diferente, eles podem ser executados em paralelo sem interferir nos arquivos um do outro (Documentação Oficial). Ao usar o aplicativo desktop, uma worktree é criada automaticamente para cada nova sessão.
Aqui está uma tabela comparando os três:
Você não ficará confuso se lembrar que a worktree lida com o isolamento de arquivos, enquanto subagents e agent teams lidam com a coordenação do trabalho em si.
Uma ação que você pode tomar hoje: Primeiro, tente digitar claude --worktree bugfix-test para ter uma ideia de como iniciar uma sessão isolada. Quando você terminar após fazer alterações, ele perguntará se deseja manter ou excluir a worktree.
3. Prática: Implantando 8 Sessões em uma "Estrutura de 3 Camadas"
Como esses três mecanismos se traduzem em 8 sessões? Eu uso um layout dividido em camadas de Comando, Execução e Qualidade.
Camada de Comando/Design (2 Sessões)
- Sessão 1 PM (Gerente de Projeto): Gerenciamento geral do progresso, divisão de tarefas, relatórios para humanos.
- Sessão 2 Arquiteto: Decide a consistência técnica e a estrutura de diretórios. Requer aprovação do plano para produzir designs sem escrever código.
Camada de Execução/Implementação (4 Sessões)
- Sessão 3 Frontend: Criação de componentes, ajustes de UI.
- Sessão 4 Backend: Implementação de endpoints, otimização de queries.
- Sessão 5 Infra/DevOps: Docker, manutenção de CI/CD.
- Sessão 6 Segurança: Verificações de vulnerabilidades, endurecimento da autenticação.
Camada de Qualidade/Manutenção (2 Sessões)
- Sessão 7 QA/Revisor: Revisões de PR, apontamento de casos de borda.
- Sessão 8 Redator Técnico: Manutenção de README, documentação de API.
Há três dicas para este layout: Isole as quatro sessões da camada de implementação com worktrees para que não interfiram nos arquivos umas das outras. Fixe as funções para a camada de qualidade como definições de subagent ou membros de agent team. E faça cada sessão transmitir informações através de arquivos Markdown compartilhados (notas de design ou resultados de revisão). O Arquiteto atualiza o design, a camada de implementação age com base nisso, e o Revisor escreve os resultados. Os humanos só precisam dar instruções para cada sessão acionadas por essas atualizações de arquivo.
Uma observação: A diretriz oficial para um agent team é de 3–5 pessoas, então não coloque todas as 8 em um único time de uma vez (Documentação Oficial). É mais seguro combinar sessões isoladas por worktree com um agent team de 3–5 pessoas e subagents conforme necessário para atingir um total de 8 trabalhadores.
Uma ação que você pode tomar hoje: Escolha duas funções das 8 acima que pareçam fáceis de dividir no seu projeto atual. Em muitos casos, Arquiteto e Revisor são os primeiros pontos de divisão.
4. Fixe os Limites das Funções com "Definições de Subagent", Não com "CLAUDE.md"
Deixe-me corrigir um equívoco comum sobre operação paralela. Você pode ver explicações como "Escreva funções (ID: arch, ID: dev-main...) no CLAUDE.md e alterne as personas na inicialização," mas esse mecanismo não existe realmente.
CLAUDE.md é um arquivo de instruções compartilhado que o Claude Code lê na inicialização. No entanto, a documentação oficial afirma claramente que CLAUDE.md é "contexto, não uma configuração forçada." Como é passado como uma mensagem do usuário após o prompt de sistema, a conformidade estrita não é garantida. Se você quiser absolutamente impedir algo, deve usar hooks (Documentação Oficial). Pense nisso como uma forte recomendação, não uma "constituição" absoluta.
Então, onde você fixa as funções? A resposta é definições de subagent. Ao colocar um arquivo em .claude/agents/ com um nome, descrição, ferramentas disponíveis e modelo no frontmatter, você completa um especialista reutilizável. Aqui está um exemplo mínimo:
name: security-reviewer
description: Audita criticamente o código da perspectiva de autenticação, validação de entrada e gerenciamento de sessão.
tools: Read, Grep, Bash
model: sonnet
Você é um revisor de segurança sênior. Foque no tratamento de tokens,
gerenciamento de sessão e validação de entrada, e reporte descobertas com níveis de gravidade.
Além disso, essas definições podem ser chamadas pelo nome como membros em agent teams. Se você pedir para "configurar um membro com o tipo de agente security-reviewer para auditar o módulo de autenticação," ele se torna um membro herdando as ferramentas e o modelo dessa definição (Documentação Oficial). O design permite que você escreva uma função uma vez como uma definição de subagent e a reutilize tanto como subagent quanto como membro do time.
Exemplo de prompt para testar (deixando o Claude criar uma definição de função):
Crie uma definição de subagent para ser colocada em .claude/agents/.
A função é "um revisor que aponta problemas de desempenho e consultas N+1 em código de implementação."
Inclua name / description / tools / model no frontmatter,
e escreva o corpo na persona de um engenheiro sênior.
5. Construindo um Time "Arquiteto-Revisor" com Agent Teams para Aumentar a Precisão
Uma configuração altamente eficaz na operação paralela é configurar um "criador" e um "questionador" separadamente. Isso não é apenas teoria; a documentação oficial fornece exemplos do mundo real.
No exemplo oficial "Parallel Code Review," para um PR, três membros são configurados para segurança, desempenho e cobertura de teste, cada um olhando de uma perspectiva diferente enquanto o líder integra os resultados. Além disso, no exemplo "Competing Hypotheses," cinco membros recebem diferentes hipóteses para um bug para argumentar e refutar as teorias uns dos outros, tratando a teoria sobrevivente como a causa raiz (Documentação Oficial). Como um único investigador tende a ser puxado para a primeira teoria, essa abordagem cria conflito intencionalmente para melhorar a precisão.
Você também pode implementar uma operação onde o Arquiteto "não recebe permissão para escrever código" usando recursos oficiais. Ao exigir aprovação do plano para um membro, o membro permanece em um modo de plano somente leitura, produzindo apenas designs até que o líder aprove. Os critérios de aprovação podem ser escritos no prompt do líder, como "apenas aprove planos que incluam cobertura de teste."
Exemplo de prompt para testar (configurando uma estrutura de conflito de uma só vez):
Crie um agent team para revisar o PR #142. Configure três membros:
um para segurança, um para desempenho e um para cobertura de teste.
Faça com que eles revisem independentemente e emitam descobertas com gravidade, depois integre-as no final.
Existem dois modos de exibição: in-process (todos os membros são executados no mesmo terminal, ciclo com Shift+Down) e split panes (cada membro em um painel separado; requer tmux ou iTerm2). É mais fácil começar com in-process, pois não requer configuração adicional.
6. Compartilhe Memória via Auto Memory Oficial (Markdown), Não "SQLite"
Ao executar múltiplas sessões, o próximo obstáculo é "compartilhar memória entre sessões." Embora técnicas avançadas como "armazenar memória marcada em SQLite e injetá-la dinamicamente" sejam às vezes introduzidas, isso não é um recurso padrão do Claude Code. É possível se você construir um DB via MCP (Model Context Protocol), mas você deve distinguir isso do mecanismo de memória fornecido oficialmente.
O auto memory oficial funciona com arquivos markdown. Dentro de ~/.claude/projects/<project>/memory/, arquivos como MEMORY.md (índice) e arquivos específicos de tópicos como debugging.md são colocados, e o Claude escreve neles conforme trabalha. As regras de carregamento são claras: cada sessão lê até as primeiras 200 linhas ou 25KB de MEMORY.md, e o Claude só vai ler arquivos específicos de tópicos quando necessário. Isso está disponível a partir do Claude Code v2.1.59, salvo por repositório (então compartilhado entre worktrees), e armazenado localmente (Documentação Oficial).
A beleza deste design é que, ao "sempre carregar o índice e buscar detalhes apenas quando necessário," você pode manter a janela de contexto limpa. Mesmo com milhares de pequenas regras, o contexto não será contaminado toda vez, desde que o índice não inche.
Em termos de ordem, use o auto memory oficial baseado em markdown ao máximo antes de tentar construir uma solução SQLite personalizada.
Uma ação que você pode tomar hoje: Digitar /memory durante uma sessão mostra a lista de arquivos CLAUDE.md e auto memory atualmente carregados. Primeiro, dê uma olhada em onde e quantas memórias você tem.
7. Três Armadilhas na Operação Paralela (Custo, DB, Permissões)
Agora que você entende o mecanismo, aqui estão três pontos de atenção para a operação.
Primeiro é o custo de tokens. A documentação oficial afirma que, como cada membro em um agent team tem um contexto independente, o uso de tokens aumenta proporcionalmente ao número de pessoas. Usar 5 pessoas para tarefas rotineiras resultará em perda de custo. É por isso que a recomendação oficial é de 3–5 pessoas, observando que "três membros focados muitas vezes vencem cinco membros distraídos" (Documentação Oficial).
Segundo é o escopo de isolamento das worktrees. Uma worktree é apenas um mecanismo do Git para separação de arquivos; bancos de dados, variáveis de ambiente e serviços em execução ainda são compartilhados. Se duas sessões executarem migrações no mesmo DB local, quebrará. A documentação oficial adverte para "lembrar de inicializar o ambiente de desenvolvimento (instalar dependências, configurar ambientes virtuais) em cada worktree," e se as tarefas tocarem no DB, você precisa separar schemas, contêineres Docker ou arquivos .env (Documentação Oficial).
Terceiro são as permissões. Os membros herdam as configurações de permissão do líder quando são gerados. Se você executar o líder com --dangerously-skip-permissions, todos os membros também estarão nesse mesmo estado não confirmado. Como o impacto de um acidente se espalha em paralelo, é mais seguro restringir as permissões no lado do líder.
8. FAQ para Usuários Intermediários: Número de Pessoas, Expansão e Portões de Qualidade
Finalmente, algumas respostas complementares para perguntas comuns.
P. Quantas sessões são realistas?
Uma boa diretriz é a estrutura de 3 camadas e 8 sessões mencionada anteriormente. O segredo não é colocar 8 pessoas em um único agent team, mas usar um time de 3–5 pessoas como núcleo e adicionar sessões de worktree ou subagents. Isso está alinhado com as recomendações oficiais (3–5 pessoas por time, 5–6 tarefas por membro). O limite final é a faixa que você pode monitorar e dirigir. Se você aumentar o número além do que pode comandar, a eficiência diminuirá.
P. E se eu superar subagents e agent teams?
Se você quiser monitorar um grande número de sessões independentes de um só lugar, a página oficial de subagents menciona um mecanismo chamado background agents. Pense em camadas: subagents para ajuda dentro de uma sessão, agent teams para um time de conversação paralelo e background agents para gerenciar muitas sessões independentes.
P. Como posso garantir a qualidade?
Recomendações em CLAUDE.md são apenas "instruções fáceis de seguir." Para verificações que você quer absolutamente executar, force-as com hooks. Agent teams têm hooks como TeammateIdle, TaskCreated e TaskCompleted; retornar o código de saída 2 envia feedback e força o trabalho a continuar (Documentação Oficial). Isso significa que você pode impor regras programaticamente como "não concluir até que os testes estejam verdes."
Resumo: De Monitor para Designer/Delegador
O valor do Claude Code reside mais na capacidade de uma pessoa controlar múltiplos Claudes especializados do que apenas em escrever código mais rápido. Aqui estão os pontos-chave:
Não confunda os três mecanismos: subagents retornam resultados, agent teams são times de conversação e worktrees isolam arquivos. Divida 8 sessões em camadas de Comando, Implementação e Qualidade; isole a implementação com worktrees e fixe as funções de qualidade com definições de subagent ou agent teams. Fixe os limites das funções nas definições de subagent em vez de CLAUDE.md, e imponha regras absolutas com hooks. Organize o auto memory oficial baseado em markdown antes de construir uma solução SQLite personalizada. Mire em 3–5 pessoas por time e construa até 8 trabalhadores adicionando camadas.
3 passos para tentar começar hoje:
- [ ] Digite
claude --worktree test-1para ter uma ideia de como iniciar uma sessão isolada. - [ ] Escreva uma definição de subagent para uma função de "revisor" em
.claude/agents/e peça para ele revisar sua implementação. - [ ] Defina
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1e tente executar uma revisão de PR em paralelo com três membros.
O tempo que você passava constantemente digitando instruções de correção em uma única sessão se transformará em tempo gasto projetando e delegando funções. Decidir o que delegar e o que supervisionar é o trabalho mais humano que resta na operação paralela.
Links de Referência (Fontes Primárias Oficiais)
- Create custom subagents
- Orchestrate teams of Claude Code sessions
- Run parallel sessions with worktrees
- How Claude remembers your project / CLAUDE.md and auto memory
Planejo compartilhar informações úteis que não posso postar no X neste Open Chat. Se tiver interesse, junte-se agora.
