Graft: O Padrão que Economiza 42% de Tokens em Agentes de Código

Na minha experiência com agentes de código (Claude Code, Codex, etc), há um padrão tão óbvio que deveria estar resolvido faz tempo: agentes estão desperdiçando tokens antes de fazer qualquer alteração. E esse desperdício é tão severo que muda completamente a equação econômica de usar agentes.

O problema é simples. Um agente que entra no seu repositório não sabe aonde ir. Então faz o que todo humano faria: explora. Executa grep, ls, find, tenta entender a estrutura. A diferença é que, ao contrário de um humano que descobre 3 arquivos e para, um agente resend o resultado inteiro da busca junto com toda a conversa anterior em cada novo contexto. Um repositório médio gera GB de dados transmitidos só em buscas exploratórias antes do agente chegar ao primeiro arquivo que realmente precisa editar.

E aí descobri Graft. Não é uma ferramenta que você "instala e pronto". É um padrão, um jeito diferente de pensar sobre como agentes acessam seu projeto.

O Que é Context Engineering (e Por Que Importa)

Context engineering é a ideia de que em vez de deixar o agente descobrir a estrutura do seu projeto do zero, você pré-calcula qual informação o agente realmente precisa e entrega só aquilo.

Parece óbvio quando você ouve. Mas quando você implementa, é revolucionário. Porque a maioria das tools que existem (autocomplete, agentic loops, RAG) deixa o agente buscar e tentar descobrir. Graft flipa: você entrega a informação relevante no formato que o agente consegue processar eficientemente.

O resultado? Seu agente chega com um mapa, não cego.

Por Que Agentes Queimam Tokens (E É Pior Do Que Você Pensa)

Um agente entrando no seu código faz:

1. find . -name "*.ts" → lista todos os TypeScript

2. grep -r "tipo X" → busca por padrão

3. Lê 5-10 arquivos de exemplo → entende patterns

4. Faz uma edit

5. Precisa verificar o impacto? Resend tudo de novo

Cada um desses passos resend toda a conversa anterior. Um repositório com 200 arquivos de tipo misto gera 20-50MB de tokens transmitidos só em buscas. Em um modelo como Opus ou GPT-6 Astra, onde uma tarefa já consome 100k tokens, essa exploração prévia é literalmente 50% do custo.

Pior ainda: context window cresce, modelo fica mais lento para raciocinar, qualidade cai. Você atinge limite de uso mais rápido. É o inimigo invisível dos agentes.

Como Graft Resolve (Com Números Reais)

Graft constrói um knowledge graph do seu projeto. Cada parte de código é um "node", cada conexão real entre partes é um "edge".

Diferente de vector search (que erra por similaridade semântica — "criar conta" e "deletar conta" dão match parecido mas fazem coisas opostas), Graft mapeia a arquitetura real: qual arquivo importa qual, onde é chamado, qual módulo depende de qual.

Funciona assim:

1. Você roda graft init no seu repositório

2. Graft escaneia a estrutura e gera um arquivo JSON (mapa local, sem APIs)

3. Graft gera automaticamente um Claude Skill dentro do seu projeto

4. Hooks entregam instruções no session start, anexam até 3 localizações prováveis a cada prompt

5. Quando você edita um arquivo, Graft atualiza o mapa automaticamente

Tudo local, sem API key separada, sem dependência externa.

O Impacto: Benchmark Com 162 Rodadas

A Graft rodar benchmark próprio com 162 runs reais. Os números falam:

42% menos tokens por tarefa

60% menos tempo de execução

46% menos tool calls (agentes param de explorar cegamente)

32% menos custo

Melhor caso: até 4x mais barato

Não é 10%. Não é "alguma melhoria". É radicalmente diferente.

Se você está pagando por tokens (OpenAI, Anthropic, AWS), isso muda a equação econômica completamente. Um agente que custava $50 por tarefa passa a custar $34. Ainda mais: um agente que demorava 2 minutos passa a demorar 48 segundos.

Pior em modelos high-end onde uma tarefa já consome muitos tokens — o conhecimento prévio economiza exponencialmente.

MCP vs Hooks: Dois Modos, Mesma Filosofia

Graft funciona de dois jeitos:

CLI/Hooks mode: Anexa contextualmente a cada prompt, atualiza após editar. Mais rápido, integração automática.

MCP mode: Agente pergunta ao Graft só quando precisa, nada anexado automaticamente. Leve vantagem em acurácia, controle mais fino.

Ambos chegam ao mesmo lugar: agente informado, contexto reduzido, economia real.

Por Que Isso Importa Para Você

Tem 3 razões pelas quais você deveria experimentar hoje:

(1) Custo real de agentes cai 32-75%. Se você está hesitando em usar agentes porque o custo é alto, context engineering torna viável. Literalmente muda de "ferramenta cara" para "ferramenta prática". Recupera investimento em semanas.

(2) Agentes ficam mais rápidos e assertivos. Sem exploração cega, agentes chegam ao código 2-3x mais rápido e erram menos. Você recupera tempo real de desenvolvimento que importa.

(3) Funciona com qualquer agente que você já usa. Não é locked a uma tool específica. Você roda Graft uma vez, integra com Claude Code ou Codex ou qualquer framework MCP. É um padrão open.

Conclusão

Graft é daquelas ferramentas que quando você entende, parecem óbvias retroativamente. Agentes não deveriam estar explorando seu projeto cegamente — eles deveriam chegar com um mapa.

Se você está usando agentes para código, vale muito a pena testar. A integração é simples (graft init), a economia é real (42% menos tokens é fato, não opinião), e funciona hoje.

Repositório e documentação completa em: https://trailhq.com/graft