Pular para conteúdo

Trabalho com agentes de IA — disciplina de tokens

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-04

O contexto de um agente de IA é recurso escasso e caro. Duas frentes simétricas cortam custo sem perder exatidão:

  • Input (o que entra no contexto) — corte a saída de comando na fonte: reporter frugal, ferramentas nativas de arquivo em vez de despejo de shell, e o rtk (proxy que resume a saída de CLI; padrão da casa — ferramentas). Detalhe e receita por stack: CI, gates e testes § Higiene de saída de comando.
  • Output (o que o agente escreve) — estilo terso + carve-out verbatim. É o que segue.

Estilo terso (output)

Corte artigo, filler, gentileza, hedging. Fragmentos OK. Sinônimo curto. Termo técnico exato. Padrão: [coisa] [ação] [razão]. [próximo passo]. Corta ~65–75% dos tokens de output com a exatidão técnica intacta. É regra de estilo — vale com ou sem plugin de compressão.

Anti-padrão (custo, zero substância):

"Claro! Fico feliz em ajudar. O problema que você enfrenta provavelmente é…"

Vira:

"Bug no auth. Expiry usa <, devia <=. Fix:"

Intensidade:

  • full — default recomendado. Dropa artigo/filler/gentileza/hedging.
  • lite — conservador (só tira filler, mantém frases). Quando a revisão pede fluidez.
  • ultra — evitar no fluxo X-Adm: abrevia demais para revisão de spec/plano/migração.

Status e fechamento — nomeie só o que falhou

O desperdício recorrente não é a gentileza — é narrar o óbvio que passou. As mensagens-padrão que o agente repete a cada sessão (gates, fechamento, confirmações) são onde mais sobra folga:

  • Gate verde não se narra linha a linha. Nomeie só o que falhou (com a saída); verde é uma linha — gates ✓ (strict, frontmatter, nav, manifesto). É o "verboso só sob falha" do reporter frugal (CI e testes) aplicado ao que o agente escreve, não só ao que o comando imprime.
  • Não re-descreva o que o git status/o diff/o tool já mostram. "Pronto, editei X, Y, Z" quando o diff já lista → corte para o que não é óbvio: a decisão e a pendência.
  • Não ecoe a escolha do usuário de volta depois de um AskUserQuestion — aja.
  • Corte o preâmbulo do tool call ("Rodando os gates:") — a chamada já aparece na transcrição.
  • Prosa do fechamento §6 é terse; o literal não. §6: nada a reportar. + a pendência em uma linha, não um parágrafo — o carve-out (a mensagem de commit e a linha §6) segue exato.

Regra de bolso: corte conectivo e status óbvio; nomeie o que quebrou, não o que passou; preserve verbatim o carve-out.

Verbatim OBRIGATÓRIO — o carve-out da casa

Terso corta prosa; nunca os deliverables que o fluxo precisa exatos. Não comprimir:

  • conteúdo de documentação — tudo que se escreve em docs//site sai em prosa normal pt-BR (constituição §1.8): terso é o chat com o dev, nunca o texto publicado;
  • código, nomes de API/CLI, tipos de commit (feat/fix/…), strings de erro;
  • a mensagem de commit pronta e a linha §6 — é o contrato da REGRA Nº 2 (o dev cola verbatim);
  • tabelas que carregam dado (call-sites, deltas de migração, referências);
  • specs e planos .ia/ — a estrutura ACT (prompt → spec → plan) é lida por outra skill.

O caveman já preserva código e strings de erro; o X-Adm soma os deliverables da casa — senão a compressão engole justo o que o fluxo precisa exato.

Mecanismo — setup

O estilo entra por um hook SessionStart (versionável, contido, no padrão do checa-constituicao.sh) que injeta a regra — funciona sem o plugin. A receita do .claude/caveman.sh, o plugin opcional e a configuração de intensidade estão em Ferramentas de token § caveman.

Pontual (sem persistir): diga caveman mode na sessão; desligue com normal mode.

As duas frentes são cultura da casa; as ferramentas que as operacionalizam — rtk (input) e caveman (output) — vivem em Ferramentas de token do dev, com install, habilitar e configurar de cada uma.

Loop de verificação — servidor local pega porta efêmera

Subir um servidor pra conferir (app em modo debug, E2E local, preview de docs) não fixa porta — pede uma porta efêmera e lê a URL que o processo imprime. Chutar 8080/8000 colide com um processo já vivo (ou zumbi de uma run anterior) e o sintoma é traiçoeiro: ou o bind falha e o passo quebra, ou pior — responde na porta outro servidor e você confere um build velho (foi o episódio do mkdocs serve na 8000 servindo o build anterior, e o Test Resources reconectando na porta morta em java-micronaut). A URL real vem do próprio servidor (log de startup ou objeto de teste), nunca de um palpite. Se a porta fixa for inevitável (ex. um webhook externo que aponta pra ela): mate por porta antes de subir e confirme via curl o que está servido (não presuma que é o seu). Mecânica por stack: E2E em CI, gates e testes · Micronaut · Flutter.

Sonde toolchain com comando bare, um por chamada. Descobrir versão de ferramenta (java -version, python --version, node --version, mkdocs --version) roda sem prompt porque o allow-list é por ferramenta (java *, python *, ...). Encadear o probe — java -version 2>&1 | head; python --version || ... — sempre pede autorização: comando composto (pipe/;/||/2>&1) não casa nenhuma regra de allow-list, por mais larga que seja. Wildcard por ferramenta cura variação de forma, não comando opaco. Um probe por chamada, bare — mesma disciplina do rtk e da /xadm-release.

Auto-análise de uso (fechamento §6)

As ferramentas só rendem se usadas bem. No fechamento de cada ciclo (/x-documentar), faça a auto-análise da disciplina de tokens:

  1. Medir — rtk gain (eficiência acumulada), rtk discover (comandos não-cobertos / oportunidades perdidas), rtk cc-economics (gasto × economia). O caveman não tem métrica aqui: o lado output é qualitativo — fui terso? o carve-out foi respeitado?
  2. Auto-corrigir — comando bare (pipe/&&/$()/prefixo-de-env furam o hook do rtk), ferramentas nativas de arquivo, output terso + carve-out (Ferramentas).
  3. Rotear o gap sistêmico — é o que faz outros apps aprenderem junto:
  4. recipe de stack que economiza (ex. sdk default java p/ o Gradle) → §6 pro central;
  5. comando verboso sem handler nativo (ex. python3, mkdocs) → envolva com rtk err/rtk summary (ajuste de uso nosso, resolve a maioria); só o que o wrapper não cobre vira issue no RTK tracker.

O score per-projeto guia a auto-correção local; só o gap sistêmico vira lição de constituição.

Lembrete automático (opcional): um hook SessionStart leve imprime a eficiência do rtk gain no início da sessão — .claude/token-check.sh:

#!/usr/bin/env bash
# Lembrete de disciplina de tokens (silencioso se sem rtk).
command -v rtk >/dev/null 2>&1 || exit 0
rtk gain 2>/dev/null | grep -iE 'Efficiency|saved' | head -2
echo 'Fechamento: rode rtk gain/discover + auto-check (engenharia/ferramentas · engenharia/agentes).'

Some ao array SessionStart do .claude/settings.json: { "type": "command", "command": "bash .claude/token-check.sh" }.