Claude Code sem magia: Habr analisa a arquitetura, o ruído de contexto e as práticas de engenharia

No Habr foi publicada uma tradução de um grande texto prático sobre Claude Code, baseado em meio ano de trabalho intensivo com o agente. Não se trata de um recapitulativo de recursos, mas de uma análise do por que uma ferramenta de IA para desenvolvimento começa a falhar quando lhe é dado muito contexto, regras e liberdade simultaneamente.

Onde o Contexto se Perde

A ideia principal do artigo é simples: Claude Code não quebra porque o modelo "não é inteligente o suficiente", 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 de resultado. Se até mesmo uma camada neste ciclo estiver sobrecarregada, a qualidade cai drasticamente: um CLAUDE.md longo cria ruído, dezenas de ferramentas complicam a tomada de decisão, e a falta de verificação rápida transforma cada edição em uma loteria. Neste modo, o desenvolvedor começa a ajustar infinitamente prompts, embora o problema esteja mais profundo.

O custo do contexto é discutido separadamente. Formalmente, Claude Code tem uma janela grande, mas uma porção significativa de tokens é gasta antes que o trabalho comece: em instruções do sistema, descritores de skills, descrições de ferramentas MCP, estado LSP, memória e CLAUDE.md do projeto. O autor fornece um cálculo revelador: um único servidor MCP típico pode ocupar milhares de tokens apenas para esquemas de ferramentas, e alguns servidores conectados facilmente consomem uma parcela notável da janela disponível. Adicione a isto resultados longos de testes, grep e logs—e o histórico de diálogo útil começa a ser deslocado por conta própria.

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

Disso decorre uma conclusão prática: conhecimento raramente usado não deve viver em um contexto constantemente carregado. Ao trocar de tarefa, é melhor usar mais frequentemente limpeza de sessão; para continuar em uma direção—compressão gerenciada. Outra dica do artigo: peça ao agente antes de uma nova sessão para reunir HANDOFF.md com progresso, becos sem saída e status de verificação. Isto é mais barato e confiável do que esperar que a compactação automática preservará verdadeiras decisões arquitetônicas importantes.

Skills, Hooks e Agentes

A segunda seção importante é dedicada à separação de funções. O autor sugere não misturar MCP, ferramentas, skills, hooks, plugins e subagents em uma pilha. A lógica é: uma ferramenta fornece nova capacidade, um skill estabelece o fluxo de trabalho, um hook incorpora verificação automática obrigatória, e um subagent descarrega uma tarefa separada em contexto isolado. Esta é uma clarificação útil porque muitas equipes tentam consertar qualquer falha com um novo prompt ou mais uma ferramenta, quando o problema poderia ser resolvido em um nível completamente diferente.

O artigo explica separadamente como um bom skill deve ser. Tem um descritor curto e preciso, um gatilho de uso compreensível, entradas documentadas, saídas e uma condição de parada. Tudo pesado—exemplos, runbooks, arquivos auxiliares—deve ser puxado sob demanda, não pendurado no SKILL.md principal. Para ações com efeitos colaterais, o autor aconselha desabilitar explicitamente a execução automática pelo modelo. A ideia é para o agente primeiro ver o índice e rota, depois carregar detalhes apenas quando realmente forem necessários.

Subagents neste detalhamento são apresentados não como uma forma de "acelerar tudo em paralelo", mas como um meio de isolamento. Pesquisa de base de código, revisão, execução de testes e outras operações barulhentas são melhor enviadas para threads filhas com permissões limitadas, um modelo separado e formato de resposta fixo. Hooks, inversamente, devem capturar coisas determinísticas o mais cedo possível: executar uma verificação rápida após edição de arquivo, bloquear mudanças perigosas, misturar contexto técnico no início da sessão. Quanto mais cedo o sistema pega um erro, menos tokens, tempo e edições desnecessárias vão para desperdício.

Cache, Verificação e Contrato

Uma das partes mais interessantes do texto é a explicação de quanto a arquitetura do Claude Code depende do prompt caching. O autor escreve que um prefixo de prompt estável economiza não apenas dinheiro, mas também reduz atrito com limites. Disso vêm várias regras não óbvias: não inserir dados dinâmicos no prompt do sistema, não embaralhar a ordem de instruções, não trocar modelos no meio de uma sessão longa sem necessidade, e quando possível, adiar o carregamento completo de esquemas de ferramentas raras. Até mesmo Plan Mode, como observado no artigo, é mais conveniente implementar sem trocar o conjunto inteiro de ferramentas, para evitar quebrar o cache.

O foco final é colocado na verificação e no papel de CLAUDE.md. O autor chama este arquivo não de base de conhecimento, mas de contrato entre o projeto e o agente: como coletar, como testar, quais limites não podem ser violados, o que deve ser preservado ao comprimir, quais proibições sempre se aplicam. CLAUDE.md não precisa trazer referências de API e introduções longas; apenas regras que são críticas em cada sessão devem viver lá. Uma dica separada: após cada erro repetido, peça ao agente para atualizar seu contrato para que erros típicos não voltem novamente.

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

Claude fez certo, a tarefa provavelmente não é adequada para execução totalmente automática."

O que Isto Significa

Este material é importante não apenas para usuários de Claude Code. Essencialmente, é uma instrução para a maturação de qualquer agente de IA para desenvolvimento: menos magia, mais isolamento, verificação explícita e controle sobre contexto. Quanto mais ativamente as equipes se movem de "chatbot de código" para engenheiro semi-autônomo, mais valiosas exatamente estas práticas se tornam, em vez de outra coleção de prompts.