Claude Code e Codex: como reduzir o desperdício de tokens com três arquivos markdown

Agentes de IA para desenvolvimento queimam contexto não porque respondem mal, mas porque passam 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 de novo, releem arquivos conhecidos e verificam servidores como se vissem o projeto pela primeira vez. A 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, embora a resposta em si tenha ocupado cerca de 800 tokens.

Ou seja, quase todo o orçamento foi para a navegação, não para o raciocínio. O problema não é uma particularidade do Claude Code, e sim uma limitação geral dos agentes de programação atuais. Cursor, Codex e Gemini CLI funcionam da mesma forma: sem um mapa do espaço de trabalho, começam cada nova sessão com uma etapa de reconhecimento.

Com um único projeto, isso é tolerável. Mas quando o desenvolvedor tem dezenas de repositórios, VPS e ambientes de staging, o agente primeiro roda grep no diretório home, encontra arquivos parecidos em projetos vizinhos, lê esses arquivos, percebe que foi parar no lugar errado e inicia uma nova rodada de busca. Em um exemplo real, uma pergunta sobre os métodos de pagamento de um bot virou uma busca em vários projetos, a releitura de seis arquivos e até uma verificação da configuração no servidor via SSH.

Esse modo de trabalho é caro e também frágil: o modelo gasta esforço se orientando e facilmente deixa passar trechos relevantes. O autor analisa três abordagens populares costumam ser oferecidas como remédio. A primeira é RAG com busca vetorial.

Ela encontra bem fragmentos semanticamente parecidos, mas entende mal a estrutura do projeto: pode devolver chunks com auth, login e token, mas não reconstruir a cadeia exata de dependências entre o middleware, a lógica de refresh e a configuração do JWT. Além disso, RAG exige infraestrutura própria, índice e reindexação, e cada consulta adiciona latência. O segundo caminho é a análise estática e o grafo de dependências via AST e tree-sitter.

Isso é útil dentro de um único repositório, mas quase inútil no nível do portfólio de projetos, em que é preciso responder não só como uma função funciona, mas também onde o serviço está, em qual servidor ele roda e qual é o seu status. A terceira opção é manter um CLAUDE.md em cada projeto.

Isso ajuda, mas só depois que o agente já descobriu para qual projeto deve ir. Em vez disso, a proposta é um contexto hierárquico que conduz o agente de cima para baixo. No nível zero fica um mapa global dos projetos: uma tabela curta com nomes, caminhos, servidores e status, incluída automaticamente em toda sessão.

No primeiro nível, um CLAUDE.md na raiz de cada projeto, com stack, arquivos-chave, comandos de deploy, nome do serviço e logs. Entre os dois, é possível adicionar uma camada intermediária com o Graphify, se a base de código for grande e for necessário um grafo preciso de relações.

Como terceira camada em markdown, o autor sugere guardar sessões anteriores e decisões de engenharia em arquivos markdown com frontmatter YAML, para que o agente consiga lembrar o que já foi discutido, quais arquivos foram alterados e quais decisões sobre debug ou pagamentos foram tomadas uma semana antes. A ideia é simples: primeiro o mapa, depois a descrição do projeto, em seguida a memória das discussões anteriores e só então o código-fonte. As medições mostram que esse esquema traz um ganho prático, não cosmético.

Para uma pergunta sobre a arquitetura do projeto, o agente às cegas precisou de 12 tool calls, contra uma com a hierarquia. Para a pergunta sobre quais projetos usam uma biblioteca específica, o modo às cegas fez 44 chamadas, escaneou o disco inteiro e ainda deixou de fora um dos três projetos relevantes; a hierarquia resolveu com duas consultas pontuais e deu a resposta completa. No caso do deploy, o efeito é ainda mais evidente: sem estrutura, o agente lia configs e acessava o servidor via SSH; com um CLAUDE.

md bem preenchido, conseguiu responder direto do contexto, sem nenhuma chamada adicional. A conclusão importante é que um contexto mais organizado melhora não só a velocidade e a economia de tokens, mas também a precisão da resposta. Por que isso funciona melhor que o pipeline de RAG tradicional?

Porque os arquivos markdown oferecem ao agente latência zero, previsibilidade e atualização simples. O próprio desenvolvedor define o que é importante saber sobre o projeto, em vez de torcer para que o ranker extraia os chunks certos do índice. Se o deploy mudou ou o serviço foi migrado, basta corrigir uma linha.

A escalabilidade também parece razoável: o mapa de projetos ocupa cerca de 2 KB, e quinze arquivos de projeto de 5 KB somam menos de 80 KB de contexto estruturado, em vez de centenas de kilobytes de código-fonte bruto. Em meio às discussões sobre janelas de contexto de milhões de tokens, isso pesa ainda mais: mais tokens nem sempre significa melhor. Informação irrelevante dispersa a atenção do modelo, e o efeito lost in the middle continua existindo.

A principal lição da análise é que o problema de tokens dos agentes de programação, na maioria das vezes, não se resolve com modelos caros nem com uma stack mais complexa, e sim com disciplina de contexto. Um mapa global de projetos, um bom CLAUDE.md e uma memória de sessões salva podem ser montados em literalmente dez minutos, e o retorno é imediato: menos busca às cegas, menos repetição, menos erros e um caminho mais curto da pergunta até o arquivo certo.