Como usar o Claude Opus 5.5 em uma migração de código que atravessa o repositório inteiro

Fala aí, beleza? A Anthropic soltou o Claude Opus 5.5 e trouxe junto um caso que chama atenção: testadores iniciais concluíram uma migração de código de 680.000 linhas em menos de um dia, trabalho que levaria semanas pra um time de engenharia

Se você já tentou algo parecido, sabe que a parte difícil não é o modelo ser burro

Migração que atravessa o repositório inteiro quebra por outros motivos: escopo mal cortado, nenhum ponto de parada, ninguém sabendo dizer o que já foi migrado e o que ainda não foi, e aquele momento clássico em que a IA "consertou" um arquivo que ninguém pediu pra ela tocar

Então a ideia aqui é bem prática: um roteiro de etapas que o Claude Opus 5.5 consegue conduzir com autonomia, com critério de revisão humana e ponto de parada em cada fase

Bora? 🙂

O que o Claude Opus 5.5 muda para migrações grandes

O lançamento foi em 22 de setembro de 2026, apresentado como sucessor do Opus 5 e voltado especificamente pra codificação agêntica de longa duração

Ou seja: tarefa que roda por horas, com muitas chamadas de ferramenta, sem humano puxando o volante a cada passo

Os números que importam pro nosso caso, todos atribuídos à própria Anthropic:

• janela de 1 milhão de tokens de contexto
• auditoria e correção de uma base de 200.000 linhas em menos de três horas, contra mais de 20 horas e 2,5x mais tokens no Opus 5
• consistência: sucesso em 39 de 40 tentativas numa tarefa repetida de reduzir tempo de carregamento em todas as páginas de um app web

Esse último número é o mais subestimado da lista

Pra migração em lote, consistência vale mais que pico de inteligência: você vai rodar a MESMA tarefa dezenas de vezes em pedaços diferentes do repo, e o que te mata é a variância, não o teto

Na Artificial Analysis, o modelo aparece com 54 no Artificial Analysis Intelligence Index na configuração Adaptive Reasoning, High Effort, Default Fallback, contra mediana 25 dos modelos comparáveis

E o preço de API ficou assim: US$ 4 por milhão de tokens de entrada e US$ 20 por milhão de saída, com leitura de cache a US$ 0,20

Segundo o The New Stack, isso representa entrada e saída 20% mais baratas que o Opus 5, leitura de cache 60% mais barata e custo cerca de 40% menor em cargas típicas nas configurações padrão

Nada disso é promessa de que a SUA migração vai rodar em um dia, beleza? São os números da fonte, e o resto é método

O que você precisa antes de começar

Antes de abrir o terminal, checklist rápido:

• Repositório versionado e uma branch dedicada só pra migração. Não é frescura, é o seu Ctrl+Z de verdade
• Suíte de testes que roda de ponta a ponta. Sem isso você não tem como saber se o lote 7 quebrou o que o lote 3 arrumou
• Critério de aceite escrito. Uma definição literal do que significa "migrado" nesse projeto. Se você não consegue escrever em três linhas, o modelo também não vai adivinhar
• Acesso ao modelo. O Claude Opus 5.5 é o novo padrão no Claude Max e o modelo mais forte disponível no Claude Pro. Na Claude API, o identificador é claude-opus-5-5; no Amazon Bedrock, ele vira anthropic.claude-opus-5-5
• Plano pago se você for usar dynamic workflows. Eles estão disponíveis em todos os planos pagos, com acesso via Anthropic API, e também no Amazon Bedrock, no Google Cloud Agent Platform e no Microsoft Foundry. No plano Pro, são ativados na linha Dynamic workflows dentro do /config do Claude Code

E um alerta operacional que quase ninguém conta antes:

Requisições sinalizadas pelos classificadores de segurança caem por padrão pra um modelo anterior, o Opus 4.8, no Claude.ai, no Claude Code e no Claude Cowork

Em fluxo agêntico de várias etapas isso pode acontecer requisição a requisição, misturando modelos dentro do MESMO fluxo

Tome cuidado: se metade do seu lote saiu com uma qualidade e metade com outra, essa pode ser a explicação antes de você culpar o prompt

Passo a passo: quebrar a migração em etapas que o Opus 5.5 executa e você revisa

O princípio é um só: o modelo trabalha melhor quando o pedaço cabe inteiro na cabeça dele E quando existe um lugar pra voltar se der ruim

Vamos ver na prática?

1. Mapear o repositório com um inventário antes de editar qualquer coisa

Primeira rodada é leitura pura, zero escrita

Você quer um inventário: onde o padrão antigo aparece, em quantos arquivos, agrupado por módulo, com os casos esquisitos separados dos casos repetitivos

Essa é a hora dos subagentes. Eles são arquivos Markdown com frontmatter YAML e servem exatamente pra tarefas laterais que inundariam a conversa principal com resultado de busca, log e conteúdo de arquivo

Ou seja: o subagente varre, sofre, e devolve pra conversa principal só o resumo que interessa

O erro comum deste passo: deixar a busca acontecer no contexto principal. Você queima metade do contexto com grep e chega na fase de edição sem espaço pra raciocinar sobre a arquitetura

2. Escrever as regras da migração no CLAUDE.md do projeto

Instrução que precisa valer em TODOS os lotes não pode morar no chat

Pra isso existe o CLAUDE.md no diretório do projeto (contexto do projeto) ou o ~/.claude/CLAUDE.md (instruções de nível de usuário)

Um esqueleto que funciona bem:

## Migração em andamento

Padrão antigo (remover):
  chamadas diretas a `db.query()` espalhadas nos controllers

Padrão novo (adotar):
  toda leitura passa pelo repositório em `src/repositories/`

Nunca tocar:
  - `src/legacy/billing/` (congelado, contrato com terceiro)
  - arquivos de migration já aplicados em produção

Critério de aceite do lote:
  - suíte de testes verde
  - nenhum import novo fora da lista aprovada
  - diff só dentro do diretório do lote

Repare que metade do arquivo é sobre o que NÃO fazer

É o pedaço mais valioso, porque migração codebase-wide erra muito mais por excesso de iniciativa do que por falta

O erro comum deste passo: escrever a regra como desejo vago ("modernizar o acesso a dados") em vez de padrão reconhecível. O modelo precisa conseguir olhar um arquivo e responder sim ou não

3. Planejar no plan mode antes de liberar escrita

No Claude Code, você entra no plan mode pressionando Shift+Tab até a barra de status mostrar plan mode on, ou já iniciando a sessão assim:

claude --permission-mode plan

Aí você pede o plano da migração completa, lê, e corta

Detalhe que muita gente não usa: Ctrl+G abre o plano no editor de texto, e você edita ali antes de o Claude seguir

É nesse editor que você apaga as três etapas otimistas que ele inventou e transforma "migrar o módulo de pagamentos" em quatro lotes menores

O erro comum deste passo: aprovar um plano de 15 etapas porque ele "pareceu bom". Plano aprovado sem corte vira execução sem freio

4. Fatiar em lotes e delegar como dynamic workflow

Um dynamic workflow é um script JavaScript que orquestra vários subagentes

O Claude escreve o script a partir da tarefa que você descreveu e um runtime executa em segundo plano

A documentação do Claude Code indica esse recurso justamente pros casos que a gente tá tratando aqui: auditoria codebase-wide, migração grande e pesquisa que precisa de checagem cruzada

Pra iniciar, você pede o workflow no próprio prompt. Algo no espírito de:

Crie um dynamic workflow para migrar o lote 1 (src/modules/orders).
Regras da migração: ver CLAUDE.md.
Um subagente por arquivo tocado.
Cada subagente roda os testes do módulo antes de encerrar.
Não saia de src/modules/orders.

O erro comum deste passo: lote definido por quantidade de arquivos em vez de fronteira de código. 40 arquivos do mesmo módulo é um lote; 40 arquivos espalhados por seis módulos é uma confusão com número bonito

5. Acompanhar com /workflows e salvar o script pro próximo lote

Com a execução rodando, /workflows lista as execuções em andamento e concluídas, a fase de cada uma e quantos agentes já terminaram

Esse é o seu painel. É aqui que você percebe que um lote empacou numa fase antes de gastar mais uma hora de execução

E tem o truque que faz a migração escalar: rode /workflows, selecione a execução e pressione s pra guardar o script daquela execução como comando

Pronto, o lote 2 não começa do zero. Você reusa o mesmo script que já funcionou no lote 1, mudando só o alvo

O erro comum deste passo: deixar o workflow rodar sem olhar e só voltar no fim. Se o primeiro lote já saiu torto, todos os outros vão sair tortos junto

6. Subir o esforço só onde dói

O parâmetro effort controla a profundidade de raciocínio e tem cinco níveis: low, medium, high, xhigh e max

Detalhe importante pra quem vem do modelo anterior: no Claude Opus 5.5 o padrão é medium, enquanto no Opus 5 o padrão era high

Se o seu fluxo parecia "mais raso" depois de trocar de modelo, provavelmente é isso, não é o modelo

Pra lote repetitivo, o padrão dá conta e sai mais barato. Pra o lote que tem regra de negócio torta e dependência circular, você sobe

No topo tem o ultracode, que combina esforço xhigh com orquestração automática de workflows:

claude --effort ultracode

Dentro de uma sessão já aberta, /effort ultracode faz o mesmo. E dá pra fixar em arquivo de settings:

{
  "ultracode": true
}

Esse settings pode ser passado via --settings ou vir num control request do Agent SDK

O erro comum deste passo: ligar ultracode no repositório inteiro "por garantia". Você paga raciocínio profundo pra renomear import, que é a tarefa mais burra do mundo

7. Ligar o advisor como segunda opinião nos pontos de decisão

O advisor consulta um segundo modelo em momentos de decisão: antes de fixar uma abordagem, quando trava num erro recorrente, ou antes de declarar a tarefa concluída

E ele recebe a conversa completa, incluindo chamadas de ferramenta e resultados. Não é um "o que você acha disso aqui?" solto no vácuo

/advisor opus

/advisor sem argumento mostra o modelo atual e os aliases aceitos, a flag --advisor configura por sessão e /advisor off desliga

Uma regra dura da documentação: o advisor precisa ser ao menos tão capaz quanto o modelo principal. Segunda opinião mais fraca que a primeira não é revisão, é ruído

Esse padrão de segunda leitura é o mesmo que vale quando você precisa revisar código em linguagem que não domina: você não vira especialista de repente, mas para de aceitar a primeira resposta como verdade

O erro comum deste passo: tratar o advisor como aprovador. Ele é insumo da SUA decisão, não substituto dela

8. Automatizar a barreira de qualidade com hooks

Hooks são comandos shell, endpoints HTTP, chamadas de ferramenta MCP, prompts de LLM ou subagentes definidos por você, que rodam automaticamente em pontos específicos do ciclo de vida do Claude Code

É aqui que teste e lint deixam de depender da boa vontade do agente e viram parte do trilho

E tem um detalhe que casa perfeito com migração em lote: hooks de arquivos de settings, de managed policy settings e de plugins também rodam DENTRO dos subagentes

Ou seja, a barreira vale pra cada agente do workflow, não só pra conversa principal 😀

O erro comum deste passo: confiar no "rode os testes no final" escrito no prompt. Instrução em prompt é pedido; hook é garantia

Onde cortar os lotes: tipos de migração e como fatiar cada um

O método é sempre o mesmo, o que muda é a unidade de lote

Troca de biblioteca ou framework

Unidade de lote: por módulo, seguindo a fronteira de import

Começa pelo módulo com menos dependências de entrada (o que ninguém importa) e sobe na árvore

Sinal de que o lote ficou grande demais: o plano começa a incluir "ajustar também os testes de X e Y" de módulos que não estavam no escopo

Atualização de API interna com assinatura nova

Unidade de lote: por tipo de chamada, não por arquivo

Todas as chamadas com a assinatura A viram um lote, as com assinatura B viram outro, mesmo que estejam espalhadas

É o caso em que o inventário do passo 1 paga sozinho o tempo investido

Sinal de alerta: o mesmo arquivo sendo tocado em três lotes diferentes. Se isso acontecer muito, reagrupe por arquivo

Renomeação de padrão que aparece em centenas de arquivos

Unidade de lote: por diretório, com lote grande mesmo

Aqui o trabalho é mecânico e o effort padrão (medium) já resolve

Sinal de que passou do ponto: começarem a aparecer alterações de lógica no diff. Renomeação que altera comportamento não é renomeação, é refatoração disfarçada

Remoção de código morto

Unidade de lote: por candidato, com verificação obrigatória antes da remoção

Esse é o tipo que mais precisa de ponto de parada humano, porque "ninguém chama" é uma afirmação difícil de provar em código dinâmico

Sinal de alerta: o agente removendo algo e adaptando um teste pra continuar verde. Teste ajustado pra acompanhar a remoção é um ponto de parada, sempre

Auditoria com correção

É o caso que a Anthropic cita direto: base de 200.000 linhas auditada e corrigida em menos de três horas, contra mais de 20 horas e 2,5x mais tokens no Opus 5

Unidade de lote: por categoria de achado, separando o relatório da correção

Primeiro roda a leitura e gera a lista, você prioriza, e só depois vira workflow de correção

Esse fatiamento é o mesmo raciocínio de quando você usa o agente pra achar falhas de segurança no código: achado e correção são etapas diferentes, com revisão humana no meio

Sinal de que o lote ficou grande demais: o relatório vindo com achados de severidades misturadas e sem prioridade. Aí você não revisa, você só lê

Pontos de parada: quando interromper e revisar antes de seguir

Antes dos sintomas, a rede de segurança

O Claude Code cria checkpoints automáticos: cada prompt que inicia um turno gera um checkpoint, e o Claude tira um snapshot dos arquivos antes de cada alteração

Pra voltar, dois toques em Esc ou o comando /rewind abrem o menu com as opções restaurar código e conversa, restaurar conversa, restaurar código ou resumir a partir dali

Saber que existe a opção de restaurar SÓ a conversa muda o jogo: às vezes o código tá certo e quem se perdeu foi o contexto

Agora os sintomas 👇

Sintoma: a saída ficou muda entre chamadas de ferramenta

Causa: no Claude Opus 5.5, o texto entre chamadas de ferramenta volta em blocos de thinking cujo texto vem vazio na configuração de exibição padrão

Solução: se a sua aplicação transmitia esse texto como atualização de progresso, ela vai parecer travada mesmo estando trabalhando. Troque o sinal de progresso pra algo que não dependa desse texto

Como prevenir: teste o fluxo agêntico em uma tarefa curta antes de soltar o lote de duas horas. Silêncio de duas horas dá pânico e pânico gera Ctrl+C no meio da migração

Sintoma: o fluxo mistura modelos no meio do caminho

Causa: requisições sinalizadas pelos classificadores de segurança caem por padrão pro Opus 4.8 no Claude.ai, no Claude Code e no Claude Cowork, e num fluxo de várias etapas isso pode acontecer requisição a requisição

Solução: trate esse lote como não confiável e revise o diff inteiro dele à mão antes de seguir

Como prevenir: lote menor. Quanto mais curto o lote, menor a chance de ele terminar com metade do trabalho feito por um modelo e metade por outro

Sintoma: o lote editou arquivo fora do escopo

Causa: a fronteira do lote existia no seu prompt, mas não existia como regra persistente

Solução: /rewind, restaurar código, e reescrever a fronteira no CLAUDE.md com caminho literal em vez de descrição

Como prevenir: hook rodando na barreira de qualidade, checando que o diff não saiu do diretório do lote. Já vi gente descobrir isso só no code review, e aí são 200 arquivos pra desembaraçar 😛

Sintoma: código que funcionava com o Opus 5 quebrou

Causa: são quatro mudanças que quebram compatibilidade

• thinking não pode ser desabilitado (o pensamento adaptativo está sempre ligado no Opus 5.5)
• uso forçado de ferramenta retorna erro
• blocos de thinking ficam atrelados ao modelo e à conversa
• na Claude API e no Google Cloud, a ferramenta computer_20251124 não é aceita

Solução: revisar o código de integração antes da migração, não durante

Como prevenir: rode um lote piloto minúsculo com o modelo novo só pra validar a integração. É o mesmo princípio de subir um deploy pequeno antes do grande

Quanto custa rodar a migração inteira e como segurar a conta

Os números, todos por milhão de tokens:

A leitura desses números pro nosso caso é direta

Migração em lote é o cenário perfeito de cache: o CLAUDE.md, o inventário e as regras se repetem em TODO lote, e leitura de cache a US$ 0,20 por milhão é outra categoria de preço comparada à entrada normal

Soma isso ao effort padrão medium e você tem lote repetitivo saindo bem mais barato do que sairia mantendo tudo no esforço alto por reflexo

E quando a etapa precisa cuspir MUITO código de uma vez, existe o limite estendido de saída: até 300 mil tokens de saída com o header beta output-300k-2026-03-24, na Message Batches API

Duas notas pra fechar essa parte

A primeira: o Claude Opus 5.5 usa preserved thinking, a salvaguarda anti-destilação introduzida com o Fable 5.1, que impede usuários da API de editar o contexto anterior do Claude pra extrair o raciocínio dele. Se o seu fluxo dependia de mexer nesse contexto, ajuste antes

A segunda: Claude Sonnet 5.5 e Claude Haiku 5.5 são esperados nas próximas semanas, e aí vai valer revisitar quais lotes realmente precisam do modelo mais caro

Porque, convenhamos, renomear import com o modelo top de linha é queimar dinheiro com estilo

O resumo do método e o próximo passo

O ciclo inteiro cabe em sete palavras: mapear, escrever a regra, planejar, lotear, executar, revisar, recomeçar

O Claude Opus 5.5 entrega a parte difícil (contexto de 1 milhão de tokens, consistência em tarefa repetida, execução longa em segundo plano)

A parte que continua sendo sua é o recorte e o ponto de parada. Sem isso, você não tem migração autônoma, você tem um diff gigante que ninguém quer revisar

Próximo passo, bem concreto: escolhe o MENOR lote possível do seu repositório. Um módulo, de preferência um que ninguém importa

Roda o ciclo completo nele: inventário, regra no CLAUDE.md, plan mode, workflow, hook de teste, revisão do diff

Se o ciclo fechar limpo nesse lote minúsculo, aí sim você escala pros lotes grandes com o script já salvo

Se não fechar, você descobriu isso gastando quase nada, que é exatamente o objetivo 😉

Até o próximo post!