💸 Economia de tokens

A frase-chave de Matt Pocock neste tema é direta: "Como você otimiza o gasto de tokens? Tendo um codebase mais fácil de fazer mudanças." Repare: a resposta dele não é "use um prompt mágico" nem "espere um modelo melhor". É arquitetura — a forma como seu codebase é organizado. Cada vez que o agente precisa entender o código pra mudar algo, ele lê arquivos (tokens de entrada) e escreve tentativas (tokens de saída). Quanto mais confuso o terreno, mais ele precisa ler e tentar — e o token spend sobe.

Por que isso é fundamento e não detalhe? Porque o preço da IA é cobrado por token — tanto o que entra quanto o que sai. Um arquivo gigante com mil linhas força o agente a engolir tudo só pra mudar uma função. Já um codebase modular (arquivos pequenos, nomes óbvios, cada coisa no seu lugar) deixa o agente ler só o pedaço relevante. Mesma tarefa, mesmo modelo, fração dos tokens. O erro comum de iniciante é tratar o custo da IA como um número fixo da fatura — quando, na verdade, ele é uma consequência direta de quão navegável você deixou o seu código.

Pocock usa uma imagem ótima pra o custo: sem proteção, o modelo fica "batendo a cabeça na parede" — tentando, falhando, tentando de novo, queimando tokens a cada tentativa. A solução não é um modelo mais esperto: são guard rails. Um guard rail é qualquer coisa no codebase que impede o caminho errado e aponta o certo: um tipo (type) que não compila se você passar o valor errado; um teste que falha na hora; um linter que reclama; uma mensagem de erro clara que diz exatamente o que está faltando.

O porquê é puro custo: cada guard rail transforma uma cabeçada cara (o agente descobre o erro tarde, depois de reescrever meio sistema) numa correção barata (o erro aparece na hora, em uma linha). Pocock resume: "guard rails melhores, menos tokens batendo a cabeça na parede." O erro comum aqui é o oposto disto — gente que remove os testes "pra ir mais rápido". Sem guard rails, a IA anda no escuro, erra mais longe e te custa mais caro a cada passo.

Aqui está o coração do módulo, na frase de Pocock: "Tenha um codebase mais fácil de mudar → você pode empregar um modelo mais burro/mais barato pra fazer o mesmo trabalho." Repare na lógica: a capacidade necessária do modelo não é fixa — ela depende de quão difícil você tornou a tarefa. Um harness bom baixa a barra de inteligência exigida. Por isso um modelo mais barato consegue entregar o que, num codebase ruim, só um modelo caro entregaria.

E o reverso, que Pocock chama pelo nome: "Hamstring seu modelo desde o dia um → você precisa de um modelo esperto." Hamstringing (literalmente "cortar o tendão") é entregar à IA um terreno confuso, sem guard rails, sem documentação. Aí ela tropeça em tudo, e você é obrigado a pagar pelo modelo top só pra ele não se perder. Conexão com o módulo 1.1: como o harness é 50% do resultado, é ele — não o modelo — que define o teto de custo. O erro comum é a corrida pelo "modelo do momento": investir no motor caro pra compensar um chassi que você mesmo poderia ter consertado por muito menos.

O custo de um codebase ruim não é uma cobrança única; é um imposto recorrente sobre cada tarefa futura. A IA relê arquivos que não precisava ler, tenta abordagens que um guard rail teria barrado, e gera código que quebra outras partes (porque não tinha como saber que existiam). Cada uma dessas idas e vindas é token gasto. Multiplique por todas as mudanças do projeto e o "imposto" vira a maior linha da sua fatura.

Tem um efeito ainda mais traiçoeiro: um codebase ruim também esconde bugs, e bugs escondidos custam tokens (e dinheiro) toda vez que a IA tropeça neles. Pocock observa que muitos bugs profundos não exigem um modelo genial pra serem achados — "você poderia descobrir esses bugs com modelos mais baratos se olhasse nos lugares certos e desse o prompt/harness certo." Ou seja: o que parecia "precisar de IA cara" era, de novo, um problema de harness. O erro comum é normalizar a torneira pingando ("é assim mesmo, IA é cara") em vez de fechar a torneira.

A boa notícia: você não está preso ao codebase que tem. Refatorar é reorganizar o código por dentro — quebrar o arquivo gigante em módulos, dar nomes claros, adicionar tipos e testes — sem mudar o que o sistema faz por fora. E aqui mora a virada: a própria IA refatora pra você. Você gasta tokens uma vez pra arrumar a casa, e a cada mudança futura paga muito menos. É investimento, não despesa.

Como Pocock põe em DX × AX: melhorar o codebase é uma das alavancas "frequentemente esquecidas" pra melhorar a experiência do agente — e, com ela, o custo. Refatorar adiciona guard rails (tópico 2), torna o terreno navegável (tópico 1) e fecha a torneira pingando (tópico 4) — os três de uma vez. O erro comum é adiar refatoração "pra quando der tempo": como o custo é recorrente, cada dia adiado é mais tokens jogados fora. Veja na copybox abaixo como muda só o jeito de pedir a refatoração — do prompt vago ao prompt com guard rails:

❌ ANTES (prompt vago → muitos tokens, resultado incerto)
"arruma esse arquivo aí, tá uma bagunça"

✅ DEPOIS (prompt com guard rails → poucos tokens, resultado seguro)
Refatore o arquivo src/pagamento.js, SEM mudar o comportamento.
Objetivo: baratear mudanças futuras.
Regras (guard rails):
1. Quebre em módulos pequenos por responsabilidade (1 arquivo = 1 tema).
2. Adicione TIPOS nas funções públicas (assinaturas explícitas).
3. NÃO toque na lógica de negócio — só na organização.
4. Rode os testes existentes ao final; todos têm que continuar passando.
5. Se faltar teste pra um caminho crítico, escreva o teste antes de mover o código.
Entregue: lista do que mudou + confirmação de testes verdes.

O que não se mede não se melhora. A métrica certa não é "quanto gastei no mês" (isso esconde a causa), e sim tokens por mudança: quantos tokens uma tarefa típica consome, do pedido à entrega. Quando esse número está alto, é sinal de hamstringing — o codebase está obrigando o agente a ler e tentar demais. Quando cai depois de uma refatoração, você acabou de provar, em número, que o harness ficou melhor. É o resumo prático de todo o módulo: arquitetura (T1) e guard rails (T2) baixam o número; um codebase ruim (T4) o infla; refatorar (T5) o derruba; e um número baixo libera o modelo barato (T3). Copie o checklist abaixo e rode-o sempre que uma tarefa gastar mais do que devia:

Tarefa gastou tokens demais? Diagnostique o HARNESS, não o modelo:
[ ] ARQUITETURA — a IA teve que ler arquivos gigantes/irrelevantes?
[ ] GUARD RAILS — faltou type/teste/lint pra barrar o erro na hora?
[ ] DOCS — faltou um README/comentário apontando o lugar certo?
[ ] REPETIÇÃO — a IA tentou, errou e retentou o mesmo erro várias vezes?
Ação: refatore a área cara + adicione 1 guard rail.
Depois, reduza o modelo (ex.: do caro pro barato) e confirme que ainda passa.
Meta: o número de "tokens por mudança" cair na próxima vez.