Seu agente está lendo quatro vezes mais do que precisa

A reclamação é sempre uma versão da mesma frase. "Depois de um ponto eu não estou mais programando, estou fazendo manutenção de contexto." "Cada sessão nova parece contratar o mesmo dev júnior de novo." O agente esquece, então você cola o projeto de volta, e paga por tudo a cada turno.

O ajuste de sempre é entregar mais lá na frente: um arquivo grande de instruções, uma visão geral do repositório, o conjunto inteiro de docs enfiado no prompt para o agente ter tudo o que possa precisar. Isso de fato deixa a resposta mais provável de estar no contexto. Também significa que cada pergunta paga pelo projeto inteiro, até as que tocam um canto só dele.

Existe outro jeito de fazer isso, e este post é uma medição de quanto ele economiza. O exemplo é o okf, uma pequena ferramenta de linha de comando (gem install okf, ou Docker, ou um plugin do Claude Code) que mantém o conhecimento de um projeto como uma pasta de arquivos Markdown: um arquivo por tópico, que ele chama de conceito, e a pasta como um todo de bundle. Seu agente de código lê desse bundle do jeito que você leria de um terminal. A única pergunta aqui é quanto dele o agente precisa ler para responder algo.

O despejo

Chame a abordagem de sempre de despejo. Você serializa todo o conhecimento e o coloca na frente do modelo antes de ele ter sido perguntado qualquer coisa. O custo escala com o tamanho do projeto, não com o tamanho da pergunta. Pergunte onde vive a chave de dedup da fatura e você paga o mesmo que pagaria por uma revisão completa de arquitetura, porque o contexto foi montado antes de qualquer das duas perguntas existir. Você poderia escolher os poucos arquivos relevantes na mão, e um engenheiro cuidadoso faz isso. Recuperar é essa seleção feita automática, pela busca, e mantida dentro de um orçamento por um teste.

O okf responde do outro jeito. Ele recupera. Quando o agente precisa de algo do bundle, ele roda o okf do jeito que você rodaria no terminal, pelo plugin do Claude Code ou chamando a CLI, e só o último passo lê um arquivo inteiro:

1. Orientar. okf index --no-body imprime o mapa: os diretórios, quantos conceitos cada um tem, nada mais. No próprio bundle do okf esse mapa tem 374 bytes.
2. Encontrar. okf search <termos> ranqueia os conceitos por onde os termos batem e devolve algumas linhas, não corpos.
3. Ler um. Abrir o arquivo vencedor. Esse é o único conceito inteiro que alguém lê.

Pergunte ao próprio bundle do okf "qual conceito cobre conformidade?" e esses três passos dão cerca de 1.200 tokens: o mapa de 374 bytes, um resultado ranqueado de 2.300 bytes, e o único conceito de 2.000 bytes onde estava a resposta.

Entregar esse mesmo bundle inteiro dá 194 KB de Markdown, cerca de 48.000 tokens (uns quatro bytes cada). (Serializado como grafo com okf graph --json, a forma que o teste abaixo usa, dá 208 KB, quase o mesmo: o peso está nos corpos dos conceitos, não no invólucro.) A pergunta foi respondida com 2% do projeto, um quarenta avos dele.

a pergunta	recuperado	entregue inteiro	lido
"qual conceito cobre conformidade?"	~1.200 tok	~48.000 tok	2% (41x menos)
"como funciona o ranqueamento?"	~4.400 tok	~48.000 tok	9% (11x menos)

A segunda linha é o pior caso deste bundle: a resposta é um dos maiores conceitos, e ler o mapa, a busca e esse arquivo inteiro ainda dá menos de um décimo.

Uma coisa que a tabela deixa de fora: se a busca devolve o conceito certo no passo dois. Ela conta o custo de uma resposta, não a chance de encontrá-la. Recall é uma pergunta real, e uma separada.

O que importa é onde o número vive

Uma medição favorável é fácil de rodar uma vez. O que faz esta valer um post é que ela não é uma medição. É uma asserção na suíte de testes do okf, em test/integration/cli/by_dir/cli_search_test.rb:

progressive = orient.bytesize + search.bytesize + one_body.bytesize
assert_operator progressive, :<, dump / 4   # menos de um quarto do inteiro

Ela monta um bundle, faz uma pergunta do jeito comum, serializa o mesmo bundle inteiro, e quebra o build se recuperar custar mais que um quarto do despejo. Está verde em cada commit desde a versão 1.5.0, e a gem é open source, então você pode ler a asserção em vez de acreditar em mim.

Então "o okf responde em menos de um quarto" não é uma afirmação que o projeto fez uma vez e seguiu em frente. É uma afirmação sobre a qual o projeto não pode silenciosamente deixar de ser verdadeiro, porque no dia em que deixar, o build fica vermelho. E um quarto é o piso, não o caso típico: o teste monta um bundle de propósito hostil, largo e raso, onde o mapa é proporcionalmente grande, então a garantia vale mesmo no pior extremo. Num projeto real o número é o 41x e o 11x acima. O teste promete um quarto; bundles reais chegam a um décimo ou um quarenta avos.

O que um contexto mais enxuto não compra

Existe uma linha que isso não cruza. Um contexto menor é mais barato de enviar e preenche a janela mais devagar. Não é uma solução para se o modelo faz o que o arquivo diz. Um agente pode ler uma regra, repeti-la de volta com precisão, e violá-la no turno seguinte, e nenhum orçamento de recuperação muda isso. A aderência a instruções de fato cai conforme o contexto enche, e um contexto mais enxuto te mantém no lado bom dessa curva por mais tempo, mas isso é um fator contribuinte e nada mais. Nenhum formato de documento faz um modelo obedecer, e o okf não afirma que faz.

O que a recuperação resolve é a aritmética, não o modelo.

Pare de despejar

Se o seu conhecimento é uma pilha que você entrega inteira, cada pergunta paga pela pilha. Se é um bundle sobre o qual o agente pode se orientar, buscar e ler um arquivo, cada pergunta paga pela pergunta.

Nada disso é exclusivo do okf. É para isso que um mapa, uma busca e um sistema de arquivos sempre serviram. O que o okf acrescenta são as partes que você teria que construir sozinho: um formato que faz o conhecimento do projeto tomar a forma com que essas três coisas trabalham, a CLI que orienta e busca, e o teste na suíte que mantém o quarto honesto. Aponte seu agente para um bundle e cada pergunta passa a pagar pela pergunta.

Seu agente provavelmente está lendo quatro vezes mais do que precisa. Não precisa ser assim.