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 no início. Na sétima hora, sugeria mudanças que contradiziam as que tinha feito três horas antes.
Isso não é falha do agente. É o que acontece quando você pede a qualquer modelo que mantenha coerência por mais contexto do que ele tem janela para processar.
O problema de refatoração de código legado com agente de programação tem uma solução técnica, mas ela depende de duas coisas que a maioria dos setups não tem: janela de contexto grande o suficiente e uma estratégia de sessão que não vai contra a física do modelo.
Por que o agente perde contexto no meio do monolito?
Cada modelo tem uma janela de contexto: o máximo de tokens que ele processa em uma única requisição. A janela não é um buffer acumulativo. Ela é o que o modelo "vê" naquele momento específico.
O problema de refatoração de legado tem três camadas que se somam:
- O código em si: um monolito de 50k linhas em Python ocupa aproximadamente 500k tokens quando você inclui o conteúdo completo dos arquivos relevantes.
- O histórico da sessão: cada ida e volta com o agente adiciona tokens ao contexto. Depois de 2 horas de sessão intensa, o histórico pode adicionar 100k tokens extras.
- As instruções e contexto de tarefa: PRD, especificações da nova API, regras de migração, mais 20k a 50k tokens.
Some esses três componentes e você chega facilmente em 700k a 800k tokens necessários para uma sessão de refactor séria. Modelos com janela de 200k tokens saturam. Quando a janela satura, os tokens mais antigos, onde estava a arquitetura original, são descartados para dar espaço ao contexto recente.
É isso que você sente como "o agente perdeu o fio da meada". Ele não perdeu: ele literalmente não pode mais ler o que leu no início da sessão.
| Componente de contexto | Tokens estimados |
|---|---|
| 50k linhas de código legado (60% dos arquivos relevantes) | ~500.000 |
| Histórico de sessão de 4 horas de refactor | ~150.000 |
| Especificações, PRD, regras de migração | ~30.000 |
| Total necessário para sessão completa | ~680.000 |
| Janela de 200k (Claude Code, Cursor c/ Claude) | Cap estourado em 30% da sessão |
| Janela de 1M (deepseek-v4-flash, mimo-v2.5) | Sessão completa sem saturação |
1M de tokens resolve o problema de contexto?
Parcialmente. Janela maior elimina a saturação forçada, mas não elimina o problema de qualidade de atenção em contextos muito longos.
Avaliações publicadas no SWEN.AI e no Artificial Analysis em 2026 mostram que a atenção dos modelos é melhor nos primeiros e últimos segmentos do contexto, com degradação no intervalo intermediário. Para sessões de 800k tokens, informação na faixa dos 200k-600k recebe menos atenção do que informação no início ou no final da janela.
O que isso significa para a estratégia de refator: não adianta jogar todo o código no contexto e esperar processamento uniforme. Você precisa de uma estratégia que coloque a informação crítica na posição certa da janela.
A boa notícia: com 1M de contexto disponível, você tem espaço para aplicar essa estratégia sem precisar truncar o código. Com 200k, você nem chega a ter essa opção.
Como estruturar a sessão de refactor para não perder contexto?
O framework abaixo foi desenhado para sessões de refatoração de monolito usando deepseek-v4-flash ou mimo-v2.5, ambos disponíveis no Verboo Code com janela de 1M de tokens. A lógica funciona com qualquer agente de programação que tenha contexto suficiente.
Passo 1: Mapa antes do código
Antes de colocar o código no contexto, peça ao agente para gerar um mapa da arquitetura baseado nos arquivos de estrutura, sem o conteúdo completo. tree, pyproject.toml, requirements.txt e os arquivos de configuração já dão uma visão da estrutura sem saturar o contexto.
# Primeiro prompt: mapa sem código completo
$ verboo
[verboo]: Analise a estrutura do projeto a partir dos arquivos abaixo
e gere um mapa de dependências entre módulos antes de lermos o código completo.
[inclua: tree, pyproject.toml, setup.cfg, __init__.py dos módulos principais]
O agente gera o mapa. Você salva esse mapa como um arquivo separado. Ele vai entrar no início de cada sub-sessão como âncora de contexto.
Passo 2: Plano de migração com ordem definida
Refatoração de legado tem dependências. O módulo de autenticação precisa ser migrado antes do de permissões. O ORM precisa ser desacoplado antes de migrar as rotas. Você define a ordem de migração antes de começar, não no meio.
Um arquivo MIGRATION_PLAN.md simples já resolve:
# MIGRATION_PLAN.md
## Ordem de migração
1. Configuração e dependências (settings, requirements)
2. Modelos e ORM (desacoplar SQLAlchemy do Django ORM)
3. Autenticação (session-based para JWT)
4. Rotas (views Django para FastAPI endpoints)
5. Testes (unittest para pytest com httpx)
## Regras de migração
- Manter compatibilidade de schema do banco durante toda a migração
- Não alterar interfaces externas até a etapa 4
- Cada módulo migrado recebe teste de fumaça antes de ir para o próximo
Esse arquivo entra no contexto de cada sub-sessão. O agente sempre sabe onde está no plano.
Passo 3: Uma sub-sessão por módulo com reset de histórico
Este é o ponto que vai contra o instinto de muitos devs. Sessão longa, contexto enorme, o agente vai "lembrar" tudo. Na prática, o histórico de sessão é um dos maiores consumidores de contexto, e não é mais valioso do que o código novo.
A estratégia: uma sessão por módulo, com o contexto sempre composto por:
- O mapa de arquitetura (âncora)
- O plano de migração com o módulo atual marcado
- O código completo do módulo atual
- Os testes existentes do módulo
- O estado final do módulo anterior (não o histórico de como chegou lá)
O histórico de sessão anterior não entra. Você não precisa que o agente lembre como chegou ao resultado do módulo anterior. Precisa que ele veja o resultado e saiba onde está no plano.
Passo 4: Modelo certo para cada tipo de tarefa
No Verboo Code, você alterna entre modelos com o comando /model dentro da sessão. Para refatoração de legado, a escolha importa:
| Modelo | Contexto | Melhor para |
|---|---|---|
mimo-v2.5 |
1M tokens | Análise de arquitetura complexa, refatoração com múltiplas dependências, raciocínio multi-step |
deepseek-v4-flash |
1M tokens | Iterações rápidas, geração de testes, conversão de sintaxe, respostas mais velozes |
qwen3.6-27b |
262k tokens | Debugging pontual, análise de lógica específica, revisão de PRs de módulos já migrados |
Use mimo-v2.5 para a análise inicial do módulo e para decisões arquiteturais. Use deepseek-v4-flash para as iterações de implementação, onde a velocidade de resposta importa mais do que profundidade de raciocínio.
Passo 5: Checkpoint de coerência a cada módulo
Antes de iniciar o próximo módulo, rode um checkpoint: peça ao agente para listar as mudanças feitas no módulo atual e verificar se estão consistentes com as regras do plano de migração.
[verboo]: Liste todas as mudanças que fizemos no módulo de autenticação
nessa sessão e verifique se cada uma está alinhada com as regras do
MIGRATION_PLAN.md, especialmente as regras de compatibilidade de schema.
Esse prompt custa alguns tokens e retorna inconsistências que vão ser muito mais caras de corrigir depois de 3 módulos na frente.
Qual modelo escolher para refatoração de código legado em 2026?
Para projetos com mais de 100k linhas, a janela de 1M tokens não é opcional: é o requisito mínimo para que o agente tenha coerência ao longo de toda a análise inicial. mimo-v2.5 e deepseek-v4-flash são as únicas opções open source nessa faixa com uso real em produção documentado em 2026.
Para projetos menores (20k a 50k linhas), qwen3.6-27b com 262k de contexto é suficiente para a maioria dos módulos, com latência menor por resposta.
O que não funciona para refatoração de legado:
- Modelos com cap de 200k tokens em projetos de médio porte: saturação na metade da sessão
- Qualquer modelo com billing por token quando você precisa de iteração intensa: custo real por sessão explode
- Sessões sem âncora de contexto (mapa + plano): o agente perde coerência ao longo do tempo mesmo com janela grande
Como saber quando o agente está perdendo contexto?
Três sinais práticos que indicam saturação da janela:
- Contradições com decisões anteriores da sessão: o agente sugere algo que você já discutiu e descartou. Não porque mudou de ideia, mas porque não está mais "vendo" aquela parte da conversa.
- Respostas genéricas onde antes eram específicas: o agente começa a responder com padrões gerais em vez de referenciar o código específico do projeto. Sinal de que o código foi descartado do contexto ativo.
- Tempo de resposta aumentando sem complexidade crescendo: o modelo está processando uma janela mais cheia, não uma tarefa mais difícil.
Quando ver qualquer um desses sinais, encerre a sessão atual e inicie uma nova com o contexto estruturado: mapa mais plano mais estado atual do módulo. Não continue tentando na mesma sessão saturada.
Resumo executivo: a estratégia em 5 pontos
| Etapa | O que fazer | Por que importa |
|---|---|---|
| 1. Mapa | Gerar mapa de arquitetura antes do código completo | Âncora de contexto que entra em toda sessão |
| 2. Plano | Definir ordem de migração e regras antes de começar | Agente sempre sabe onde está e o que não pode quebrar |
| 3. Sub-sessões | Uma sessão por módulo com reset de histórico | Elimina acúmulo de contexto irrelevante |
| 4. Modelo certo | mimo-v2.5 para análise, deepseek-v4-flash para iteração | 1M de contexto em ambos, escolha por velocidade vs profundidade |
| 5. Checkpoint | Verificar coerência com o plano a cada módulo concluído | Previne inconsistências antes de ficarem caras |
O custo de depurar inconsistências introduzidas por agente sem contexto é frequentemente maior do que o custo de refatorar na mão. A estratégia de sub-sessões estruturadas com âncora de contexto resolve o problema na raiz, não nos sintomas.
Para entender por que o cap de 5 horas do Claude Code impacta exatamente esse tipo de tarefa, veja a conta real do "ilimitado" em Claude Code, Cursor e Copilot. E para o comparativo completo de coding agents e janelas de contexto em 2026, os dados estão em tokens ilimitados ou pagar por token.
Quer rodar isso sem cap de tokens? Conheça o Verboo Code, agente de programação com tokens ilimitados.
