"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 à IA se tornaram o maior gargalo."
Muitas pessoas provavelmente estão travadas nesse 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 diminuir à medida que o histórico aumentava.
O que percebi recentemente é que o próprio Claude Code oferece 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ê dividi-los por função, pode passar para o "lado do comando" sem escrever uma única linha de código.
Hoje, vou organizar esses três mecanismos e a maneira correta de fixar limites de função, verificando 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ções 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 o uso de IA para pequenas e médias empresas, ajudando na implementação comercial do 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 Fim 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. Por mais inteligente que o modelo Claude seja, ele encontra limites estruturais.
Especificamente, você enfrenta estes três problemas:
- Contaminação de Contexto: Quando código de implementação, testes, histórico de depuração 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 de tempo e custo.
A solução é a ideia de "se tornar um único comandante e alinhar Clientes 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 é seu ponto de partida para dividi-los.
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 opera 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 ao principal, e os 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 uma equipe). Uma sessão se torna o líder da equipe e cria colegas de equipe, colaborando por meio de uma lista de tarefas compartilhada e uma caixa de correio. Ao contrário dos subagents, os colegas 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 uma 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, um worktree é criado automaticamente para cada nova sessão.
Aqui está uma tabela comparando os três:
Você não ficará confuso se lembrar que o 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 o 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 de progresso geral, divisão de tarefas, relatórios para humanos.
- Sessão 2 Arquiteto: Decide consistência técnica e estrutura de diretórios. Requer aprovação de 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 consultas.
- Sessão 5 Infra/DevOps: Docker, manutenção de CI/CD.
- Sessão 6 Segurança: Verificações de vulnerabilidades, endurecimento de autenticação.
Camada de Qualidade/Manutenção (2 Sessões)
- Sessão 7 QA/Revisor: Revisões de PR, apontamento de casos extremos.
- 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 funções para a camada de qualidade como definições de subagent ou colegas de agent team. E faça cada sessão retransmitir informações por meio de arquivos Markdown compartilhados (notas de design ou resultados de revisão). O Arquiteto atualiza o design, a camada de implementação se move 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 a 5 pessoas, então não coloque todos os 8 em uma única equipe de uma vez (Documentação Oficial). É mais seguro combinar sessões isoladas por worktree com um agent team de 3 a 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 entre as 8 acima que pareçam fáceis de dividir em seu projeto atual. Em muitos casos, Arquiteto e Revisor são os primeiros pontos de divisão.
4. Fixe Limites de Função 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 personas na inicialização", mas esse mecanismo não existe realmente.
CLAUDE.md é um arquivo de instrução 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 de usuário após o prompt de sistema, a conformidade estrita não é garantida. Se você quer 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 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. Concentre-se em manipulação 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 colegas em agent teams. Se você pedir para "configurar um colega 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 da equipe.
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 nome / descrição / ferramentas / modelo no frontmatter,
e escreva o corpo na persona de um engenheiro sênior.
5. Construindo uma Equipe "Arquiteto-Revisor" com Agent Teams para Aumentar a Precisão
Uma configuração altamente eficaz em 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 de "Revisão de Código Paralela", para um PR, três colegas 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 "Hipóteses Concorrentes", cinco colegas recebem diferentes hipóteses para um bug, a fim de argumentar e refutar as teorias uns dos outros, tratando a teoria sobrevivente como a causa raiz (Documentação Oficial). Como um investigador único tende a ser puxado para a primeira teoria, essa abordagem cria intencionalmente conflito para melhorar a precisão.
Você também pode implementar uma operação onde o Arquiteto "não tem permissão para escrever código" usando recursos oficiais. Ao exigir aprovação de plano para um colega, o colega 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 nº 142. Configure três colegas:
um para segurança, um para desempenho e um para cobertura de teste.
Peça para eles revisarem de forma independente e emitirem descobertas com gravidade, depois integre no final.
Existem dois modos de exibição: in-process (todos os colegas são executados no mesmo terminal, ciclam com Shift+Down) e split panes (cada colega 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 Memória Automática 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 BD via MCP (Model Context Protocol), mas você deve distinguir isso do mecanismo de memória fornecido oficialmente.
A memória automática oficial funciona com arquivos markdown. Dentro de ~/.claude/projects/<project>/memory/, arquivos como MEMORY.md (índice) e arquivos de tópicos específicos como debugging.md são colocados, e o Claude escreve neles enquanto 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 de tópicos específicos quando necessário. Isso está disponível a partir do Claude Code v2.1.59, salvo por repositório (portanto, 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 ao máximo a memória automática oficial baseada em markdown 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 de memória automática atualmente carregados. Primeiro, dê uma olhada em onde e quantas memórias você tem.
7. Três Armadilhas na Operação Paralela (Custo, BD, Permissões)
Agora que você entende o mecanismo, aqui estão três pontos de cautela para a operação.
Primeiro é o custo de tokens. A documentação oficial afirma que, como cada colega 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 a 5 pessoas, observando que "três membros focados muitas vezes superam cinco membros distraídos" (Documentação Oficial).
Segundo é o escopo de isolamento dos worktrees. Um 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 BD local, isso quebrará. A documentação oficial alerta para "lembrar de inicializar o ambiente de desenvolvimento (instalar dependências, configurar ambientes virtuais) em cada worktree", e se as tarefas tocarem no BD, você precisa separar esquemas, contêineres Docker ou arquivos .env (Documentação Oficial).
Terceiro são as permissões. Os colegas 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 colegas 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 a 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 uma equipe de 3 a 5 pessoas como núcleo e adicionar sessões de worktree ou subagents. Isso está alinhado com as recomendações oficiais (3 a 5 pessoas por equipe, 5 a 6 tarefas por colega). O limite máximo é o alcance que você pode monitorar e direcionar. 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 uma equipe paralela conversacional 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 aplicar regras programaticamente, como "não concluir até que os testes estejam verdes."
Resumo: De Monitor a Designer/Delegador
O valor do Claude Code reside mais na capacidade de uma pessoa controlar múltiplos Clientes 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 equipes conversacionais e worktrees isolam arquivos. Divida 8 sessões em camadas de Comando, Implementação e Qualidade; isole a implementação com worktrees e fixe funções de qualidade com definições de subagent ou agent teams. Fixe limites de função em definições de subagent em vez de CLAUDE.md e imponha regras absolutas com hooks. Organize a memória automática oficial baseada em markdown antes de construir uma solução SQLite personalizada. Procure ter de 3 a 5 pessoas por equipe e construa até 8 trabalhadores adicionando camadas.
3 passos para tentar começando 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 colegas.
O tempo que você passou digitando constantemente 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)
- Criar subagents personalizados
- Orquestrar equipes de sessões do Claude Code
- Executar sessões paralelas com worktrees
- Como o Claude lembra do seu projeto / CLAUDE.md e memória automática
Planejo compartilhar informações úteis que não posso postar no X neste Open Chat. Se tiver interesse, junte-se agora.
