Tradução para Português - Brasil:
Toda sessão longa do Claude Code termina do mesmo jeito: você perde horas de progresso e começa do zero.
A solução não é um modelo mais inteligente, é um sistema que a equipe do Claude Code usa internamente e nunca escreveu um guia sobre isso.
A maioria dos devs não tem e nem sabe que existe.
Aqui está o sistema completo 👇
🧠Antes de mergulharmos, compartilho notas diárias sobre IA e vibe coding no meu canal do Telegram: https://t.me/zodchixquant
O que engenharia de contexto realmente significa
Claude lê milhares de linhas a cada sessão. A maior parte é ruído, e os 5% que importam ficam soterrados na segunda hora.
É aí que Claude começa a inventar funções e corrigir bugs que você nunca escreveu. A solução não é um modelo maior, é controlar o que entra na sessão.
Estes são os 6 padrões que a equipe do Claude Code usa no próprio monorepo deles.
Padrão 1: CLAUDE.md em camadas (Passos 1-3)
Um único CLAUDE.md não é suficiente. A equipe do Claude Code usa três camadas, cada uma focada em um aspecto diferente.
Passo 1: CLAUDE.md raiz com regras do projeto inteiro
Coloque um CLAUDE.md na raiz do seu repositório. Mantenha abaixo de 100 linhas. Ele deve responder a quatro perguntas que Claude faz a cada prompt:
1# Projeto: [nome]23## Stack4- Runtime: Node 22, TypeScript 5.55- Framework: Next.js 15, React 196- Banco de dados: Postgres 16, Drizzle ORM7- Testes: Vitest, Playwright89## Convenções10- Imports: caminhos absolutos de `@/` apenas11- Componentes: arquivos em kebab-case, exports em PascalCase12- Testes: colocalizados como `[arquivo].test.ts`13- Commits: conventional commits, sem rodapé de co-autor1415## Não mexer16- `infra/terraform/` (gerenciado pela operação)17- `migrations/` (gerado, nunca editado manualmente)18- `vendor/` (dependências comitadas)1920## Padrões21- Execute `npm test` antes de declarar uma tarefa concluída22- Verifique tipos com `tsc --noEmit` a cada edição23- Formate com Prettier ao salvar
Passo 2: CLAUDE.md de subdiretório com contexto específico do módulo
Adicione CLAUDE.md em qualquer pasta onde as regras mudarem. Claude lê o mais próximo quando estiver trabalhando naquela pasta, sobreposto ao da raiz.
Exemplo, src/auth/CLAUDE.md:
1# Módulo de autenticação23Este módulo gerencia sessão e fluxos OAuth.45## Regras6- Nunca registre tokens, nem mesmo truncados7- Todas as leituras de sessão passam por `getSession()`, nunca cookies brutos8- Novos provedores exigem revisão de segurança antes do merge910## Arquivos para ler primeiro11- `session.ts` para o contrato12- `providers/index.ts` para o padrão de registro
Passo 3: CLAUDE.md pessoal em ~/.claude/CLAUDE.md
Esta é sua camada de preferências globais. Fica fora de qualquer repositório, aplica-se em todo lugar.
1## Minhas preferências - Explique o que está prestes a fazer antes de fazer em edições multi-arquivo - Reaja se meu pedido parecer que vai quebrar algo - Prefira composição a herança - Eu trabalho em zsh no macOS
As três camadas se empilham: preferências globais + regras do projeto + regras do módulo. Claude lê todas as três a cada prompt sem precisar re-enviá-las pelo seu contexto.
Padrão 2: Referências cirúrgicas a arquivos (Passos 4-5)
O padrão "deixa Claude descobrir quais arquivos importam" é a forma mais lenta e burra de usar contexto.
Passo 4:@arquivo com autocomplete
Quando você digita @ em um prompt, Claude abre um seletor fuzzy de arquivos. Use-o em vez de descrever arquivos em prosa.
Ruim: "olhe o código de autenticação do usuário e o auxiliar de sessão"
Bom: "olhe
@src/auth /session.ts e
@src/auth /providers/google.ts, corrija a renovação do token"
Referências cirúrgicas carregam exatamente esses arquivos. Descrições em prosa forçam Claude a pesquisar, ler 4-5 arquivos candidatos e escolher errado metade das vezes.
Passo 5: /focus para escopar um fluxo de trabalho inteiro
Para tarefas mais longas, escope toda a sessão do Claude para pastas específicas:
1/focus src/auth src/api/auth-routes
Agora toda busca, grep e leitura opera apenas dentro dessas duas pastas.
Reduz o uso de contexto em 60-80% em tarefas focadas, e Claude para de ler "prestativo" arquivos irrelevantes que não precisa.
Execute /focus clear para resetar.
Padrão 3: Compactar-e-continuar (Passos 6-8)
Sessões longas atingem o limite de contexto e travam. O truque não é evitar sessões longas, é executá-las por meio de compactação controlada.
Passo 6: Monitore o uso de contexto com /stats
Execute /stats periodicamente.
Quando você ultrapassar 70% de uso de contexto, está na zona de perigo. Acima de 85%, Claude começa a descartar mensagens antigas sem avisar.
Passo 7: /compact com instruções de preservação
/compact sozinho resume a conversa. Com instruções, você diz a Claude o que preservar literalmente:
1/compact preserve: plano da tarefa atual, todas as decisões sobre a refatoração de autenticação, a saída do teste falhando do passo 3
Passo 8: /resume para sessões que duram dias
Se uma tarefa durar vários dias, termine cada sessão com /compact preserve: ... e comece a próxima com:
1claude --resume [id-da-sessão]
Ou apenas claude --continue para a sessão mais recente. Retoma exatamente de onde parou com o estado compactado intacto.
Padrão 4: Leitura com planejamento (Passos 9-10)
O maior vazamento de contexto é Claude editar arquivos antes de entendê-los. O modo plano força ele a ler primeiro, escrever depois.
Passo 9: Ative o modo plano em toda tarefa arriscada
Pressione Shift+Tab para entrar no modo plano antes de qualquer tarefa que toque mais de um arquivo.
No modo plano, Claude só pode ler. Ele explica o que faria, lista cada arquivo que planeja tocar e mostra as alterações propostas. Nada é executado até você aprovar.
A economia é real: uma leitura, uma edição, em vez de ler 8, editar 3 errado, reverter, reler, editar de novo.
Passo 10: Trave o modo plano para caminhos sensíveis via hooks
Torne o modo plano obrigatório para áreas arriscadas. Em .claude/settings.json:
1{2 "hooks": {3 "PreToolUse": [4 {5 "matcher": "Edit(src/auth/**)|Edit(migrations/**)",6 "hooks": [7 {8 "type": "command",9 "command": "claude-require-plan-mode"10 }11 ]12 }13 ]14 }15}
Qualquer tentativa de edição em src/auth/*\ ou migrations/\\* aciona um requisito de modo plano. Claude não pode contornar.
Padrão 5: Isolamento de contexto de subagente (Passos 11-13)
Subagentes são a forma mais limpa de manter seu contexto principal pequeno. Cada subagente roda em sua própria janela, então a sessão pai nunca vê o ruído.
Passo 11: Projete subagentes com superfície mínima de ferramentas
Restrinja as ferramentas ao que a tarefa precisa.
Um code-reviewer não precisa de Write ou Edit.
Um doc-updater não precisa de Bash. Menos superfície, menos contexto queimado em documentação e descrições de ferramentas irrelevantes.
1---2name: code-reviewer3description: Revisar mudanças de código para bugs e problemas de segurança4tools: Read, Grep, Glob5model: sonnet6---
Passo 12: Passe apenas as referências de arquivo que o agente precisa
Não diga "revise as mudanças recentes." Diga "revise @src/auth/session.ts e @src/auth/providers/google.ts."
O subagente lê apenas esses, não seu melhor palpite do que "recente" significa.
Passo 13: Use modelos mais baratos para subagentes
Defina o modelo por agente com base na tarefa.
Sonnet para tarefas de revisão e teste, Haiku para atualizações de documentação e lints, Opus apenas para auditorias de arquitetura ou segurança onde raciocínio profundo importa.
Defina globalmente se necessário:
1export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"
Subagentes mais baratos = mais chamadas de subagente por dólar = mais isolamento = contexto principal menor.
O iniciador de engenharia de contexto de 30 minutos
10 minutos: escreva um CLAUDE.md raiz enxuto com stack, convenções, lista de "não mexer" e padrões.
5 minutos: adicione CLAUDE.md de subdiretório nos seus 2-3 módulos mais editados.
5 minutos: coloque um CLAUDE.md pessoal em ~/.claude/CLAUDE.md com suas preferências.
5 minutos: construa uma skill em .claude/skills/ para o fluxo de trabalho que você faz com mais frequência.
5 minutos: fixe a memória muscular de Shift+Tab e comece toda tarefa multi-arquivo no modo plano.
Pronto!
Sua próxima sessão usará 50-70% menos contexto para a mesma quantidade de trabalho. Na quinta sessão, os padrões se tornam reflexo, e você para de bater no limite completamente.
Contexto não é algo que Claude gerencia para você. É algo que você projeta.
Agora você tem o sistema.
Obrigado pela leitura!
Compartilho notas diárias sobre IA, finanças e vibe coding no meu canal do Telegram: https://t.me/zodchixquant
