Claude Code e Codex: como reduzir perdas de tokens com três arquivos markdown

Agentes de IA para desenvolvimento consomem contexto não porque respondem mal, mas porque gastam quase todo o tempo procurando o lugar certo no código. Mesmo com uma janela de um milhão de tokens, eles percorrem diretórios novamente, releem arquivos familiares e verificam servidores como se estivessem vendo o projeto pela primeira vez. Uma análise mostra que para uma pergunta simples sobre pagamentos, o agente gastou mais de 80 mil tokens e mais de 15 chamadas de ferramentas, enquanto a resposta em si levou cerca de 800 tokens.

Em outras palavras, quase todo o orçamento foi gasto não em pensar, mas em navegar. O problema não era uma peculiaridade local do Claude Code, mas uma limitação geral de agentes de codificação modernos. Cursor, Codex e Gemini CLI funcionam da mesma forma: sem um mapa do espaço de trabalho, eles começam cada nova sessão com reconhecimento.

Se há um projeto, é tolerável. Mas quando um desenvolvedor tem dezenas de repositórios, instâncias de VPS e ambientes de staging, o agente primeiro faz grep no diretório home, encontra arquivos similares em projetos vizinhos, os lê, depois percebe que foi pelo caminho errado e inicia uma nova rodada de busca. Em um exemplo real, uma pergunta sobre métodos de pagamento em um bot se transformou em busca em múltiplos projetos, releitura de seis arquivos e até verificação SSH da configuração do servidor.

Tal modo não é apenas custoso mas também frágil: o modelo gasta esforço em orientação e facilmente perde lugares relevantes. O autor examina três abordagens populares que costumam ser oferecidas como cura. A primeira é RAG e busca vetorial.

Ela faz um bom trabalho encontrando fragmentos semanticamente similares, mas entende mal a estrutura do projeto: pode retornar chunks com auth, login e token, mas falhar em restaurar a cadeia exata de dependências entre middleware, lógica de refresh e configuração JWT. Além disso, RAG requer infraestrutura separada, um índice e reindexação, e cada consulta adiciona latência. O segundo caminho é análise estática e gráficos de dependências através de AST e tree-sitter.

Isso é útil dentro de um repositório, mas quase inútil no nível de um portfólio de projetos, onde você precisa responder não apenas como uma função funciona, mas onde o serviço necessário realmente vive, em qual servidor está rodando e qual é seu status. A terceira opção é manter CLAUDE.md em cada projeto.

Isso ajuda, mas apenas após o agente já ter descoberto para qual projeto ir. Em vez disso, propõe-se um contexto hierárquico que guia o agente de cima para baixo. No nível zero fica um mapa global de projetos: uma tabela curta com nomes, caminhos, servidores e status, que automaticamente entra em cada sessão.

No primeiro nível fica CLAUDE.md na raiz de um projeto específico com o stack, arquivos-chave, comandos de deploy, nome do serviço e logs. Entre eles, pode-se adicionar uma camada intermediária na forma de Graphify se a base de código é grande e um gráfico de dependências preciso é necessário.

E como terceira camada markdown, o autor propõe armazenar sessões passadas e soluções de engenharia como arquivos markdown com frontmatter YAML, para que o agente possa lembrar o que já foi discutido, quais arquivos foram alterados e que soluções para debugging ou pagamentos foram tomadas uma semana antes. A ideia é simples: primeiro o mapa, depois a descrição do projeto, depois memória de discussões passadas, e apenas então o código-fonte. Medições mostram que tal esquema oferece ganhos não cosméticos mas práticos.

Para uma pergunta sobre arquitetura de projeto, o agente cego precisou de 12 chamadas de ferramenta versus uma com a hierarquia. Para uma pergunta sobre quais projetos usam uma biblioteca específica, o modo cego fez 44 chamadas, varreu todo o disco e ainda assim perdeu um dos três projetos necessários; a hierarquia se encaixou em dois consultas pontuais e deu uma resposta completa. No caso de deployment, o efeito é ainda mais notável: sem estrutura, o agente lia configs e ia sobre SSH, mas com um CLAUDE.

md adequadamente preenchido conseguiu responder diretamente do contexto sem nenhuma chamada adicional. A conclusão importante aqui é que um contexto mais organizado aumenta não apenas velocidade e economia de tokens, mas também precisão da resposta. Por que isso funciona melhor que o familiar pipeline RAG?

Porque arquivos markdown dão ao agente latência zero, previsibilidade e atualizações simples. O desenvolvedor mesmo determina o que exatamente é importante saber sobre o projeto, em vez de esperar que o ranker puxe os chunks necessários do índice. Se o deployment mudou ou um serviço se moveu, é suficiente corrigir uma linha.

Escalabilidade também parece razoável: o mapa de projetos ocupa cerca de 2 KB, e quinze arquivos de projeto de 5 KB cada dão menos de 80 KB de contexto estruturado em vez de centenas de kilobytes de código-fonte bruto. Contra o pano de fundo de discussões sobre janelas de um milhão de tokens, isso é especialmente importante: mais tokens nem sempre significa melhor. Informação irrelevante borra a atenção do modelo, e o efeito lost in the middle ainda continua presente.

A conclusão principal da análise é que o problema de tokens em agentes de codificação geralmente deve ser resolvido não com modelos caros e não complicando a stack, mas com disciplina de contexto. Um mapa global de projetos, um bom CLAUDE.md e memória de sessões salvas podem ser montados literalmente em dez minutos, e o retorno aparece imediatamente: menos busca cega, menos repetições, menos erros e um caminho mais curto de pergunta para arquivo necessário.