Claude Code sem mágica: Habr analisa arquitetura, ruído de contexto e práticas de engenharia

O Habr publicou a tradução de um extenso texto prático sobre o Claude Code, baseado em meio ano de trabalho intenso com o agente. Não é um resumo de funcionalidades, mas uma análise de por que uma ferramenta de IA para desenvolvimento começa a falhar quando recebe contexto, regras e liberdade demais ao mesmo tempo.

Onde o contexto se perde

A ideia central do artigo é simples: o Claude Code quebra não porque o modelo seja «pouco inteligente», mas porque o ambiente de engenharia ao redor dele é mal estruturado. O autor descreve o agente como um ciclo de coleta de contexto, ação e verificação do resultado. Se pelo menos uma camada desse ciclo estiver sobrecarregada, a qualidade cai bruscamente: um CLAUDE.md longo gera ruído, dezenas de ferramentas dificultam a escolha, e a falta de uma verificação rápida transforma cada edição em loteria. Nesse cenário, o desenvolvedor passa a ajustar prompts sem parar, embora o problema esteja mais fundo.

O texto analisa também o custo do contexto. Formalmente, o Claude Code tem uma janela grande, mas boa parte dos tokens é gasta antes mesmo de o trabalho começar: instruções de sistema, descritores de skills, descrições de ferramentas MCP, estado do LSP, memória e o CLAUDE.md do projeto. O autor apresenta um cálculo ilustrativo: um servidor MCP típico pode ocupar milhares de tokens apenas com os esquemas de ferramentas, e vários servidores conectados facilmente consomem uma fatia considerável da janela disponível. Some a isso a saída longa de testes, grep e logs, e o histórico útil da conversa passa a ser expulso naturalmente.

• Instruções de sistema e regras básicas
• Descrições de skills e ferramentas MCP
• Memória do projeto e conteúdo do CLAUDE.md
• Resultados de chamadas de shell, testes e buscas
• Histórico da sessão comprimido, mas nem sempre preciso

Disso decorre uma conclusão prática: conhecimento raramente usado não deve ficar num contexto sempre carregado. Para mudar de tarefa, vale limpar a sessão com mais frequência; para continuar na mesma linha, compressão controlada. Outra dica do artigo é pedir ao agente que, antes de uma nova sessão, monte um HANDOFF.md com progresso, becos sem saída e status da verificação. Sai mais barato e é mais confiável do que torcer para que o compaction automático preserve as decisões arquiteturais realmente importantes.

Skills, hooks e agentes

O segundo bloco importante trata da divisão de papéis. O autor propõe não misturar MCP, tools, skills, hooks, plugins e subagents. A lógica é: a ferramenta oferece uma nova capacidade, a skill define um fluxo de trabalho, o hook embute uma verificação automática obrigatória, e o subagent leva uma tarefa específica para um contexto isolado. É uma distinção útil, porque muitas equipes tentam resolver qualquer falha com um novo prompt ou mais uma tool, quando o problema pode estar em outro nível.

O artigo explica também como deve ser uma boa skill: descritor curto e preciso, gatilho de uso claro, entradas, saídas e condição de parada definidas. Tudo o que é pesado — exemplos, runbooks, arquivos auxiliares — deve ser carregado sob demanda, e não ficar no SKILL.md principal. Para ações com efeitos colaterais, o autor recomenda desativar explicitamente o disparo automático pelo modelo. A ideia é que o agente veja primeiro um índice e uma rota, e só carregue os detalhes quando realmente precisar.

Na análise, os subagents aparecem não como forma de «acelerar tudo em paralelo», mas como meio de isolamento. Exploração da base de código, revisão, execução de testes e outras operações ruidosas são melhor enviadas a threads filhas com permissões limitadas, modelo próprio e formato de resposta fixo. Já os hooks devem capturar o mais cedo possível o que é determinístico: rodar uma verificação rápida após a edição de um arquivo, bloquear mudanças perigosas, injetar contexto técnico no início da sessão. Quanto antes o sistema pega o erro, menos tokens, tempo e edições inúteis são desperdiçados.

Cache, verificação e contrato

Uma das partes mais interessantes do texto explica o quanto a arquitetura do Claude Code depende de prompt caching. O autor escreve que um prefixo de prompt estável economiza não só dinheiro, mas também reduz o atrito com os limites de uso. Daí vêm algumas regras pouco óbvias: não inserir dados dinâmicos no prompt de sistema, não embaralhar a ordem das ferramentas, não trocar de modelo no meio de uma sessão longa sem necessidade e, sempre que possível, adiar o carregamento completo de esquemas de tools raras. Até o Plan Mode, segundo o artigo, é mais conveniente de implementar sem trocar todo o conjunto de ferramentas, para não quebrar o cache.

A ênfase final recai sobre a verificação e o papel do CLAUDE.md. O autor chama esse arquivo não de base de conhecimento, mas de contrato entre o projeto e o agente: como compilar, como testar, quais limites não podem ser violados, o que preservar obrigatoriamente na compressão, quais proibições valem sempre. No CLAUDE.md não se deve colocar referências de API nem introduções longas; ali só entram regras críticas em toda sessão. Outra dica: após cada erro recorrente, pedir ao agente que atualize seu contrato, para que os deslizes típicos não voltem.

«Se você não consegue explicar como saber que o

Claude fez o trabalho corretamente, a tarefa provavelmente não é adequada para execução totalmente automática».

O que isso significa

Esse material é importante não só para quem usa o Claude Code. No fundo, é um guia de amadurecimento para qualquer agente de IA voltado ao desenvolvimento: menos mágica, mais isolamento, verificação explícita e controle sobre o contexto. Quanto mais as equipes migram do «chatbot para código» para um engenheiro semiautônomo, mais valiosas se tornam justamente essas práticas, e não mais uma coleção de prompts.