Semana passada, um dono de SH que mentoro me mandou um print do Slack interno dele. Um dev sênior reclamando que o Claude Code “ficou burro de repente”. Outro dizendo que o /effort não aparecia. Um terceiro perguntando por que o Opus consumia rate limit tão rápido.
Sabe o que estava acontecendo? Cada um estava usando um modelo diferente. O sênior tinha pinado Opus 4.5 manualmente. O pleno estava no Sonnet padrão. O júnior, sem querer, estava no Haiku. E o tal que reclamava do /effort? O modelo dele nem suportava a feature — mas o Claude Code não avisou nada. Falhou silenciosamente.
Isso é o que eu chamo de model sprawl: cada dev na sua bolha, usando o modelo que quiser, gastando o que quiser, e o CEO olhando a fatura no fim do mês sem entender por que passou de R$ 8 mil para R$ 23 mil.
Se você leu meus artigos sobre managed-settings.d e X-Claude-Code-Session-Id, já sabe que governança de IA não é luxo — é sobrevivência. Aqueles dois artigos resolveram configuração centralizada e observabilidade de custos. Faltava a terceira peça: controle sobre qual modelo cada dev realmente usa.
Hoje fecho essa trilogia.
O Que é modelOverrides (e o Stack Completo de Model Governance)
O Claude Code tem um sistema completo de configuração de modelos que a maioria das SHs ignora completamente. Não é uma feature só — é um stack de 5 camadas que, juntas, dão controle total sobre quem usa o quê.
Camada 1: `availableModels` — O Picker Controlado
A config mais direta. Você define quais modelos aparecem no /model picker:
{
"availableModels": ["sonnet", "haiku"]
}Pronto. Seus devs só veem Sonnet e Haiku. Opus some do menu. Ninguém usa Opus sem sua autorização.
Combine com managed settings (aquele managed-settings.d/ que expliquei naquele artigo) e nenhum dev consegue fazer override — nem via ANTHROPIC_MODEL, nem via --model, nem via /model na sessão.
O Default do model picker continua sempre disponível (baseado no plano do usuário), mas os modelos nomeados ficam restritos à sua lista.
Camada 2: `modelOverrides` — O Mapeamento Enterprise
Aqui é onde fica interessante para SHs que usam Bedrock, Vertex AI ou Foundry. O modelOverrides mapeia os IDs de modelo do Anthropic para IDs específicos do seu provider:
{
"modelOverrides": {
"claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
"claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
}
}Quando o dev seleciona “Opus” no picker, o Claude Code manda a request para o seu Bedrock inference profile. Não para o Anthropic direto. Você controla o endpoint, o custo, a região, tudo.
Isso é governança real: o dev acha que está usando Opus normalmente, mas por baixo a request passa pelo seu gateway, com seus limites, suas regras de roteamento, sua auditoria.
Camada 3: `ANTHROPIC_DEFAULT_*_MODEL` — O Pin de Versão
Essa é a que mais SH ignora — e a que mais causa problema silencioso.
O Claude Code usa aliases como sonnet, opus, haiku. Esses aliases apontam para a versão mais recente. Quando a Anthropic lança um modelo novo, o alias muda. Se o seu provider ainda não habilitou a versão nova, quebra silenciosamente.
A própria Anthropic avisa na documentação:
⚠️ Set all three model environment variables to specific version IDs as part of your initial setup. Skipping this step means a Claude Code update can break your users without any action on your part.
A solução é pinar:
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"Agora, não importa quantas versões a Anthropic lançar — seus devs continuam na versão que você testou e aprovou.
Camada 4: `ANTHROPIC_CUSTOM_MODEL_OPTION` — O Gateway no Picker
Se você usa um LLM Gateway (LiteLLM, Bifrost, Kong, ou um proxy próprio como o CCProxy), pode adicionar uma entrada custom no picker:
export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Opus roteado pelo gateway interno"O dev abre /model, vê “Opus via Gateway” como opção nativa. Sem gambiarras, sem scripts manuais, sem instruções em Wiki que ninguém lê.
O Claude Code não valida o model ID dessa opção — aceita qualquer string que seu endpoint entenda. Flexibilidade total.
Camada 5: `_SUPPORTED_CAPABILITIES` — O Anti-Degradação Silenciosa
Essa é a camada que o Trevor Samaroo documentou no Medium e que causa mais dor invisível.
Quando você pina um modelo com ID de provider (tipo um ARN do Bedrock), o Claude Code não reconhece qual modelo é. Ele usa .includes() pra detectar capabilities — se o ID não contém “claude-opus-4-6” como substring, features como /effort, extended thinking e adaptive reasoning desaparecem silenciosamente.
O dev não recebe erro. A feature simplesmente não aparece. Ele acha que o Claude Code “não tem essa feature” e segue trabalhando com menos ferramentas.
A solução:
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES="effort,max_effort,thinking,adaptive_thinking,interleaved_thinking"Agora o Claude Code sabe exatamente o que o modelo suporta, independente do ID. Sem degradação silenciosa.
Como Funciona na Prática: Configuração Completa para uma SH
Vou mostrar uma configuração real que uso em mentorias. SH com 20 devs, Bedrock na AWS, 3 squads.
Arquivo central: `managed-settings.d/10-model-governance.json`
{
"model": "sonnet",
"availableModels": ["sonnet", "opus", "haiku", "opusplan"],
"modelOverrides": {
"claude-opus-4-6": "arn:aws:bedrock:us-east-2:ACCOUNT:application-inference-profile/opus-prod",
"claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:ACCOUNT:application-inference-profile/sonnet-prod",
"claude-haiku-4-5-20251001": "arn:aws:bedrock:us-east-2:ACCOUNT:application-inference-profile/haiku-prod"
},
"env": {
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
"ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES": "effort,max_effort,thinking,adaptive_thinking,interleaved_thinking",
"ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES": "effort,thinking,adaptive_thinking,interleaved_thinking"
}
}O que cada squad vê
- Squad A (frontend): Sonnet como default, pode usar Haiku pra tasks simples
- Squad B (backend core): Opus disponível pra debugging complexo, opusplan pra arquitetura
- Squad C (manutenção): Haiku + Sonnet, sem acesso a Opus (custo controlado)
Cada squad pode ter seu próprio arquivo em managed-settings.d/ com availableModels mais restritivo. Arrays fazem merge e dedup. O arquivo com prioridade mais alta (managed/policy) vence.
Bonus: `opusplan` — O Híbrido Inteligente
Para tech leads e arquitetos, o alias opusplan é ouro:
- Em plan mode: usa Opus (raciocínio complexo, decisões de arquitetura)
- Em execution mode: troca automaticamente pra Sonnet (geração de código, implementação)
O melhor dos dois mundos: raciocínio de Opus quando precisa pensar, velocidade e custo de Sonnet quando precisa executar. Sem intervenção manual.
Por Que Isso Importa para Sua Software House
O Custo do Model Sprawl
Números que vi na prática e em pesquisas:
- CIOs estimam 60-70 ferramentas de IA em uso. A realidade é 200-300. Em SHs menores a proporção é similar: você acha que todos usam Sonnet, mas metade dos devs já experimentou Opus “pra ver se é melhor” e esqueceu de voltar.
- 90% das empresas têm funcionários usando contas pessoais de IA para tarefas de trabalho. Shadow AI é a regra, não a exceção.
- Modelos agentic consomem 5-30x mais tokens por task comparado a chatbot (Gartner, março/2026). Um dev no Opus fazendo code review consome em 1 hora o que deveria durar o dia inteiro.
- Claude Code custa ~$6/dev/dia em média, mas a variância é enorme. Vi SHs onde um dev gastava $2/dia e outro $25/dia — no mesmo plano, no mesmo projeto.
A Degradação Silenciosa
Esse é o problema mais perigoso porque ninguém percebe.
Trevor Samaroo documentou: quando o Claude Code não reconhece o modelo pelo ID, ele desabilita features sem avisar. Seu dev perde:
- /effort — controle de nível de raciocínio (low/medium/high/max)
- Extended thinking — raciocínio profundo com thinking tokens
- Adaptive thinking — alocação dinâmica de thinking baseada em complexidade
O dev não sabe que essas features existem no setup dele. Ele simplesmente produz menos. E você não sabe que ele produz menos. E ele não sabe que produz menos. Um ciclo de ignorância que custa dinheiro todos os dias.
A Quebra Silenciosa de Versão
Em março de 2026, a crise de rate limit do Claude Code (MacRumors reportou, The Register confirmou) expôs outro problema: SHs usando providers terceiros (Bedrock, Vertex) com aliases sem pin viram seus ambientes quebrarem quando a Anthropic atualizou os modelos. O alias opus passou a apontar pra uma versão que o provider deles ainda não suportava.
Resultado: devs com erro 400, features desaparecendo, produtividade zero até alguém descobrir que o problema era um mismatch de versão de modelo.
Três variáveis de ambiente teriam evitado tudo isso.
O Stack Completo: A Trilogia de Governança
Se você acompanhou os artigos anteriores, agora tem as três peças:
| Peça | Artigo | O Que Resolve |
|---|---|---|
| **Configuração** | [managed-settings.d/](https://thuliobittencourt.com/claude-code-managed-settings-d-governanca-ia-software-house/) | Governança centralizada por squad/equipe |
| **Observabilidade** | [X-Claude-Code-Session-Id](https://thuliobittencourt.com/claude-code-session-id-header-observabilidade-custos-proxy-software-house/) | Visibilidade de custos por sessão/dev |
| **Modelo** | modelOverrides (este artigo) | Controle sobre qual modelo cada dev usa |
Juntas, essas três camadas transformam o Claude Code de “ferramenta que cada dev configura como quer” em “infraestrutura de IA governada pela empresa”.
O Que Eu Penso
Na minha experiência com 300+ software houses, governança de IA não é sobre restringir. É sobre criar padrão.
O dev que reclama de restrição é o mesmo que reclama quando o rate limit acaba na quarta-feira porque alguém da equipe deixou 3 agents em Opus rodando no fim de semana. Model governance não tira liberdade — organiza ela.
A curva de governança está 18 meses atrasada em relação à curva de adoção. Só 14% das organizações têm enforcement de AI assurance no nível enterprise. As outras 86% estão na fase do “cada um faz o que quer e a gente torce pro melhor”.
Se a sua SH já usa Claude Code com 5+ devs e você ainda não configurou availableModels nem modelOverrides, você está pagando uma conta que não entende, com features que não funcionam, em versões que podem quebrar amanhã.
Três variáveis de ambiente. Um arquivo JSON. Essa é a distância entre model sprawl e model governance.
Conclusão
Model governance no Claude Code não é enterprise theater — é a diferença entre uma SH que sabe o que está pagando e uma que descobre na fatura. modelOverrides mapeia seus modelos para seus endpoints. availableModels restringe o picker. ANTHROPIC_DEFAULT_*_MODEL pina versões. _SUPPORTED_CAPABILITIES evita degradação silenciosa.
Se você já implementou managed-settings.d e session ID, adicionar model governance é uma tarde de trabalho. Se não implementou nenhum dos três, comece por aqui — é a camada que tem impacto financeiro mais imediato.
Se você quer implementar esse nível de governança de IA na sua software house e não sabe por onde começar, eu posso ajudar. Já fiz isso com dezenas de SHs.
Sou Thulio, mentoro 300+ SHs desde 2016.
