Refatorar legado sem estourar contexto: guia prático 2026

Por Mafra — 29/06/2026

Era uma tarde comum em uma squad de plataforma. Três horas de sessão contínua com um agente de IA, 60 arquivos no escopo, o contexto parecia sólido. O agente navegava por um CRM legado em Django 2.1, identificando ponto a ponto o que precisaria ser alterado para a migração para FastAPI. A arquitetura estava clara, os módulos estavam mapeados, e a confiança no processo era total. Então, veio o cap.

O agente começou a perder referências a módulos que ele mesmo havia analisado no início da sessão. Nomes de classes que apareciam nos primeiros arquivos voltavam como se fossem novos. A solução para um bug de ForeignKey foi proposta duas vezes. Na sétima hora, o contexto estourou de vez, e o que era uma sessão cirúrgica virou uma conversa de agente amnésico. Esse cenário, infelizmente, não é exceção. É a realidade de quem tenta usar IA para refatorar sistemas legados sem uma metodologia firme.

Neste guia prático de 2026, vamos explorar como evitar esse desperdício de tempo e tokens, combinando boas práticas clássicas de engenharia com as ferramentas mais atuais de desenvolvimento autônomo, como o Claude Code e o recém-lançado Katana.

O problema: por que o contexto estoura, afinal?

Modelos de linguagem usam uma janela de contexto limitada — mesmo as versões mais avançadas de 2026. Na prática, isso significa que, em uma longa sessão de refatoração, o agente precisa "esquecer" informações antigas para abrir espaço para as novas. E isso não acontece de forma inteligente: ele não prioriza o que é mais importante. Ele simplesmente descarta.

No caso da refatoração de código legado, o problema é ainda maior. Sistemas antigos têm:

• Dependências obscuras: a função que ninguém sabe quem chama;
• Código duplicado: alterar um trecho sem perceber que ele foi copiado em outros três lugares;
• Falta de testes:: qualquer mudança pode quebrar algo invisível;
• Dívida técnica de anos: padrões de projeto abandonados misturados com novas implementações.

Para um agente de IA, mapear tudo isso de uma só vez é um inferno de contexto. A cada nova descoberta, ele precisa manter na memória toda a árvore de dependências, todos os nomes de variáveis, todas as regras de negócio. Eventualmente, algo se perde.

Estratégia 1: nunca refatore o sistema inteiro de uma vez

O maior erro que você pode cometer é dar ao agente um objetivo gigante: "Migre o sistema inteiro para FastAPI." Ou, pior ainda, "Refatore todo o legado para Laravel."

O princípio é o mesmo da cirurgia: você não opera o corpo inteiro de uma vez. Você opera um órgão, ou um sistema, enquanto mantém o resto vivo.

A abordagem recomendada é refatoração incremental por módulo:

1. Crie uma branch dedicada para a refatoração. Isso garante que o trabalho do agente fique isolado e possa ser descartado sem críticas.
2. Comece por um módulo de borda — algo que não esteja no coração do domínio, como uma camada de exportação de relatórios ou um adaptador de API externa.
3. Defina o contrato: antes de mexer, escreva os testes de caracterização que garantem o comportamento atual do módulo.
4. Alimente o agente apenas com esse módulo: envie o caminho do diretório, os testes e o padrão arquitetural desejado. Nada mais.
5. Rode os testes a cada mudança. Se quebrar, o agente corrige na hora, antes de avançar.

Um caso real documentado em um tutorial de novembro de 2025 mostrou essa técnica em ação: um desenvolvedor migrou um sistema de 8 anos de PHP puro para Laravel em 3 semanas com Claude Code, contra uma estimativa de 6 meses de trabalho manual. O segredo? Ele mesmo escreveu: "A chave foi fazer um módulo por vez, com testes rodando continuamente."

Estratégia 2: mapeie dependências antes de tocar no código

Você não quer que o agente descubra a arquitetura enquanto refatora. Isso é ansiedade pura. O processo correto é:

• Faça um mapeamento preliminar das dependências do módulo: o que ele importa, o que ele exporta, quais tabelas ele usa, quais endpoints chamam ele.
• Gere um diagrama (mesmo que em texto) e envie isso ao agente como contexto inicial.
• Instrua o agente a não explorar além dos limites do módulo durante a refatoração. Se ele precisar de informação sobre outra parte do sistema, ele deve perguntar — não sair em busca própria, gastando contexto.

Isso cria uma "coleira mecânica" para o agente, um termo que usamos aqui na Verboo para descrever restrições artificiais que impedem o comportamento destrutivo.

Estratégia 3: use ferramentas de estado retomável e modo overnight

O que acontece quando, mesmo com tudo planejado, o contexto estoura no meio de uma tarefa de 4 horas? Você perde todo o progresso? Em 2025, sim. Em 2026, não.

Ferramentas como o Katana — um sistema de desenvolvimento autônomo para Claude Code — resolveram esse problema com uma arquitetura de estado retomável.

O Katana opera com:

• Runs com branch/PR/self-review/merge reais: o agente não apenas edita código; ele cria branch, implementa, revisa o próprio trabalho, abre um PR e, se os testes passarem, faz o merge.
• Roadmap executável: você define um plano de refatoração, e o Katana o executa passo a passo, persistindo o progresso na branch após cada etapa.
• Hooks que funcionam como coleira mecânica: regras de negócio que impedem o agente de pular etapas ou de refatorar fora do escopo.
• Modo overnight: você inicia a refatoração à noite, com um conjunto de módulos mapeados, e o sistema trabalha de forma autônoma, salvando o estado a cada checkpoint.

Se o contexto estourar (ou a API falhar), o sistema simplesmente retoma do último estado salvo. Nada de re-analisar o que já foi analisado. O contexto é tratado como um recurso escasso, e o estado como um artefato persistente.

O Katana, em particular, é fruto de uma linhagem de projetos que começou com solodev, passou pelo Crucible e chegou ao Forger. Ou seja: é a terceira iteração de algo que foi lapidado com sofrimento real, em projetos reais de sistemas legados.

Estratégia 4: nem todo código precisa ser tocado

Refatorar legado sem estourar contexto também é saber priorizar. O agente não deve gastar tokens e contexto com:

• Trechos de código morto (morto = ninguém chama, não tem teste, não está na stack atual);
• Formatação ou estilo que pode ser resolvido por automatizadores como o black ou prettier (rode-os ao final no modo bulk);
• Ajustes de variáveis de ambiente que não possuem impacto no comportamento do módulo.

Defina uma lista de "não tocar" antes de iniciar o agente. Isso reduz drasticamente o ruído e mantém o contexto focado no que importa.

Exemplo prático: migração Django para FastAPI com contexto controlado

Vamos aplicar tudo isso em um cenário concreto, com o CRM legado no Django 2.1 (não suportado mais, servindo apenas de cobaia).

Fase 1 – Preparação (fora da sessão do agente)

• Criar branch refactor/crm-to-fastapi.
• Mapear os módulos do sistema: deltas, contratos, clientes.
• Escolher o primeiro módulo: contratos (por ser o mais simples e isolado).
• Escrever testes de caracterização para os endpoints atuais (pytest + django-test-client).

Fase 2 – Sessão 1: Contexto mínimo

• Prompt inicial:
• "Você está migrando o módulo de contratos de Django para FastAPI. O comportamento atual está descrito nos testes na pasta tests/contratos. O contrato da API deve ser exatamente o mesmo. Não analise outros módulos. Se encontrar dependências fora de contratos/, liste-as em um arquivo DEPENDENCIAS.md e não siga."
• Resultado em 1h30: FastAPI funcional para contratos, testes passando, PR aberto.

Fase 3 – Checkpoint entre módulos

• O agente salva o estado, encerra a run, e você revisa o PR.
• Atualiza o roadmap: contratos concluído, próximo: clientes.

Fase 4 – Sessão 2: Contexto com histórico compacto

• Prompt inicial:
• "Resumo do progresso: contratos migrado. Agora faça o módulo clientes. Use o padrão estabelecido no módulo contratos (ver contratos/api.py como referência). Não explore além de clientes/."
• O agente dessa vez já sabe o padrão. Não precisa re-explicar a arquitetura.

Perceba que o contexto inicial de cada sessão é uma combinação do roadmap (pequeno), do padrão de referência (um arquivo), e dos testes (o contrato). Nada mais.

O papel do auto-review e dos testes contínuos

Uma das maiores vantagens de ferramentas como Claude Code e Katana de 2026 é o self-review. Depois de gerar o código, o agente mesmo revisa, identifica problemas de padrão, testa e redige um resumo das mudanças para o PR.

Isso é crucial porque uma das maiores fontes de estouro de contexto é a correção manual interminável. Se o agente vê um bug no próprio código, ele corrige ali mesmo, com o contexto quente. Se isso é feito automaticamente por um runner, o custo de token é menor do que se você, desenvolvedor humano, precisasse ler o diff e apontar o problema manualmente.

No Katana, esse ciclo é:

1. Run com testes;
2. Se falhar, o agente lê o erro, corrige e roda de novo;
3. Após N passagens verdes, ele faz self-review e reescreve partes que considere desnecessárias ou confusas;
4. Abre o PR;
5. Merge automático se todos os checks passarem.

Conclusão: refatorar legado é mais sobre controle do que sobre poder

O que aprendemos em 2026 é que a IA é absurdamente poderosa, mas esse poder precisa de estrutura. Sem boas práticas — branch dedicada, módulo por módulo, mapeamento prévio, testes de caracterização, estado retomável — o agente se perde, o contexto estoura, e o que era para ser um avanço vira uma noite de frustração.

A boa notícia: as ferramentas evoluíram muito. O Katana trouxe a coleira mecânica e o modo overnight, que transformam a refatoração de legado em um processo quase industrial. O Claude Code se tornou mais robusto para sessões longas.

Mas nada disso substitui a disciplina de engenharia. O agente é um cirurgião incrivelmente rápido e preciso, mas você ainda é o responsável pela operação. Desenhe o plano, defina os limites, acompanhe os checkpoints. Se você fizer isso, aquele CRM de 2019 pode virar FastAPI em semanas, não anos.

E o mais importante: mantenha o contexto como o bem mais precioso da sua sessão. Ele é o combustível. Use com sabedoria.

Quer aprofundar? No blog da Verboo, você encontra mais conteúdo sobre migração de sistemas e engenharia de plataforma. Em projetos práticos, vale experimentar o Katana em um repo pequeno e ir aumentando a complexidade. A curva de aprendizado é curta, e o retorno é imenso.

Bom deploy.