Quando estava construindo o Downshift, precisei entender melhor como o Claude Code gastava contexto e escolhia os modelos dos subagentes. Eu vinha de uma dor bem concreta: pagava o plano Pro e, em poucos dias de trabalho, já tinha esgotado o limite semanal. Queria entender o que estava consumindo tanto e onde fazia sentido otimizar.
É como trabalhar com outro dev: passar a tarefa é só o começo. A gente também combina os limites, divide o que pode andar em paralelo e confere se a entrega atende ao que foi pedido. Com agentes, precisamos ainda decidir qual modelo usar, quanto esforço dedicar e o que vale carregar na conversa.
A decisão que vale levar para o próximo projeto é esta: escolher capacidade conforme o problema e dar ao agente uma forma concreta de verificar a entrega. Vamos aplicar isso a uma correção de API, com comandos e configurações que você pode adaptar.
1. Escolha modelo e esforço antes de aumentar o prompt
Imagine que POST /pedidos recebe {"quantidade": -1} e retorna 201 Created. Neste exemplo didático, o contrato exige quantidade positiva e prevê 400 Bad Request para esse caso. Precisamos corrigir a validação e manter a criação de pedidos válidos funcionando.
Para começar, confira três coisas diferentes:
| Configuração | O que significa | Como conferir |
|---|---|---|
| Versão do Claude Code | O programa instalado e os recursos disponíveis |
claude --version no terminal |
| Modelo | Quem recebe e resolve a tarefa |
/model na sessão |
| Effort | O esforço solicitado para raciocinar e executar |
/effort status na sessão |
O material que inspirou este artigo destaca uma mudança específica: Opus 5.5 em medium iguala ou supera Opus 5 em high nas avaliações de código e trabalho de conhecimento da Anthropic. Carregar a configuração antiga para a versão nova pode deixar de ser uma boa escolha. Isso não é um benchmark do nosso projeto. Fonte: configuração de modelos e esforço.
Na documentação consultada em 12/11/2026, opus, sonnet e haiku resolvem para a família 5.5 na API da Anthropic. Outros provedores podem usar versões anteriores. Opus 5.5 exige Claude Code v2.1.280+, Sonnet 5.5 v2.1.284+ e Haiku 5.5 v2.1.293+. Para repetir uma comparação, registre o ID completo. Tabela por provedor.
Modelo e effort não são a mesma alavanca. O modelo define a capacidade; o esforço influencia quanto trabalho ele dedica ao turno, incluindo investigação e verificação. Mais esforço pode gerar mais tokens e espera. Não define um teto fixo de gasto. Explicação da Anthropic.
Na API do exemplo, eu usaria esta referência inicial, como hipótese para testar:
| Situação | Combinação inicial | Motivo |
|---|---|---|
| Extrair campos e localizar consumidores conhecidos | Haiku 5.5, medium
|
Pesquisa delimitada, com retorno fácil de conferir |
| Corrigir validação com teste reproduzível | Sonnet 5.5, medium
|
Implementação com escopo e aceite claros |
| Investigar regressão com hipóteses concorrentes | Opus 5.5, medium
|
Diagnóstico exige cruzar evidências |
| Diagnóstico continua inconclusivo | Comparar Opus 5.5 em medium e high
|
Verificar se aprofundar melhora a solução |
Na prática: se o teste já mostra que falta uma validação, Sonnet em medium é meu ponto de partida. Se o erro só aparece com duas requisições simultâneas, preciso investigar concorrência: aí testaria Opus, começando em medium. A incerteza da tarefa orienta a escolha.
Subir para high ou max por hábito também tem efeito colateral: em tarefas delimitadas, esforço excessivo aumenta o tempo de raciocínio (overthinking) e leva o agente a inventar abstrações que você não pediu. Para rotinas recorrentes, vale calibrar o menor par (model × effort) que passa nos testes do repositório. O mesmo ceticismo se aplica a benchmarks de lançamento publicados pelos próprios laboratórios: agregadores independentes como o Epoch Capabilities Index (ECI) ajudam como triagem inicial entre modelos, mas não substituem a medição nos seus próprios casos de falha.
Para abrir a sessão de implementação no terminal:
claude --model claude-sonnet-5-5 --effort medium
A escala da família 5.5 inclui low, medium, high, xhigh e max. Comece no padrão e aumente quando houver uma lacuna concreta na investigação. Para mudar, use /effort high; a seleção direta salva a preferência para o modelo. A variável CLAUDE_CODE_EFFORT_LEVEL pode prevalecer e políticas da organização podem limitar o nível. Níveis e precedência.
Um detalhe de versão: no Claude Code v2.1.311+, ultrathink tem tratamento específico e pode elevar aquele turno a xhigh nos casos suportados. think e think hard são texto comum. A afirmação de que todas essas palavras perderam efeito ficou desatualizada. Semântica atual.
2. Dê um contrato de trabalho e um mapa curto
Em vez de começar com “analise profundamente e siga todas as boas práticas”, descreva o comportamento que precisa mudar:
Tarefa: POST /pedidos aceita quantidade -1 e retorna 201.
O contrato prevê 400 para quantidade não positiva; corrija a validação.
Primeiro, escreva um teste que reproduza a falha.
Limites: preserve os campos e os status previstos no contrato.
Pedidos válidos devem continuar retornando 201.
Não altere o esquema do banco.
Pronto: o teste falha antes da correção e passa depois;
as verificações relevantes passam e o diff pode ser revisado.
Se faltar informação sobre o contrato, apresente a dúvida antes de alterá-lo.
Isso dá ao agente uma tarefa executável e permite ao revisor conferir o resultado. Para experimentar sem um repositório pronto, salve o arquivo abaixo como pedidos_test.go. Ele contém o handler e os testes e usa apenas a biblioteca padrão do Go.
Exemplo completo: handler e testes em um arquivo
package pedidos
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func novoHandler(criar func()) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var pedido struct {
Quantidade int `json:"quantidade"`
}
if err := json.NewDecoder(r.Body).Decode(&pedido); err != nil {
http.Error(w, "JSON inválido", http.StatusBadRequest)
return
}
// Correção: rejeitar antes do efeito colateral.
if pedido.Quantidade <= 0 {
http.Error(w, "quantidade deve ser positiva", http.StatusBadRequest)
return
}
criar()
w.WriteHeader(http.StatusCreated)
})
}
func TestCriarPedido(t *testing.T) {
casos := []struct {
nome, corpo string
status, criacoes int
}{
{"negativa", `{"quantidade":-1}`, 400, 0},
{"zero", `{"quantidade":0}`, 400, 0},
{"positiva", `{"quantidade":1}`, 201, 1},
}
for _, caso := range casos {
t.Run(caso.nome, func(t *testing.T) {
criadas := 0
handler := novoHandler(func() { criadas++ })
req := httptest.NewRequest(http.MethodPost, "/pedidos",
strings.NewReader(caso.corpo))
req.Header.Set("Content-Type", "application/json")
res := httptest.NewRecorder()
handler.ServeHTTP(res, req)
if res.Code != caso.status {
t.Errorf("status: esperado %d, recebido %d", caso.status, res.Code)
}
if criadas != caso.criacoes {
t.Errorf("criações: esperado %d, recebido %d", caso.criacoes, criadas)
}
})
}
}
Execute no diretório onde salvou o arquivo:
go test -v pedidos_test.go
Para reproduzir o bug, remova temporariamente o bloco if pedido.Quantidade <= 0 e repita o comando. Os casos negativo e zero falham: recebem 201 e criam um pedido. Restaure a validação e rode novamente: os três casos passam. O teste confere tanto o status quanto o efeito colateral; devolver 400 depois de criar o pedido não resolveria o problema.
Conferi esse ciclo localmente para o artigo: sem a validação, dois casos falharam; com ela, os três passaram. É uma demonstração de comportamento HTTP, sem banco, autenticação ou servidor de produção. Em uma API real, mantenha os demais campos válidos para a falha acontecer pelo motivo que está testando.
O CLAUDE.md complementa esse pedido com o que vale para o projeto: comando de testes, convenções próprias e caminhos das regras. Não precisa recontar o funcionamento de Go ou copiar toda a documentação. A recomendação oficial é mantê-lo abaixo de 200 linhas. Imports @ carregam conteúdo; dividir um documento usando imports não elimina seu custo de contexto. Use ponteiros e regras por caminho quando fizer sentido. Memória e regras.
No Downshift (projeto open-source meu em Go que roda acoplado a ferramentas como Claude Code, Codex CLI e Cursor — o que chamamos de harness, a camada de software ao redor do modelo que controla contexto, ferramentas, permissões e hooks), aplicamos essa divisão diretamente no repositório. Como o Downshift existe para compactar saídas de terminal e aplicar limites de modelo nos subagentes dentro da política do projeto, precisamos manter as instruções dele enxutas em qualquer agente. O CLAUDE.md tem apenas três linhas: importa @AGENTS.md e aponta para docs/contrib/layering.md, mantendo o contrato compartilhado em AGENTS.md cravado no teto de 200 linhas para que todos os harnesses leiam o mesmo texto sem duplicar instruções.
Em vez de empilhar proibições em CAIXA ALTA no prompt esperando que o modelo se lembre delas no fim da sessão, as regras estruturais viram testes executáveis em go test ./internal/archtest. O arquivo internal/archtest/filesize_test.go falha se qualquer arquivo .go de produção ultrapassar 300 linhas (maxFileLines = 300), enquanto internal/archtest/layers_test.go trava as fronteiras de importação entre pacotes — por exemplo, garantindo que accounting (o pacote que contabiliza tokens) importe apenas telemetry, execwrap (o wrapper de comandos) e catalog:
// internal/archtest/layers_test.go
func TestLayerDirectImports(t *testing.T) {
allowed := map[string][]string{
"accounting": {"telemetry", "execwrap", "catalog"},
}
for pkg, ok := range allowed {
t.Run(pkg, func(t *testing.T) {
if bad := outsideAllowlist(directImports(t, pkg), ok); len(bad) > 0 {
t.Errorf("internal/%s imports %v; it may import only %v", pkg, bad, ok)
}
})
}
}
Se um agente tentar cruzar uma camada ou inflar um arquivo, o teste quebra de forma determinística antes da revisão humana, sem gastar tokens repetindo a regra a cada turno.
O Plan Mode continua útil para explorar uma mudança ampla antes de editar. Ele controla a etapa de trabalho e as ferramentas disponíveis; não aumenta o effort. Para esse bug delimitado, eu começaria pelo teste. Boas práticas.
3. Separe a pesquisa quando ela atrapalhar a correção
Se descobrir os consumidores exigir ler dezenas de arquivos, essa exploração pode ocupar a conversa inteira. Um subagente consegue pesquisar em contexto separado e devolver as evidências relevantes. Para uma busca curta, abrir outro agente pode acrescentar mais coordenação do que benefício.
Uma definição didática em .claude/agents/contratos-api.md:
---
name: contratos-api
description: Investiga consumidores de endpoints sem editar arquivos.
tools: Read, Grep, Glob
model: haiku
effort: medium
---
Identifique campos, status e consumidores do endpoint solicitado.
Retorne arquivo e linha de cada evidência e declare as lacunas.
Peça: “Use contratos-api para investigar os consumidores deste endpoint; retorne o contrato observado e o que não conseguiu confirmar.”
Um retorno útil nesse cenário seria: “O contrato prevê 400 para quantidade não positiva e 201 para pedido válido. Localizei o consumidor web, mas não confirmei o comportamento do aplicativo mobile.” É uma resposta ilustrativa; numa execução real, ela precisa trazer arquivo e linha das evidências. Essa lacuna deve continuar visível na revisão.
Aqui, a escolha do modelo é explícita e as ferramentas permitem apenas leitura. O alias acompanha o provedor; fixe o ID completo quando precisar reproduzir um teste. O subagente também consome cota: preservar a conversa principal não significa eliminar esse consumo. Configuração de subagentes.
Também não suponha que o effort será sempre herdado. Sem configuração própria, no mesmo modelo ele acompanha a seleção da sessão; em outro modelo, essa seleção não se aplica. Declare effort quando precisar controlar essa escolha e confira o modelo em /tasks. Regras de esforço.
Nos agentes reais do Downshift, como agents/researcher.md e agents/mechanical-worker.md, seguimos a mesma estrutura de escopo fechado, mas sem fixar um model: literal no frontmatter:
---
name: researcher
domain: core
mode: read
default_tier: small
playbook: research
tools: Read, Grep, Glob, Bash
---
- Be precise: cite file and line number for every claim.
- If you cannot find something, say so. Do not guess.
- Do not write or modify code. Report findings only.
O agente herda o modelo da sessão por padrão, mas quem coordena a tarefa pode sinalizar trabalhos mecânicos com [tier=small] (como prevê agents/mechanical-worker.md) para que o hook roteie o filho dentro da política do projeto sem chumbá-lo a um ID fixo. Note que default_tier e playbook no trecho acima são campos do catálogo do Downshift; no Claude Code puro (.claude/agents/*.md), você usa model: e effort:, como vimos em contratos-api.md. Já a seção obrigatória ## Gaps força o subagente a declarar o que não encontrou em vez de preencher lacunas com suposições.
Outra trava simples para cortar tokens de saída e acelerar a revisão humana é controlar a verbosidade da resposta. O retorno de um subagente deveria parecer saída de CI: arquivo, linha, status e só. Em agents/mechanical-worker.md, aplicamos essa disciplina direto no contrato:
- Report: what you changed (file and line), what you ran and its exit status, and
anything you left undone. No prose beyond that.
Sem essa regra, modelos capazes devolvem resumos narrativos em cada subtarefa; com ela, você lê o diff e o status de saída sem pagar por prosa redundante.
4. Faça o agente demonstrar que terminou
Na nossa API, uma entrega útil mostra três evidências: o teste reproduziu o problema, passou após a correção e as verificações relevantes foram executadas sobre o código final. “Revise duas vezes” não define nenhuma dessas provas.
Para continuar automaticamente até uma condição de término, /goal aceita um objetivo como:
/goal Corrigir o endpoint e incluir o teste de regressão.
Prova: executar as verificações do projeto e trazer à conversa
os comandos, códigos de saída e resumo dos resultados.
Preservar contrato público e esquema do banco.
Após 15 turnos, parar e relatar o bloqueio se não houver prova.
O avaliador de /goal lê a conversa; não abre arquivos nem executa comandos por conta própria. Por isso, a prova precisa aparecer no histórico. O limite de turnos escrito no objetivo é interpretado pelo avaliador, não um teto rígido de execução. O recurso também consome tokens e não muda as permissões. Funcionamento de /goal.
Na revisão, eu pediria: o nome dos testes executados, o resultado antes e depois e se o código mudou após a última execução. Isso permite conferir a entrega sem aceitar um “agora funciona” como prova. E vale lembrar que critério sem acesso real ao ambiente falha em silêncio: para APIs, o agente precisa rodar go test ou o linter; para fluxos visuais de front-end, precisa de automação de navegador (como Playwright ou Chrome DevTools) capaz de validar o estado renderizado.
No código do Downshift, automatizamos essa auditoria em internal/adapters/claudecode/verification.go. Em vez de confiar na frase final do subagente, readSubagentVerification lê o log JSONL da execução, casa cada chamada Bash de teste ou lint (go test, pytest, vitest, golangci-lint, etc.) com o tool_result correspondente e lê a flag IsError — mantendo sempre o último resultado (passed, failed ou none), sem gravar comandos nem saídas:
// internal/adapters/claudecode/verification.go (trecho de readSubagentVerification)
switch b.Type {
case "tool_use":
if b.Name == "Bash" && b.ID != "" && verifyCommand.MatchString(b.Input.Command) {
pending[b.ID] = true
}
case "tool_result":
if pending[b.ToolUseID] {
delete(pending, b.ToolUseID)
if b.IsError {
result = verificationFailed
} else {
result = verificationPassed
}
}
}
Limites críticos também precisam de controles além do texto. Em hooks baseados em comando, um hook PreToolUse bloqueia uma chamada antes da execução quando retorna código de saída 2 e envia o motivo em stderr para o contexto do Claude (enquanto exit 1 é tratado apenas como erro não bloqueante do script e deixa a ferramenta rodar). Ainda assim, sua eficácia depende das ações que o hook consegue identificar e interceptar; um filtro de comandos não protege sozinho todos os acessos ao banco. Contrato dos hooks.
Quando o hook serve para reescrever uma chamada sem quebrar as permissões do usuário, o cuidado de protocolo é o mesmo. Em internal/adapters/claudecode/shell.go, ShellRewrite troca apenas tool_input.command, copia todos os campos irmãos (description, timeout, run_in_background) intactos e omite permissionDecision de propósito para não atropelar regras de allow, ask e deny configuradas pelo desenvolvedor:
// internal/adapters/claudecode/shell.go (trecho de ShellRewrite)
ti["command"] = encoded
updated, _ := json.Marshal(ti)
return shellOutput{
HookSpecificOutput: shellHookOutput{
HookEventName: "PreToolUse",
UpdatedInput: updated, // sem permissionDecision: preserva allow/ask/deny
},
}, nil
O segundo ganho dessa interceptação está em filtrar dados via código determinístico antes de jogá-los na janela de contexto. Em vez de mandar milhares de linhas de go test -v ou git log para o LLM resumir, o Compactor com CCR (Command Context Recovery) em internal/execwrap/balance.go e internal/execwrap/keep.go só corta saídas acima de 16 KB (BalanceThreshold = 16 << 10) depois que keep salva o original em disco e devolve o ID de recuperação ([downshift compact: X to Y bytes; downshift retrieve <id>]):
// internal/execwrap/balance.go (trecho de balance)
if keep == nil || balanceRefused[family] || len(shown) <= threshold {
return nil, false
}
cut, applied := compressor.BalanceWith(balanceKindOf(family), body, cfg.limits)
if !applied {
return nil, false
}
id, stored := keep(append([]byte(nil), raw...))
if !stored {
return nil, false
}
return append(append([]byte{}, cut...), MarkerWithID(len(raw), len(cut), id)...), true
Repare nas travas de segurança: leituras de arquivos locais (FamilyFileRead) nunca sofrem corte com perda, se o armazenamento falhar o texto volta intacto (fail-open) e respostas HTTP que podem carregar cabeçalhos sensíveis como Set-Cookie não têm permissão para gravar saída bruta em disco.
É a aplicação prática de guias e sensores em harness engineering, por Birgitta Böckeler: instruções orientam; controles e verificações dão retorno sobre o que aconteceu.
5. Skills sem efeito placebo: criar pelo erro, orçar tokens e testar como código
O mesmo critério de prova vale para skills e plugins. No código, ninguém coloca uma dependência nova sem conferir peso e cobertura; em contexto de agente, o pessoal costuma instalar pacotes inteiros de SKILL.md sem medir o que muda na sessão.
5.1 Como as skills carregam no Claude Code (e o orçamento real em skills/README.md)
Uma skill no Claude Code não é gratuita, mesmo quando ninguém a chama naquela conversa. O carregamento funciona em dois estágios:
-
Estágio 1 — Custo fixo por turno: a linha
description:do frontmatter YAML de toda skill elegível entra no contexto em todas as sessões (com orçamento padrão de até 1% da janela de contexto). Além disso, como registramos nos próprios testes do Downshift (skills/orchestrator_skill_test.go), o harness escolhe qual skill acionar apenas peladescriptione ignora chaves extras comotriggers:. -
Estágio 2 — Carga sob demanda: o corpo do arquivo
SKILL.mdsó entra na conversa quando a descrição casa com a tarefa pedida.
Quando você instala o plugin do Downshift no Claude Code, ele também embarca um conjunto enxuto de skills próprias (/downshift:<nome>) para ensinar o agente a usar esses limites e comandos sem desperdiçar contexto. No arquivo skills/README.md, documentamos exatamente o custo de cada uma (medido em 17/10/2026 como estimativa bytes / 4, não um tokenizador exato):
| Skill no Downshift |
description (sempre carregada) |
Corpo (ao acionar) | Papel e ciclo de vida |
|---|---|---|---|
ponytail/SKILL.md |
~45 tokens | ~620 tokens | Menor mudança completa (53 linhas) |
downshift-setup/SKILL.md |
~66 tokens | ~730 tokens | Instalação com --dry-run; pode ser apagada após downshift doctor passar |
downshift-audit/SKILL.md |
~70 tokens | ~890 tokens | Inspeção somente leitura da sessão |
downshift-tune/SKILL.md |
~86 tokens | ~750 tokens (+ ~400 por ref) | Diagnóstico ordenado de gasto de tokens |
Somando todo o conjunto instalado pelo plugin do Downshift (incluindo a skill complementar downshift-effort, o agente mecânico e o comando de status), a taxa fixa fica em torno de 390 tokens por sessão. Uma skill não economiza nada por existir: ela só se paga quando muda uma ação concreta do modelo. Por isso, restringimos as descrições do Downshift para disparar apenas quando o usuário cita o Downshift ou pergunta sobre hooks e consumo — nunca em qualquer menção genérica a CLAUDE.md — e explicitamos na tabela quando uma skill descartável (como downshift-setup) pode ser deletada.
5.2 Criar a partir do erro observado: a skill downshift-effort dentro do Downshift
O erro mais comum ao escrever skills é sentar na frente de um arquivo em branco e inventar um manual de 300 linhas antes mesmo de testar o modelo. O guia da Anthropic (e a prática do Downshift) inverte a ordem:
- Rode a tarefa sem skill nenhuma em casos reais do repositório.
- Anote exatamente onde o modelo tropeçou (por exemplo: esqueceu rollback numa migration ou aplicou esforço máximo numa troca de nome trivial).
- Quando a sessão finalmente convergir, destile o
SKILL.mda partir do histórico daquela conversa — registrando só as decisões e correções observadas — e valide no modelo que você realmente usa em produção.
Um exemplo real dessa abordagem dentro do próprio repositório do Downshift é a skill skills/downshift-effort/SKILL.md (47 linhas no arquivo inteiro, embarcada junto com o plugin). Em vez de tentar ensinar engenharia de software do zero, ela ataca um erro recorrente de uso de tokens: gastar esforço alto em tarefa mecânica ou economizar verificação em código crítico.
---
name: downshift-effort
description: Advice for the orchestrator on matching reasoning and verification effort to what a task puts at risk. Use when deciding how hard to think, how much to check, or what effort to give a subagent, with Downshift installed.
---
# Effort follows the stakes
| Level | Typical work | Effort | Verification |
|---|---|---|---|
| Mechanical and reversible | rename, format, boilerplate, a typo, a lookup | fast, low | a glance at the diff |
| Ordinary code change with tests | a feature slice, a bug fix, a refactor with coverage | medium | run the tests that cover the change |
| High stakes | auth, security, money, production data, or a claim the user will act on unchecked | high | check it directly before you report |
Repare no desenho enxuto: ela classifica o risco em três faixas, proíbe subir esforço apenas "para parecer cuidadoso" e declara explicitamente que nunca escolhe o valor de effort por conta própria — quem decide é o agente principal, dentro da política declarada pelo usuário (como explico na Seção 6).
5.3 O protocolo de 3 braços do skill-placebo (e por que ponytail sobreviveu)
Testar uma skill comparando apenas "com skill" contra "sem skill" engana, porque qualquer bloco de texto extra injetado no contexto muda os pesos de atenção e o gasto de tokens do modelo.
Para isolar o efeito real, o estudo independente skill-placebo (Simon Ether) avaliou nove pacotes populares ao longo de 450 execuções no Claude Opus 5.5 (15 tarefas públicas de SWE-bench Verified, Terminal-Bench e TBLite, com 30 repetições por braço) usando três braços:
- Sem skill (plain): a tarefa pura no modelo base.
- Placebo de mesmo tamanho: texto neutro, sem instruções úteis, com a mesma contagem de tokens e instalado do mesmo jeito.
- Skill real: o pacote avaliado.
O resultado serve de freio para quem coleciona pacotes de terceiros:
- 6 de 9 pacotes empataram estatisticamente com texto neutro de mesmo tamanho;
-
1 pacote (
planning-with-files) foi pior que o placebo, derrubando a taxa de aprovação de 100% para 80%; - Apenas 2 de 9 (
ponytaileagent-skills) superaram seus placebos equivalentes em eficiência de custo — ainda que nenhum dos nove tenha custado menos que rodar sem skill alguma nessa amostra genérica.
No Downshift, embarcamos justamente skills/ponytail/SKILL.md (53 linhas), que concentra regras curtas contra over-engineering ("The shortest working diff wins... Lazy code without its check is unfinished"). Mesmo assim, o aprendizado do skill-placebo vale para qualquer regra nova: o texto precisa provar que resolve um erro recorrente melhor do que espaço vazio.
5.4 Três camadas de sensores para testar e limpar skills como código
Em vez de tratar SKILL.md como prosa estática que ninguém revisa, vale aplicar três sensores em camadas:
1. Testes unitários sobre o próprio Markdown (go test ./skills/...):
O Downshift já teve uma primeira tentativa chamada Universal Skill — uma skill monolítica que tentava ensinar tudo num único arquivo, chumbando nomes fixos de modelos (flash_lite / haiku-5-5) e nomes antigos de ferramentas MCP (Model Context Protocol, protocolo padrão para conectar agentes a ferramentas externas) que o servidor não registrava, em vez de consultar a ferramenta MCP providers que devolve os modelos disponíveis na sessão. Quando apagamos esse arquivo, criamos testes em skills/shipped_text_test.go, skills/orchestrator_skill_test.go e skills/effort_skill_test.go que barram modelos chumbados, ferramentas inexistentes e skills inchadas:
// skills/shipped_text_test.go e skills/effort_skill_test.go
func TestShippedTextNamesNoModel(t *testing.T) {
ids := catalogIDs(t)
for from, text := range shippedTexts(t) {
if found := modelLiterals(text, ids); len(found) > 0 {
t.Errorf("%s names models %v; models come from the providers tool", from, found)
}
}
}
func TestEffortSkillHasNoDollarsOrModelIDs(t *testing.T) {
text := effortText(t)
if strings.Contains(text, "$") {
t.Error("effort skill must keep accounting in tokens, found a dollar sign")
}
if n := strings.Count(text, "\n"); n >= 80 {
t.Errorf("effort skill has %d lines, want under 80", n)
}
}
2. Auditoria de custo e uso real com /skill-doctor:
Introduzido no Claude Code v2.1.261, o comando /skill-doctor (junto do /doctor) mostra quanto da janela cada descrição elegível está consumindo e quais skills nunca foram invocadas na prática. Skill que cobra taxa fixa em todo turno e nunca dispara sai do projeto.
3. Benchmark A/B com claude plugin eval:
Introduzido no Claude Code v2.1.269, o claude plugin eval executa uma suíte versionada em evals/ (prompt.md + avaliadores em graders/, desde checagens determinísticas gratuitas como regex, tool_used, tool_order e file_exists até juízes llm e baseline), rodando cada cenário com e sem a skill para medir o delta (Δ) real antes de manter a instrução no time. O fluxo abaixo resume essa comparação em três braços (sem skill, texto neutro e skill real):
6. Como medir consumo sem confundir tokens com a conta
Ao concluir uma tentativa, abra /usage. O bloco de sessão apresenta tokens por modelo, incluindo entrada, saída, leitura e escrita de cache, além de duração e custo estimado. No Pro, o valor em dólares não é uma cobrança adicional: a tela também mostra os limites do plano. Para faturamento de API, confira o provedor. Referência de consumo.
Na comparação, salve uma linha por tentativa:
tarefa | modelo/versão | effort | passou? | tokens por categoria |
custo estimado | duração | tentativas | intervenção humana
Use o mesmo estado inicial do código, prompt, testes, skills e ferramentas. Abra sessões novas, alterne a ordem das configurações e registre o estado do cache; não compare uma sessão já aquecida com outra fria como se fossem equivalentes. Repita os casos antes de concluir que houve ganho.
Inclua as falhas na conta: some o consumo de todas as tentativas de uma configuração e divida pelas entregas aceitas. Se nenhuma passou, não há custo por entrega aceita a reportar. Mantenha tokens de cache separados: um token lido do cache e um token de saída não têm o mesmo preço. A ocupação da janela de contexto também não representa todo o consumo acumulado.
O que essa comparação mostrou no Downshift
Foi essa distinção que precisei levar para o Downshift. No estudo de 21/10/2026, a bateria teve 46 execuções com tarefas mecânicas e delegação obrigatória:
| Configuração | Aceitas | Tokens por execução aceita |
|---|---|---|
opusplan nativo |
10 de 11 | 2,00 milhões |
opusplan com roteamento do Downshift |
12 de 12 | 1,52 milhão |
O relatório registra 24,1% menos tokens por execução aceita, contando as falhas no consumo do grupo. O compactador estava desligado nos dois grupos comparados; essa diferença é do experimento de roteamento. O intervalo de 95% foi amplo: de 2,1% a 46,7%. Mais de 98% dos tokens eram de cache. Portanto, esse percentual não significa a mesma redução na fatura ou aumento do limite semanal do Pro.
É um resultado histórico do roteamento usado naquele experimento, anterior à mudança de arquitetura registrada como decisão O8 no repositório — quando o roteador deixou de escolher o modelo por conta própria e passou apenas a aplicar, no hook PreToolUse, a escolha feita pelo agente principal dentro da política declarada pelo usuário, como ressalva o README atual. Não comprova o efeito da implementação atual, nem se estende a tarefas gerais. O aprendizado aplicável aqui é medir a entrega aceita e identificar de onde vem a diferença antes de anunciar economia.
Já para o corte determinístico de saídas antes da janela de contexto (a segunda alavanca do Downshift), as medições separadas registradas no mesmo README mostram onde o filtro de código reduz volume sem envolver outro LLM:
| Medição de compactação | Resultado | Escopo |
|---|---|---|
| Compactação sem perda (lossless) | 59,3% menos bytes | 64 fixtures em corpus sintético |
| Compactação com CCR ativo | 69,4% menos bytes | 113 fixtures em corpus sintético (52,6% com CCR desligado) |
Compactação balanceada (> 16 KB) |
76,3% menos bytes | 4 saídas reais do repositório (go test -v, git show, git log -p, grep -rn; 35,0% só com lossless), com linhas cortadas recuperáveis via downshift retrieve
|
Como bytes reduzidos no terminal e tokens por execução aceita estão em unidades e amostras distintas, nenhuma das tabelas acima permite afirmar economia automática na fatura mensal ou no limite semanal do plano Pro.
Conclusão: por onde começar na próxima sessão
Quando voltei para o problema que abriu esta investigação — o limite semanal do plano Pro acabando em poucos dias enquanto eu construía o Downshift —, ficou claro que o gasto raramente nasce de um único prompt longo. Ele se acumula na soma de modelo superdimensionado para tarefa mecânica, logs brutos despejados na janela de contexto, skills que cobram pedágio em todo turno sem mudar o comportamento e proibições escritas em prosa onde deveria haver um teste ou hook determinístico.
Se você quiser aplicar esse fluxo amanhã no seu repositório sem refazer tudo do zero, comece por estes cinco passos na ordem:
-
Calibre
model×effortpelo risco: entre emSonnet 5.5commediumquando a falha já tem reprodução clara (como noPOST /pedidos) e reserve oOpus 5.5para investigações com hipóteses concorrentes. -
Corte o
CLAUDE.mdpara abaixo de 200 linhas: troque avisos emCAIXA ALTApor testes de arquitetura (go test) e hooksPreToolUsecomexit 2para regras inegociáveis. -
Isole pesquisas extensas e filtre saídas longas: delegue buscas pesadas a subagentes somente leitura com retorno seco (
file:line+## Gaps) e compacte logs volumosos (> 16 KB) antes da janela de contexto. -
Exija prova executada no
/goale pode skills ociosas: amarre o critério de parada ao comando e ao código de saída impressos na conversa, rode/skill-doctore valide skills próprias comclaude plugin eval. -
Meça no
/usagecontando as falhas: some todas as tentativas até a entrega aceita — e, se quiser automatizar a compactação de comandos e a política de subagentes descritas aqui, o guia de instalação do Downshift mostra como testar em modo seguro comdownshift setup --dry-runedownshift doctor.
O ganho prático desse desenho é conseguir responder, em qualquer revisão de código assistido: por que usamos essa capacidade, o que o agente pôde tocar e qual evidência executada prova que a mudança funciona. Nenhuma automação de harness substitui o domínio humano sobre a arquitetura, as fronteiras entre módulos e os modos de falha do sistema — e é exatamente esse critério que impede transformar uma sessão barata em dívida técnica cara.
Olhando para o seu CLAUDE.md ou para as skills instaladas hoje no seu ambiente: qual regra ainda está escrita como pedido no prompt, mas já deveria ter virado um teste ou um hook determinístico?
Referências
- Vídeos que inspiraram a seleção dos temas: IA em 6 minutos e Maestros da IA.
- Modelos, versões e esforço, explicação do mecanismo e Epoch Capabilities Index (ECI).
- Memória e CLAUDE.md, boas práticas, skills e subagentes.
-
Hooks,
/goale medição de consumo. -
Downshift: código citado (
AGENTS.md,archtest,agents/,claudecode/,execwrap/eskills/) e estudo controlado de tarefas mecânicas, 21/10/2026. - Skill-placebo: método e resultados.
- Harness engineering — Birgitta Böckeler.



Top comments (0)