Otimização de modelos no Claude Code

Instruções da skill

---
name: claude-code-otimizacao
description: Configura o roteamento de modelos de um projeto no Claude Code — descobre o catálogo de modelos vigente, define o modelo principal, cria subagentes em modelos mais baratos para as tarefas menores e escreve a política de delegação no CLAUDE.md, tudo adaptado ao stack do repositório. Use quando pedirem para otimizar custo do Claude Code num diretório, reduzir gasto de tokens, configurar subagentes, usar Opus ou Haiku para tarefas pequenas dentro do projeto, ou montar a configuração de modelos de um repositório novo.
---

# Otimização de modelos no Claude Code

Monta, num diretório de projeto, a configuração que faz a conversa principal rodar num modelo forte e delegar as tarefas menores a subagentes em modelos mais baratos.

Não existe roteamento automático por complexidade no Claude Code. O que existe, e é o que esta skill configura, são três peças que juntas produzem o mesmo efeito: o modelo principal no `settings.json`, subagentes com modelo próprio no frontmatter, e uma política escrita que diz ao modelo principal quando delegar. Sem a terceira peça as outras duas não economizam nada, porque o modelo não delega por conta própria.

## Regras gerais

Nunca sobrescreva configuração existente sem mesclar. `settings.json` e `CLAUDE.md` costumam ter conteúdo do time. Leia, mescle, preserve.

Nunca escreva um nome de modelo de memória. O catálogo muda e modelos são aposentados com data marcada. Descubra o catálogo vigente a cada execução, como descrito no passo 3.

## Passo 1 — Situar-se

```bash
pwd && ls -a
test -d .git && git rev-parse --show-toplevel
ls -a .claude/ 2>/dev/null
ls .claude/agents/ 2>/dev/null
cat .claude/settings.json 2>/dev/null
cat .claude/settings.local.json 2>/dev/null
ls CLAUDE.md AGENTS.md 2>/dev/null
```

Se o diretório não for a raiz de um projeto (sem `.git`, sem manifesto de pacote), pergunte ao usuário se é ali mesmo que ele quer a configuração antes de escrever qualquer coisa.

Se já existirem agentes em `.claude/agents/`, liste-os para o usuário e pergunte se devem ser mantidos, substituídos ou complementados. Nunca apague um agente existente sem confirmação.

## Passo 2 — Diagnosticar o que atrapalha

Três coisas silenciosamente anulam a configuração. Verifique e relate:

```bash
env | grep -E '^ANTHROPIC_(MODEL|DEFAULT_|SMALL_FAST_)' || echo "nenhuma variável de modelo no ambiente"
```

- `ANTHROPIC_MODEL` no ambiente **sobrescreve** o `model` do `settings.json`. Se estiver setada, avise: a configuração do projeto será ignorada enquanto ela existir.
- `ANTHROPIC_SMALL_FAST_MODEL` está descontinuada. Se aparecer, diga para remover.
- `.claude/settings.local.json` tem precedência sobre `.claude/settings.json`. Se houver um `model` lá, ele vence.

A precedência completa, da mais alta para a mais baixa: managed settings, flag `--model` na linha de comando, `settings.local.json`, `settings.json` do projeto, `~/.claude/settings.json` do usuário.

## Passo 3 — Descobrir o catálogo de modelos

Faça isto **toda vez**, antes de escolher o perfil. Pare no primeiro degrau que devolver uma lista utilizável.

**Degrau 1 — a própria conta.** É o mais confiável, porque reflete o que a conta do usuário pode usar, não o que existe no mundo.

```bash
claude --help 2>/dev/null | grep -i -A3 -- '--model'
```

Se a saída não listar modelos, peça ao usuário para rodar `/model` numa sessão do Claude Code e colar o que aparece. É um pedido barato e resolve o caso com certeza.

**Degrau 2 — Models API, se houver chave.**

```bash
[ -n "$ANTHROPIC_API_KEY" ] && curl -sS --max-time 15 \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
  https://api.anthropic.com/v1/models | grep -oE '"id":"[^"]+"' | sort -u
```

Vale só para quem usa chave de API. Assinatura por conta ChatGPT/Claude não expõe isso.

**Degrau 3 — catálogo publicado.** A página de modelos responde markdown bruto quando se acrescenta `.md` à URL, com uma tabela que traz as linhas `Claude API ID`, `Claude API alias` e `Retirement`:

```bash
curl -sS --max-time 20 https://platform.claude.com/docs/en/models/overview.md \
  | grep -E 'Claude API (ID|alias)|Retirement|^\| (Description|Pricing)'
```

Se o `curl` falhar por rede ou proxy, busque a mesma URL com a ferramenta de fetch web disponível na sessão.

**Degrau 4 — fallback datado.** Só se os três anteriores falharem: use a tabela de `references/perfis-e-modelos.md`, que está marcada com a data em que foi conferida, e **diga ao usuário** que está usando um catálogo possivelmente desatualizado e que ele deve confirmar com `/model`.

Ao final deste passo você deve ter, explicitamente: quais modelos existem, qual o alias de cada um, e quais estão marcados para aposentadoria. Se dois degraus discordarem, prevaleça o degrau mais alto e mencione a divergência.

## Passo 4 — Escolher o perfil

Pergunte ao usuário qual perfil aplicar, apresentando os três com os **nomes reais** descobertos no passo 3. Se ele já tiver dito na conversa, não pergunte de novo.

| Perfil | Principal | Implementação | Mecânico | Quando |
| --- | --- | --- | --- | --- |
| `max` | modelo de topo | modelo forte | modelo mais barato | Arquitetura difícil, projeto novo, refatoração grande |
| `equilibrado` | modelo forte | modelo intermediário | modelo mais barato | Desenvolvimento do dia a dia num projeto já estruturado |
| `economico` | modelo intermediário | modelo intermediário | modelo mais barato | Manutenção, correções pequenas, orçamento apertado |

Prefira **aliases** a IDs completos: o alias sobrevive à troca de snapshot do modelo. Use ID completo só quando o usuário pedir reprodutibilidade estrita.

Se algum modelo candidato tiver data de aposentadoria próxima, não o use e avise o usuário.

## Passo 5 — Ler o projeto

O valor desta skill está aqui: os subagentes precisam saber os comandos reais do projeto, senão o usuário vai corrigi-los toda vez.

```bash
ls package.json pyproject.toml requirements.txt go.mod Cargo.toml composer.json Gemfile pom.xml build.gradle 2>/dev/null
```

Conforme o que existir, extraia:

- **Comando de teste** — scripts do `package.json`, seção do `pyproject.toml`, `Makefile`, workflow de CI em `.github/workflows/`
- **Comando de lint e format** — eslint, biome, ruff, black, gofmt, clippy, rubocop
- **Gerenciador de pacotes** — presença de `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `uv.lock`, `poetry.lock`
- **Estrutura** — onde ficam código, testes e migrações; monorepo ou pacote único
- **Convenções** — leia o `CLAUDE.md`/`AGENTS.md` existente e o `CONTRIBUTING.md`

Confirme o comando de teste com o usuário se houver ambiguidade. Não invente comando: um subagente que roda o comando errado é pior que nenhum.

## Passo 6 — Escrever a configuração

### settings.json

Mescle, nunca substitua o arquivo inteiro. Troque os valores pelos modelos descobertos no passo 3:

```bash
mkdir -p .claude
python3 - <<'PY'
import json, pathlib
p = pathlib.Path(".claude/settings.json")
cfg = json.loads(p.read_text()) if p.exists() else {}
cfg["model"] = "ALIAS_PRINCIPAL"
cfg.setdefault("env", {})["CLAUDE_CODE_SUBAGENT_MODEL"] = "ALIAS_INTERMEDIARIO"
p.write_text(json.dumps(cfg, indent=2, ensure_ascii=False) + "\n")
print(p.read_text())
PY
```

`CLAUDE_CODE_SUBAGENT_MODEL` é o padrão para subagentes que não declaram modelo próprio. Sem ele, um subagente sem `model` herda o modelo principal — que é justamente o caro.

### Subagentes

Escreva em `.claude/agents/`. Dois são a base; acrescente os que o stack justificar.

O campo `description` é o que faz o modelo principal escolher o subagente certo, então descreva **situações**, não capacidades. "Use quando precisar rodar a suíte de testes e reportar falhas" funciona; "especialista em testes" não.

Templates completos e adaptáveis em `references/agentes.md`. A base:

- **`grunt`** (modelo mais barato) — busca, renomeação, formatação, boilerplate, rodar testes e reportar. Ferramentas: `Bash, Glob, Grep, Read, Edit`.
- **`dev`** (modelo forte ou intermediário, conforme o perfil) — implementar feature ou corrigir bug já diagnosticado, com arquitetura definida.

Acrescente conforme o repositório:

- **`testes`** (barato) quando houver suíte real — já com o comando do projeto no corpo do agente
- **`migracoes`** (forte) quando houver diretório de migrações de banco
- **`revisor`** (forte, somente leitura) quando houver `CONTRIBUTING.md` ou processo de PR

### Política de delegação

Sem isto nada acontece. Acrescente ao `CLAUDE.md` do projeto, criando o arquivo se não existir, **anexando** a uma seção nova sem tocar no resto:

```markdown
## Política de delegação

Antes de executar, classifique a tarefa:

- Busca ampla, leitura de muitos arquivos, renomeação, formatação, boilerplate,
  rodar testes, verificar se algo existe → delegue ao subagente `grunt`.
- Implementar módulo, endpoint, migração, ou corrigir bug já diagnosticado,
  com arquitetura definida → delegue ao subagente `dev`.
- Decisão de arquitetura, modelagem de dados, revisão de segurança, refatoração
  que cruza módulos, diagnóstico de bug sem causa conhecida → faça aqui.

Dispare subagentes independentes em paralelo, numa única mensagem.
Não releia arquivos que um subagente já resumiu — confie no retorno dele.
```

## Passo 7 — Verificar e relatar

```bash
cat .claude/settings.json
ls -1 .claude/agents/
head -5 .claude/agents/*.md
```

Confirme que cada agente tem `model` declarado — um agente sem `model` é um vazamento de custo silencioso.

**Teste de fumaça.** Se o usuário autorizar (custa uma chamada mínima), valide cada slug gravado antes de dar o trabalho por concluído:

```bash
claude -p "responda apenas OK" --model ALIAS_PRINCIPAL
```

Erro de modelo desconhecido aqui é muito melhor que erro na primeira tarefa real do usuário.

Relate ao usuário em poucas linhas: de qual degrau veio o catálogo, o perfil aplicado, quais agentes foram criados e com qual modelo cada um, o que foi preservado do que já existia, e qualquer variável de ambiente que precise ser removida. Diga também que a mudança de modelo principal vale a partir da **próxima** sessão do Claude Code, ou imediatamente com `/model`.

## Armadilhas

- Subagente sem `model` no frontmatter herda o modelo caro. É o erro mais comum.
- `description` genérica faz o modelo principal nunca delegar. Descreva situações.
- Dar `Write` e `Bash` irrestritos ao agente mais barato aumenta o risco de estrago em tarefa mal interpretada. Restrinja as ferramentas ao necessário.
- Não configure modelo por skill ou por comando: o Claude Code não suporta isso, o modelo é sempre por escopo.
- `opusplan` existe e alterna o modelo de topo no plan mode com um intermediário na execução, mas é um roteamento mais raso que esta configuração. Mencione como alternativa só se o usuário quiser algo mais simples.
- Um projeto configurado há meses pode ter modelos já aposentados. Ao revisitar, refaça o passo 3 e compare com o que está gravado.

Requisitos

• Claude Code v2.1 ou superior
• acesso a terminal no diretório do projeto
• python3 disponível para mesclar JSON com segurança

Permissões declaradas

• leitura e escrita em .claude/settings.json, .claude/agents/ e CLAUDE.md do projeto
• execução de comandos somente-leitura no repositório (ls, cat, git, grep)
• leitura de variáveis de ambiente que começam com ANTHROPIC_ para diagnóstico

Versões

• v1.1.0

  Descoberta do catálogo de modelos em tempo de execução, substituindo a lista fixa. A skill agora percorre uma escada de fontes a cada invocação — CLI e conta do usuário (claude --help e /model), Models API quando há ANTHROPIC_API_KEY, catálogo publicado em platform.claude.com como markdown, e só então a tabela local, agora rotulada como fallback datado. Perfis max, equilibrado e economico reescritos em termos relativos (topo, forte, intermediário, mais barato) e mapeados para slugs concretos apenas após a descoberta, para sobreviverem à troca de nomes de modelo. Acrescentados verificação de data de aposentadoria antes de gravar e teste de fumaça opcional que valida cada slug com uma chamada mínima.

• v1.0.0

  Primeira publicação. Configura modelo principal, subagentes com modelo próprio e política de delegação no CLAUDE.md, com três perfis (max, equilibrado, economico) e adaptação ao stack do repositório.