Vale a pena usar Claude Code num projeto legado?

Fala aí, beleza? Todo mundo posta print do Claude Code criando projeto do zero, tudo verde, tudo lindo… aí você abre aquele repositório de 2013 que paga a conta da empresa e o clima muda na hora

A pergunta de quem decide adoção no trabalho não é se a ferramenta escreve código, isso já ficou claro faz tempo

A pergunta é se ela sobrevive a um sistema que NINGUÉM entende inteiro: base grande, código antigo, quase nenhuma documentação e o único mapa real morando na cabeça de duas pessoas que talvez nem estejam mais no time

Bora separar o que ela resolve de verdade nesse cenário do que ela só parece resolver 🙂

Onde o Claude Code ajuda e onde atrapalha em projeto legado

Repara num padrão aí em cima: quase toda a coluna da direita é a MESMA restrição repetida

A janela de contexto é a limitação que sustenta praticamente todas as boas práticas em base grande, e é ela que separa o "funcionou lindo" do "começou bem e depois ficou estranho"

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

As tarefas de legado em que ele rende mais

A Anthropic tem uma página oficial de soluções de modernização de código, e ela nomeia quatro frentes

Vale ir uma por uma, porque cada uma tem um motivo pra funcionar em base sem docs e um limite bem claro de até onde dá pra confiar

Preservar a lógica de negócio:

Esse é o ponto que mais dói em legado: o código É a especificação

O if esquisito lá do meio do arquivo de 4 mil linhas não é bug, é uma regra fiscal de 2009 que alguém pediu por telefone

A proposta oficial é justamente essa, modernizar preservando a lógica de negócio em vez de reescrever "do jeito certo" e perder o comportamento

O limite: o agente consegue descrever o que o código faz, mas ele não sabe qual desses comportamentos ainda importa pro negócio hoje

Essa parte é humana, sem atalho

Mapear dependências:

Mapear dependências é foco declarado da página de modernização, e não por acaso: na metodologia de migração da Anthropic, regras e mapa de dependências são o PRIMEIRO passo dos seis

Faz sentido, né? Sem saber quem chama quem, qualquer mudança vira roleta

E aqui o desenho ajuda: em vez de você mesmo abrir 200 arquivos, o agente principal despacha subagentes de busca, cada um com sua própria janela

O limite: em base gigante o mapa vai ser parcial, e a própria Anthropic assume que a abordagem hierárquica de contexto quebra em bases com centenas de milhares de pastas e milhões de arquivos

Trate o mapa como hipótese a validar, não como planta baixa

Refatorar incrementalmente:

Refatoração incremental é o oposto do "reescreve tudo num fim de semana", e é o que a página oficial recomenda

O ganho em legado é óbvio: pedaço pequeno, verificável, reversível

O limite: incremental só é seguro se cada incremento passa por algum juiz automático

Se o módulo não tem teste nenhum, você não está refatorando, está torcendo

Gerar documentação a partir de código sem documentação:

Esse talvez seja o uso de MELHOR relação custo/benefício em legado, e é literalmente um dos focos da página oficial

Porque a doc gerada é barata de verificar: você lê, o dev que conhece aquele pedaço lê junto, e em minutos vocês sabem se bateu

A doc errada é detectável, o refactor errado nem sempre 😀

O limite continua o mesmo: humano no circuito

Documentação gerada e não revisada é pior que ausência de documentação, porque ela tem cara de oficial

O que migrações reais já mostraram em escala

Aqui dá pra sair do achismo, porque existem dois casos com números publicados

Bun, de Zig para Rust. Cerca de 1 milhão de linhas, concluído em menos de duas semanas, com cerca de US$ 165 mil de custo de API relatado e 100% da suíte de testes passando antes do merge

Python para TypeScript. 165 mil linhas de TypeScript em um fim de semana, com centenas de agentes, oito portões de fase, três rodadas de revisão adversarial e uma checagem final de paridade

Agora a leitura honesta disso, que é a parte que some dos prints de LinkedIn

O resultado não veio de confiar no modelo

Veio acompanhado de custo alto e de um processo de verificação PESADO em volta: suíte passando integralmente antes do merge num caso, oito portões e revisão adversarial em três rodadas no outro

E a metodologia publicada deixa isso explícito nos seis passos: regras e mapa de dependências, inventário de lacunas, mini-migração de estresse, tradução em paralelo com modelos menores, laços de correção por compilador e testes de fumaça, e verificação final de paridade

Os dois princípios que sobram disso são o que realmente importa pra decidir adoção:

• deixar os scripts serem o juiz (compilador, diff, suíte de testes)
• modelos menores no volume de implementação, e o modelo maior nos revisores e nas regras que os outros agentes seguem

Ou seja: a escala não veio do agente ser esperto, veio de ter como PROVAR cada pedaço automaticamente

Guarda isso, porque é exatamente o que decide se vale a pena no seu legado

Os limites que aparecem em base grande (e como contornar)

A qualidade cai no meio da sessão:

Sintoma: começa afiado, acerta os primeiros arquivos, e depois de um tempo passa a repetir coisa, esquecer decisão e entregar mudança meia-boca

Causa: a janela de contexto enchendo

O desempenho degrada conforme a janela enche, e o Claude Code compacta automaticamente ao se aproximar do limite

Solução: assumir o controle do que fica

O /compact aceita instrução, tipo /compact focus on the auth bug fix, e o /clear zera quando você troca de assunto

Como prevenir: uma sessão, um objetivo

Trocou de módulo? /clear

É o mesmo cuidado de não deixar 40 abas abertas achando que isso ajuda a focar 🙂

As instruções do outro pacote não chegam:

Sintoma: você escreveu a regra no CLAUDE.md e ele ignorou solenemente

Causa: o CLAUDE.md é hierárquico

Uma sessão iniciada dentro de packages/api carrega o packages/api/CLAUDE.md mais o da raiz, e não carrega as instruções de packages/web

Pacote sem arquivo próprio herda só o da raiz

Solução: colocar a regra no nível certo, e conferir com /memory, que lista e abre os arquivos de memória carregados na sessão

Como prevenir: regra de time e convenção vão na raiz, regra específica de pacote vai no pacote

E tome cuidado com a expectativa: em base com centenas de milhares de pastas e milhões de arquivos, a própria Anthropic diz que essa abordagem hierárquica quebra

Um arquivo gigante come a sessão inteira:

Sintoma: você pede pra ele entender um módulo, ele lê três arquivos monstruosos e a sessão já nasce velha

Causa: o conteúdo lido fica na janela principal

Solução: delegar a leitura grande a um subagente

A documentação recomenda exatamente isso, pra que o conteúdo dos arquivos fique no contexto do subagente e não no da sessão principal

Pra explorar, tem o Explore, que é somente leitura, sem as ferramentas de escrita e edição

Como prevenir: inverter o hábito

O padrão em legado não é "lê tudo e depois decide", é "manda alguém procurar e me traz o resumo"

Configuração mínima antes de julgar a ferramenta

Muita avaliação de adoção morre aqui: o time testa a ferramenta crua num monorepo, dá ruim, e a conclusão vira "não serve pra legado"

Então faz esse mínimo antes de bater o martelo

1. Ler o guia oficial de base grande. A Anthropic mantém um documento específico pra isso, o Set up Claude Code in a monorepo or large codebase. O erro comum deste passo: testar o monorepo com a mesma configuração de um projeto pequeno e culpar o modelo pelo resultado

2. Gerar o CLAUDE.md inicial. O /init cria o arquivo pra você começar:

/init

O erro comum deste passo: aceitar o gerado como está e nunca refinar, quando ele é ponto de partida

3. Conferir o que realmente carregou. O /memory lista e abre os arquivos de memória da sessão, incluindo CLAUDE.md, CLAUDE.local.md e arquivos de regras. O erro comum deste passo: assumir que escreveu, logo foi lido

4. Distribuir o CLAUDE.md por pacote. Lembra da hierarquia: sessão dentro de packages/api pega o CLAUDE.md daquele pacote mais o da raiz. O erro comum deste passo: empilhar TUDO na raiz e depois reclamar que ele mistura convenção de um pacote com a de outro

5. Entrar em modo de planejamento antes de mudança grande. O Shift+Tab cicla pro plan mode, e o comando /plan também entra no modo de planejamento. Em legado isso é o que separa "ele propôs" de "ele já mexeu", e combina bem com o Extended Thinking do Claude Code quando a decisão é arquitetural. O erro comum deste passo: mandar refatorar direto e revisar um diff enorme depois

6. Delegar busca e leitura a subagente. Cada subagente opera na própria janela de contexto, e o Explore é somente leitura. O erro comum deste passo: pedir exploração na sessão principal e queimar a janela antes de escrever a primeira linha

7. Habilitar a janela de 1M se o plano permite. No Claude Code com Pro, Max, Team ou Enterprise, os modelos Sonnet 5, Fable 5, Opus 5, Opus 4.8, Opus 4.7 e Opus 4.6 suportam 1M de tokens, e no Pro é preciso habilitar créditos de uso. O erro comum deste passo: contar com a janela maior no Pro sem habilitar os créditos de uso

8. Só pra reescrita de stack, instalar o plugin oficial. O plugin de modernização de código é mantido pela Anthropic e instala por comando dentro do próprio Claude Code:

/plugin install code-modernization@claude-plugins-official

Ele assume convenção de pastas: código legado em legacy/<system-dir>/, artefatos de análise em analysis/<system-dir>/ e código novo em modernized/<system-dir>/

Se o seu código mora em outro lugar (e em legado ele SEMPRE mora), a saída é symlink:

mkdir -p legacy && ln -s /caminho/do/codigo legacy/billing

E tem checagem inicial do ambiente antes de sair migrando:

/modernize-preflight billing

São três métodos de reconstrução: transform (reescrita entre stacks, tipo COBOL para Java), reimagine (reconstrução em nova arquitetura) e uplift (mesma stack, salto de versão, tipo .NET Framework para .NET 8)

O erro comum deste passo: apontar o plugin pro código onde ele está e ignorar a convenção de pastas, aí os artefatos de análise se misturam com o código novo

9. Passar a revisão de segurança nas mudanças. O /security-review revisa as mudanças pendentes, e dá pra customizar copiando o security-review.md pra pasta .claude/commands/ do projeto. O erro comum deste passo: esperar que ele audite a base legada inteira, quando o escopo é o pendente

Veredito: para quem decide adoção no trabalho

O divisor de águas não é o tamanho da base, nem a idade do código, nem a stack

É se existe alguma coisa capaz de JULGAR o resultado sem você

Compilador, suíte de testes, diff limpo

O princípio da metodologia de migração é esse: deixar os scripts serem o juiz, com modelos menores no volume de implementação e o modelo maior nas regras e nos revisores

Quando isso existe, o legado vira terreno bom: você entrega volume de trabalho chato e o juiz automático segura a onda

Ajuda muito, aqui, saber trabalhar em pedaços pequenos e revisar commits e diffs pelo Git, porque é o que transforma "ele mexeu em 60 arquivos" em algo revisável

Quando NÃO existe juiz nenhum, muda de figura

Base sem teste, sem tipagem, sem ambiente pra rodar, deploy manual e ninguém que saiba dizer se o comportamento continua o mesmo? Aí a ferramenta produz mudança rápido e você não tem como verificar rápido

Isso não é ganho, é dívida acelerada

E dois avisos de honestidade, porque não vou inventar número pra te convencer:

• não existe percentual público e auditável de ganho de produtividade em legado, então quem te promete "X% mais rápido" está chutando
• os casos grandes que existem vieram com custo de API relatado na casa das dezenas de milhares de dólares e processo de verificação pesado em volta

Pra quem decide adoção, a leitura prática é essa: se o seu legado ainda não tem como provar nada automaticamente, o primeiro investimento não é a ferramenta, é o juiz

Um teste de fumaça que roda, um caminho de build que fecha, um diff que alguém entende

Depois disso, a conversa muda completamente

Conclusão

Claude Code em projeto legado não é bala de prata nem enrolação: é uma ferramenta cujo rendimento depende do quanto você consegue verificar o que ela produz

Ele rende bem em entender, mapear e documentar, que é justamente a parte barata de conferir

E fica arriscado em reescrever no escuro, que é justamente a parte cara de conferir

O próximo passo mais barato que você pode dar hoje não envolve migração nenhuma

Escolhe UM módulo isolado do legado, roda /init ali, entra em plan mode antes de qualquer mudança e pede a documentação daquele pedaço

Depois senta com quem conhece o módulo e compara com o que o time já sabe

Se bateu, você tem sinal verde pra escalar devagar

Se veio bonito mas errado, você descobriu isso por um custo ridículo, em vez de descobrir no meio de uma migração

É o tipo de teste que responde a pergunta de adoção em uma tarde, sem reunião nenhuma 😀

até o próximo post!