Refatorar legado sem estourar contexto: guia prático 2026

A sessão estava indo bem. Três horas de contexto, 60 arquivos no escopo, o agente entendendo a arquitetura de um CRM legado em Django 2.1 e indo linha a linha identificando o que precisava mudar para a migração para FastAPI. Então o cap de contexto apareceu. O agente começou a perder referência a módulos que havia analisado minutos antes. O que era uma refatoração cirúrgica virou um pesadelo de alucinações e retrabalho.

Se você já viveu isso — e em 2026 quase todo dev que usa agentes de IA já viveu — sabe que o problema não é inteligência do modelo, e sim gestão de contexto. Este guia prático reúne as lições que aprendi (e que a comunidade tem validado) para refatorar sistemas legados com agentes autônomos sem explodir a janela de contexto. Vamos falar de planejamento, hooks, estados retomáveis e daquela velha máxima: menos escopo, mais entrega.

O problema não é o código, é o contexto

Janelas de contexto cresceram muito, mas o código legado também. Sistemas Django 2.1, monolitos em .NET Framework, CRUDs com 15 anos de regra de negócio escondida... O que um agente precisa "ver" para refatorar com segurança é desproporcional ao que cabe na conversa.

Quando o contexto estoura, acontece o fenômeno que apelidei de amnésia progressiva: o agente começa a repetir perguntas, sugerir mudanças baseadas em arquivos que já não existem e, pior, "inventar" APIs que nunca leu. Não é má vontade — é limite físico da atenção contínua.

A primeira regra, então, é aceitar: você não vai refatorar um sistema inteiro numa única sessão. E não deve. O objetivo é terminar a sessão com o contexto intacto, não com 100% do código migrado.

Estratégia 1: Fatie o escopo como um cirurgião

No exemplo do CRM, o agente tinha 60 arquivos no escopo. Isso é receita para desastre. A alternativa é dividir a refatoração em fatias verticais pequenas:

• Por módulo de negócio: em vez de "migrar tudo", "migrar o fluxo de checkout" primeiro.
• Por camada: primeiro os models, depois os endpoints, depois os serviços — cada um em uma sessão separada.
• Por dependência: identifique módulos que ninguém importa (código morto é o melhor amigo do refatorador) e remova-os antes de tocar no resto.

Cada fatia deve caber na janela de contexto com folga. Se você perceber que o agente está empurrando o limite, corte a fatia no meio. Prefira 10 sessões de 20 minutos a uma de 4 horas que morre no final.

Estratégia 2: Roadmap executável, não prompt gigante

Uma das ferramentas mais interessantes que apareceu recentemente é o Katana — um sistema de desenvolvimento autônomo para Claude Code que propõe uma abordagem diferente: em vez de uma única instrução gigante, ele trabalha com um roadmap executável. O agente não recebe tudo de uma vez; ele recebe um plano com objetivos pequenos, cada um com critérios de aceite claros.

O Katana traz comandos como /plan, /goal e /fix, que separam o momento de pensar do momento de agir. Isso é ouro para refatoração. Em vez de dizer ao agente "migre esse CRM Django para FastAPI", você quebra isso em um roadmap:

1. Mapear dependências atuais (fetch e dump em arquivo)
2. Criar estrutura FastAPI com mesmos endpoints, sem tocar em regras
3. Migrar models ORM com scripts de dados
4. Rodar testes de paridade, módulo a módulo
5. Ligar o breakpoint final e revisar a migração

Com um roadmap, o agente não precisa carregar o sistema inteiro na cabeça o tempo todo. Ele foca apenas no passo atual. E, se o contexto estourar, você retoma do roadmap — não do zero.

Estratégia 3: Hooks para não desperdiçar tokens

Existe um tipo de trabalho que devora contexto sem gerar valor: rodar testes, formatar código, verificar lint. Se você usa um agente como o Claude Code, cada comando que você dá manualmente ocupa atenção e tokens preciosos.

A solução é usar hooks — scripts que o agente executa automaticamente em resposta a eventos. Por exemplo:

• Depois que o agente edita um arquivo, um hook roda dotnet format e aplica as convenções do projeto.
• Antes de um commit, um hook roda os testes da solução e aborta se quebrar.
• Depois de cada modificação, um hook registra em um arquivo CHANGELOG.md o que mudou.

Isso não é só conveniência: é uma forma de coleira mecânica — o termo que o Katana usa para os hooks que mantêm o agente dentro dos trilhos. Sem isso, você gasta contexto corrigindo o agente que esqueceu de rodar o teste. Com isso, o agente produz, e você só revisa o resumo.

Estratégia 4: Estado retomável e self-review real

Outra grande sacada do Katana é o estado retomável. Em vez de uma única sessão monolítica, o sistema guarda o progresso em disco — arquivos, decisões, branches — e permite que você retome de onde parou. Isso é crucial para refatoração longa. O agente pode trabalhar em modo overnight, gerar um branch com as mudanças, fazer self-review e até abrir um PR. Você acorda, revisa e aprova.

Mas atenção: self-review de agente não substitui revisão humana. A ideia do PR com self-review é que o agente verifique as próprias mudanças de forma automatizada (testes, lint, análise estática) antes de incomodar você. Isso reduz o ciclo de feedback e evita que você gaste seu contexto mental com erros bobos.

Na prática, para refatorar legado:

• Cada fatia vira uma branch com um PR pequeno.
• O agente roda os testes automaticamente e anexa evidência no PR.
• Você revisa a lógica, não o estilo — porque o estilo o hook já cuidou.

Colocando tudo em prática: um fluxo que funciona

Com base no que vimos, aqui está um fluxo de refatoração que tenho usado e que respeita o contexto do agente e o seu:

1. Diagnóstico em uma sessão dedicada: peça ao agente apenas para mapear o sistema e gerar um relatório de dependências. Salve o relatório em arquivo.
2. Criar o roadmap: com base no relatório, defina as fatias e os critérios de aceite. Não comece a codar.
3. Configurar hooks: antes de começar, automatize formatação, testes e changelog. Assim você elimina 30% do ruído.
4. Uma fatia por sessão: rode uma fatia do roadmap, com branch própria. Garanta que o agente termine antes de estourar o contexto.
5. Self-review e PR: o agente abre o PR, roda os hooks e anexa evidência. Você revisa em blocos de 10 minutos.
6. Retome o roadmap: se o contexto ainda estiver confortável, continue para a próxima fatia. Se não, pare. O roadmap está salvo.

O que evitar a todo custo

Alguns erros que vi acontecerem repetidamente (e cometi):

• Colocar 10 instruções no mesmo prompt: "Analise, migre, refatore, teste, documente e faça deploy". O agente vai fazer a primeira, esquecer a quinta e alucinar a sexta.
• Não usar o sistema de arquivos como memória externa: salve relatórios, decisões e TODOs em Markdown. O contexto do agente é volátil; o arquivo não.
• Ignorar os hooks: se você trabalha com .NET, Python ou qualquer ecossistema com CLI, o agente pode rodar tudo automaticamente. Fazer isso manualmente é jogar contexto fora.
• Deixar o agente abrir PR gigante: PR com 5 mil linhas é impossível de revisar — seja humano ou máquina.

Conclusão: a sabedoria da restrição

Refatorar legado sem estourar contexto é, no fundo, um exercício de design de restrições. Não é sobre ter mais tokens — é sobre gastar melhor os que você tem. Fatiar o escopo, usar roadmap executável, delegar tarefas chatas para hooks e manter um estado retomável. Essas práticas transformam uma sessão caótica em um processo incremental e seguro.

O agente é uma ferramenta poderosa, mas a orquestração ainda é sua. O contexto é o novo recurso escasso, e quem souber gerenciá-lo vai entregar refatorações ambiciosas sem sangue frio no final. Em 2026, o dev que domina isso não é substituído por IA — ele vira o maestro da orquestra.

E quando a próxima sessão de 3 horas começar, você saberá a hora certa de parar, salvar o roadmap e tomar um café. O resto o hook faz.