Como registrar no repositório qual modelo do Claude seu time usa (e por que isso importa)

Fala aí, beleza? "Usei o Opus" parece uma informação completa, mas não diz qual modelo rodou de verdade

E isso vira dor de cabeça rapidinho: alguém abre um bug dizendo que o Claude gerou um código zoado, outra pessoa tenta reproduzir e o resultado sai diferente

Aí começa a investigação… foi o prompt? foi o contexto? ou eram dois modelos diferentes respondendo ao mesmo "opus"? 🤔

Neste post eu te mostro como deixar a versão do Claude no projeto explícita e versionada no repositório, com o settings.json commitado e um registro no CLAUDE.md

Assim relato de bug, comparação de resultado e revisão de prompt param de ficar sem contexto 🙂

Por que registrar a versão do modelo importa?

Antes do como, o porquê (senão parece só burocracia, né?)

Na Anthropic existem duas coisas diferentes: o ID do modelo e o alias

O ID identifica uma versão fixa: o modelo por trás de um ID não muda enquanto esse ID existir

Já o alias é um ponteiro, ele aponta pra alguma coisa que pode mudar com o tempo

Se você já usou tag de imagem Docker, é bem semelhante: latest é o alias, uma tag de versão específica é o ID

O que o alias opus e sonnet do Claude Code resolve hoje?

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

No Claude Code, o alias opus usa o Opus mais recente e o sonnet usa o Sonnet mais recente

E tem mais: o MESMO alias aponta pra modelos diferentes conforme o provedor

O modelo default também muda: nas contas Pro, Max, Team, Enterprise e na API da Anthropic é o Opus 5.5, já no Microsoft Foundry é o Sonnet 4.5

Por isso a própria Anthropic recomenda usar versões específicas de modelo em produção pra manter o comportamento consistente, deixando os aliases pra experimentação

Resumindo: duas pessoas do time digitando o mesmo "opus" podem estar rodando modelos diferentes, e ninguém percebe até o resultado divergir

E se o time quer medir se o Claude Code está acelerando o projeto, comparar números sem saber qual modelo gerou cada resultado é comparar banana com laranja haha

O que você precisa antes de começar?

A lista é curta:

• Um projeto com Claude Code em uso
• O projeto num repositório git, com permissão pra commitar na pasta .claude
• Saber qual provedor o time usa: API da Anthropic, Claude Platform on AWS, Amazon Bedrock, Google Cloud ou Microsoft Foundry

Por que o provedor importa tanto?

Porque além do mapeamento de alias mudar, o formato do ID também muda por plataforma:

• Amazon Bedrock: prefixo anthropic., no formato anthropic.claude-{nome}-{major}[-{minor}]
• Vertex AI do Google Cloud: sufixo com data, no formato claude-{nome}-{major}-{minor}@{AAAAMMDD}

Pra ver quais modelos estão disponíveis pra sua conta, abra uma sessão do Claude Code e rode o /model sem argumento:

/model

Ele lista os modelos disponíveis, e é dali que sai o nome certo pra usar nos próximos passos

Passo a passo: como deixar o modelo explícito e versionado no repositório

1. Escolha entre alias e ID completo

Os aliases do Claude Code são sonnet, opus, haiku, opusplan, best e fable

O best usa o Fable onde ele estiver disponível (senão, Opus) e o opusplan usa Opus no plan mode e depois Sonnet na execução

Alias é massa pra experimentar: se o time está avaliando o Fable, por exemplo, faz sentido testar o Fable no seu projeto primeiro e só depois fixar

Pra consistência, o caminho é o ID completo, como o exemplo da documentação: claude-opus-5-5

Se liga nisso: a partir da geração 4.6, os IDs da Anthropic não têm data (claude-{nome}-{major}[-{minor}]) e cada ID sem data já é o ID canônico, apontando pra um snapshot fixo

Modelos anteriores à 4.6 levam data no ID (claude-{nome}-{major}-{minor}-{AAAAMMDD}), tipo claude-sonnet-4-5-20250929

Nesses modelos mais antigos, o nome sem data (claude-sonnet-4-5) é alias e aponta pro snapshot datado mais recente daquela versão

Erro comum deste passo: achar que opus é uma versão fixa, ele não é! É um ponteiro pro Opus mais recente

2. Defina a chave model no .claude/settings.json e commite

O .claude/settings.json é o arquivo de configurações compartilhado do projeto: vale pra todo mundo que trabalha na pasta e deve ir pro git pra que o time receba a mesma configuração

A chave model aceita alias ou ID completo, então fixar fica assim:

{
  "model": "claude-opus-5-5"
}

Depois é commitar normalmente:

git add .claude/settings.json
git commit -m "chore: fixa modelo do Claude Code em claude-opus-5-5"

Erro comum deste passo: colocar a chave no ~/.claude/settings.json. Esse é o escopo User, fica na sua máquina e não vai pro time

3. Alternativa: fixe as versões por trás dos aliases no bloco env

Tem time que gosta de continuar digitando opus e sonnet no /model, e tudo bem

Nesse caso, dá pra fixar o que cada alias resolve usando variáveis de ambiente no bloco env do settings:

• ANTHROPIC_DEFAULT_OPUS_MODEL controla o alias opus (e o opusplan no plan mode)
• ANTHROPIC_DEFAULT_SONNET_MODEL controla o alias sonnet (e o opusplan fora do plan mode)

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5"
  }
}

Confira os nomes exatos na lista do /model antes de commitar, principalmente se o provedor não for a API da Anthropic (lembra do prefixo e do sufixo do passo anterior?)

Erro comum deste passo: fixar só uma das duas variáveis. Aí o opusplan roda metade fixado e metade solta, e o plan mode fica com uma versão enquanto a execução segue o Sonnet mais recente

4. Documente a escolha no CLAUDE.md

O settings.json diz QUAL modelo, mas não diz POR QUÊ

O CLAUDE.md do projeto fica em ./CLAUDE.md ou ./.claude/CLAUDE.md, guarda instruções do time e é compartilhado pelo controle de versão, então é um ótimo lugar pra isso

Não existe um formato oficial da Anthropic pra registrar modelo, então isso aqui é sugestão de boa prática:

## Modelo do Claude usado no projeto

- Modelo fixado: claude-opus-5-5 (definido em .claude/settings.json)
- Provedor: API da Anthropic
- Motivo: consistência entre revisões de prompt e relatos de bug
- Status do modelo: Active (revisar ao receber aviso de deprecation)

### Ao relatar bug gerado pelo Claude, inclua:
- Modelo usado (nome que aparece no /model)
- Como a sessão foi iniciada (flag --model, ANTHROPIC_MODEL ou /model)
- Prompt e arquivos de contexto envolvidos

Pra confirmar que o arquivo foi carregado, rode /context na sessão e procure o CLAUDE.md na lista em Memory files

Erro comum deste passo: atualizar o CLAUDE.md e esquecer o settings.json (ou o contrário). Aí você tem duas fontes dizendo coisas diferentes, que é pior do que não ter nenhuma

5. Deixe as exceções pessoais no .claude/settings.local.json

Alguém do time precisa testar outro modelo? Sem problema

Cada pessoa pode sobrescrever a configuração do projeto pra si mesma no .claude/settings.local.json, sem mexer no que vale pro resto do time

Quando o próprio Claude Code cria esse arquivo, ele já fica fora do git

Se você criar na mão, adicione no .gitignore:

.claude/settings.local.json

Erro comum deste passo: commitar o settings.local.json por acidente e fazer o teste pessoal de alguém virar a config de todo mundo. Tome cuidado com aquele git add . apressado!

O que pode sobrescrever o modelo do projeto sem ninguém perceber?

Fixar no repositório é metade do caminho

A outra metade é saber o que passa por cima dessa configuração, porque é aí que mora o famoso mas na minha máquina deu certo xD

Resposta direta: o modelo fixado no .claude/settings.json pode ser sobrescrito pelo .claude/settings.local.json de cada pessoa, pela variável ANTHROPIC_MODEL exportada no shell, pela flag --model ao iniciar a sessão e pelo /model dentro da sessão

Bora ver cada um com calma

A ordem de precedência dos arquivos é:

• Local (.claude/settings.local.json) vence o projeto
• Project (.claude/settings.json) vence o usuário
• User (~/.claude/settings.json) fica por último

E fora dos arquivos:

• ANTHROPIC_MODEL exportada no shell tem prioridade sobre a chave model de QUALQUER arquivo e vale pra sessão iniciada com ela
• A flag --model também vale só pra sessão iniciada com ela
• O /model troca o modelo dentro da sessão
• ANTHROPIC_DEFAULT_MODEL só entra como fallback, quando nenhum arquivo define model
• O alias default limpa qualquer override de modelo e volta pro padrão da conta

O mais traiçoeiro é o ANTHROPIC_MODEL esquecido no .bashrc ou .zshrc de alguém: o projeto diz uma coisa e a sessão roda outra

Por isso, em relato de bug, vale registrar como a sessão foi iniciada (flag, variável de ambiente, troca com /model) e não só o que está no settings

E para times grandes?

Aí dá pra ir além de combinar no papo

Administradores podem usar availableModels em managed/policy settings pra restringir os modelos que os usuários podem escolher, por família, prefixo de versão ou ID completo

E o enforceAvailableModels aplica essa lista também à opção Default, fechando a última brecha

Quando revisar o registro: aposentadoria e status de modelos

Modelo fixado não é modelo eterno

A Anthropic aposenta modelos antigos regularmente, e cada modelo passa por quatro status:

• Active: em uso normal
• Legacy: versão mais antiga
• Deprecated: ainda funciona, mas já tem substituto recomendado e data de aposentadoria
• Retired: as requisições falham

A boa notícia é que dá tempo de se organizar: pra modelos lançados publicamente, a Anthropic avisa com pelo menos 60 dias de antecedência, por e-mail e na documentação

Só que tem um detalhe: essas datas valem pras plataformas operadas pela Anthropic (Claude API, Claude Platform on AWS e Microsoft Foundry)

Amazon Bedrock e Google Cloud definem cronogramas próprios, então status e datas podem ser diferentes por lá

Minha sugestão de processo:

• Anote no CLAUDE.md o status do modelo fixado
• Quando chegar aviso de deprecation, revise o registro
• Troque o ID num commit próprio, só com essa mudança

Assim o histórico fica rastreável: dá pra olhar o git log e saber exatamente a partir de quando o time mudou de modelo 😀

Conclusão: um commit que poupa horas de investigação

Recapitulando o que montamos:

• .claude/settings.json commitado com o ID completo ou com as variáveis ANTHROPIC_DEFAULT_OPUS_MODEL e ANTHROPIC_DEFAULT_SONNET_MODEL fixadas no bloco env
• CLAUDE.md explicando qual modelo, por quê e o que entra num relato de bug
• .claude/settings.local.json pras exceções pessoais, fora do git

Parece pouca coisa, mas é o tipo de detalhe que separa um bug resolvido em 10 minutos de uma tarde inteira caçando fantasma

Próximo passo? Abre o repositório agora, roda o /model pra ver o que está ativo, cria o commit de fixação e inclui um campo "modelo usado" no template de issue do time

E se ficou dúvida ou teu time resolve isso de outro jeito, bora trocar uma ideia 🙂

Até o próximo post!