Claude Code em grandes codebases: contexto sem caos

Claude Code suporta uma janela de contexto de 1 milhão de tokens nos planos pagos, e esse número aparece em todo artigo sobre o assunto como a explicação principal de por que ele lida bem com grandes codebases. O número é real, mas a explicação é errada. O tamanho da janela de contexto é mais um teto do que uma solução, e tratá-lo como mecanismo principal produz fluxos de trabalho que degradam exatamente quando você mais precisa de precisão. O que mantém o Claude Code coerente num monorepo de 300 mil linhas é um conjunto de decisões de engenharia feitas fora do modelo: como você configura a recuperação de informação, o que você delimita para o Claude ver, e como você delega trabalho para subagentes isolados. O harness importa mais do que o número no anúncio.

Uma janela de 1M de tokens não significa que você deve enchê-la

A documentação da Anthropic sobre boas práticas de contexto aborda o problema de forma direta: à medida que a contagem de tokens cresce, a precisão e o recall degradam, um fenômeno chamado de context rot. Isso não é uma peculiaridade do Claude, é uma propriedade bem documentada dos mecanismos de atenção em large language models. A precisão cai quando o sinal relevante está enterrado num volume grande de texto irrelevante.

Na prática, o context rot aparece de formas específicas. O Claude começa a fazer suposições sobre import paths que não existem no seu projeto. Ele alucina dependências presentes em alguns arquivos que leu, mas não no módulo em que você realmente está trabalhando. Sugere refatorações que quebram interfaces definidas três arquivos atrás. Nenhum desses casos é falha do modelo no sentido abstrato, é falha de retrieval causada por contexto sobrecarregado.

A resposta recomendada pela Anthropic não é contratar um plano com janela maior. É controlar o que entra via escolhas deliberadas de tooling, e delegar trabalho exploratório para subagentes para que o contexto principal da conversa fique limpo para implementação. Essa é a mudança arquitetural que separa times com resultados consistentes dos que reclamam que o Claude "perde o fio" do projeto no meio da sessão.

Contraditoriamente, uma sessão bem configurada do Claude Code num codebase grande deve ter um contexto ativo menor do que uma sessão ingênua, e não maior.

CLAUDE.md é um arquivo de configuração de retrieval, não um README

A maioria dos times que configura o CLAUDE.md trata o arquivo como um README de projeto: notas de alto nível sobre o que o projeto faz, talvez algumas instruções de setup. Esse é o modelo mental errado. CLAUDE.md é mais próximo de um documento de política de retrieval. Ele diz ao Claude quais partes do codebase são relevantes para determinado tipo de tarefa, quais diretórios estão fora do escopo, e quais fronteiras arquiteturais existem entre módulos.

Quando o Claude Code roda num monorepo sem um CLAUDE.md configurado, ele tende a puxar arquivos com escopo amplo durante a exploração. Isso enche a janela de contexto com código estruturalmente adjacente à tarefa, mas semanticamente irrelevante para ela. Segundo a documentação oficial do Claude Code publicada pela Anthropic, o harness é construído a partir de pontos de extensão que incluem arquivos CLAUDE.md, hooks, skills, plugins e servidores MCP. O CLAUDE.md é a primeira camada e molda tudo o que vem depois.

Um CLAUDE.md útil para um monorepo especifica a propriedade dos módulos de forma explícita. Algo como: "O diretório payments/ é de responsabilidade do time de pagamentos e não tem imports diretos de catalog/. Se uma tarefa envolver payments, não percorra os módulos de catalog a menos que seja explicitamente solicitado." Uma única restrição dessas elimina uma classe inteira de dependências cross-módulo alucinadas.

Além das fronteiras, o CLAUDE.md deve incluir as convenções de dependência do projeto, qualquer path aliasing não óbvio, e quais serviços são externos versus internos. Times que populam esse arquivo com fronteiras arquiteturais relatam menos import paths alucinados porque estão gerenciando o que o Claude recupera antes mesmo de a janela de contexto entrar em jogo. A maioria dos artigos sobre Claude Code pula esse ponto inteiramente porque parece higiene de documentação, não engenharia de IA.

Para uma analogia prática: isso é similar em espírito ao que acontece com restrições negativas em prompts. Você não está dizendo ao Claude o que fazer; está estreitando o espaço que ele pesquisa.

Subagentes são unidades de isolamento de contexto, não só paralelismo

Subagentes no Claude Code são geralmente descritos como uma forma de paralelizar trabalho, e isso é correto, mas incompleto. Uma descrição mais precisa, que aparece na documentação de agentes da Anthropic: um subagente é uma instância isolada do Claude com sua própria janela de contexto que recebe uma tarefa, executa o trabalho e retorna apenas o resultado final para o agente pai. Receber apenas o valor de retorno é a parte que importa. Toda a exploração do subagente, leituras de arquivo, outputs de comandos e raciocínio intermediário ficam no contexto do subagente e nunca contaminam a sessão principal.

Num codebase grande, isso importa de uma forma específica e não óbvia. Pedir ao Claude para investigar por que um determinado endpoint de API está lento pode envolver ler uma dúzia de arquivos, rodar queries, fazer grep em logs e seguir cadeias de dependência. Tudo isso consome tokens. Se isso acontece na sua sessão principal, você gastou dezenas de milhares de tokens em investigação, e o trabalho de implementação que vem depois começa num contexto já degradado. Delegar "use um subagente para investigar a latência na API de pagamentos e retorne um resumo das causas raiz" significa que o contexto principal recebe apenas o resumo.

Uma análise da arquitetura do Claude Code publicada no arxiv.org descreve isso como um "pipeline de compactação de cinco camadas para gerenciamento de contexto" combinado com "delegação e orquestração de subagentes". A compactação lida com sumarização automática do contexto mais antigo; o mecanismo de subagente lida com o isolamento do trabalho exploratório. São mecanismos separados resolvendo partes diferentes do mesmo problema.

Trate subagentes como unidades de isolamento de contexto e delegue qualquer tarefa que envolva percurso significativo de arquivos ou raciocínio exploratório antes de chegar à implementação. A sintaxe de instrução é direta: "use subagentes para investigar X, depois retorne um resumo estruturado." O benefício é uma sessão principal com espaço suficiente para o trabalho de implementação real sem degradar.

O modo de falha que os times descobrem tarde demais: Skills carregam contexto de domínio sob demanda

Subagentes e CLAUDE.md resolvem dois problemas: isolamento de exploração e fronteiras de retrieval. Skills resolvem um terceiro problema, menos óbvio até você ter rodado Claude Code numa codebase complexa por algumas semanas.

Minha leitura, baseada no que aparece na documentação e no comportamento observável do Claude Code em sessões longas, é que skills funcionam como progressive disclosure de conhecimento especializado: workflows e contexto de domínio que de outra forma competiriam por espaço na janela são carregados apenas quando a tarefa explicitamente exige. Uma sessão focada em mudança de UI não precisa do playbook completo de migração de banco. Uma sessão focada em hotfix não precisa carregar as convenções de testes de integração.

Na prática, isso significa que suas convenções de testes, procedimentos de deploy, padrões de migração de banco de dados e regras de versionamento de API não precisam estar no CLAUDE.md base. Cada um desses domínios pode ser codificado como uma skill que carrega apenas quando a tarefa explicitamente exige.

Times que não configuram skills acabam compensando colocando tudo no CLAUDE.md, que cresce para um documento de vários milhares de palavras e ele mesmo começa a causar context rot. A essa altura, o documento compete com o código real pela atenção, e a precisão do Claude em tarefas específicas degrada como resultado. Skills são o mecanismo para evitar que o CLAUDE.md se torne o problema que ele era para resolver.

Esse ponto conecta o raciocínio arquitetural do Claude Code a padrões mais amplos sobre como a IA está mudando o desenvolvimento de software: a disciplina é menos sobre prompting e mais sobre design de sistemas, especificamente sobre quando carregar qual conhecimento em qual contexto de execução.

Na prática

Trabalho no dia a dia com Magento, integrações de marketplace e automações que tocam partes bem diferentes de um mesmo repositório. O problema de context rot aparece de forma clara quando você pede ao Claude para trabalhar em algo que atravessa módulos: ele puxa arquivos de contexto adjacente que são estruturalmente próximos mas irrelevantes para o que você está tentando fazer, e as sugestões começam a refletir um modelo mental equivocado do que está conectado ao quê.

O que resolveu de forma mais imediata no meu caso foi tratar o CLAUDE.md exatamente como o artigo original descreve: não como documentação do projeto, mas como um documento de fronteiras. Especificar quais módulos têm dependências entre si e quais explicitamente não têm elimina uma boa parte das sugestões que quebrariam integrações em produção. Parece burocrático no início, mas o arquivo paga o custo de manutenção rápido quando você para de receber import paths que não existem no seu projeto.

Para tarefas de investigação, o padrão de delegar para subagente e receber só o resumo estruturado funciona especialmente bem em diagnósticos de performance: você não quer que a investigação ocupe o mesmo contexto que vai segurar a implementação da correção.

FAQ

Aumentar a janela de contexto do Claude Code melhora os resultados em codebases grandes?

Não de forma confiável, e às vezes o efeito é inverso. A documentação da Anthropic afirma que precisão e recall degradam conforme a contagem de tokens cresce, o que eles chamam de context rot. Controlar o que entra no contexto via configuração do CLAUDE.md e delegação para subagentes é o ponto de alavanca mais preciso, em vez de expandir a janela e enchê-la com arquivos de escopo amplo.

O que um arquivo CLAUDE.md deve conter para um monorepo?

No mínimo: fronteiras de propriedade dos módulos, diretórios explicitamente fora de escopo para cada tipo de tarefa, path aliases não óbvios, distinção entre serviços externos e internos, e convenções de dependência que diferem dos padrões usuais. Deve parecer menos com um README e mais com um registro de decisões arquiteturais focado no que o Claude deve e não deve percorrer durante uma sessão.

Como subagentes do Claude Code diferem de simplesmente rodar múltiplas sessões do Claude?

Um subagente é uma instância isolada gerenciada pela sessão principal do Claude Code. Ele recebe uma tarefa, completa no próprio contexto e retorna apenas o resultado para o pai. A sessão pai nunca acumula leituras de arquivo do subagente, outputs de grep ou raciocínio intermediário. Rodar sessões separadas manualmente consegue isolamento, mas não orquestração: a sessão pai não tem como receber resultados estruturados de sessões manuais e continuar a implementação de forma integrada.

Quando o Claude Code sumariza automaticamente o contexto antigo, isso conta para o limite de uso?

Segundo a documentação de suporte da Anthropic, quando uma conversa num plano pago se aproxima do limite da janela de contexto, o Claude sumariza automaticamente mensagens anteriores para abrir espaço. Isso não conta para os limites de uso. O histórico completo do chat fica preservado para referência mesmo após a sumarização de partes dele.

Times que obtêm resultados consistentes com Claude Code em codebases grandes não são os que têm as maiores janelas de contexto. São os que configuraram o CLAUDE.md com fronteiras arquiteturais reais, usam subagentes para qualquer trabalho que envolva percurso significativo de arquivos, e codificam conhecimento de domínio como skills em vez de carregá-lo inteiro em toda sessão. O modelo é o mesmo para todo mundo. O harness é onde a diferença aparece.