Modernizar legado é preservar conhecimento, não copiar telas

Uma tela aparentemente simples pode combinar permissões, estados intermediários, arredondamentos, consultas, efeitos fiscais e atalhos operacionais. Cada detalhe isolado parece pequeno; juntos, eles formam o contrato real que os usuários conhecem.

Por isso, começar pela arquitetura futura sem mapear o comportamento atual cria uma lacuna perigosa. A equipe passa a discutir como o novo sistema deveria funcionar antes de compreender por que o atual funciona daquela maneira.

Comparar uma solução nova com um legado que continua mudando é comparar dois alvos móveis. O primeiro passo é fixar uma versão de referência e registrar o recorte que será convertido: entradas, saídas, estados, permissões, consultas e integrações.

Essa baseline não precisa documentar o sistema inteiro. Ela precisa ser específica o suficiente para responder o que pertence à entrega atual e o que continua fora dela. O limite reduz ruído e impede que diferenças legítimas sejam confundidas com regressões.

Separar frontend, API e persistência em grandes projetos paralelos parece eficiente, mas adia a única pergunta que importa: o fluxo funciona de ponta a ponta? Uma interface sem regra real ou uma API sem uso concreto produz progresso difícil de validar.

Prefiro recortes verticais pequenos. Um fluxo atravessa interface, contrato, regra, dados e validação antes que o próximo comece. O resultado aparece mais cedo e cada entrega gera aprendizado aplicável à seguinte.

Paridade não significa copiar cada detalhe visual. Significa demonstrar que entradas relevantes produzem estados e resultados compatíveis, salvo quando uma mudança de comportamento foi decidida de forma explícita.

Testes ajudam, mas não substituem a referência. A comparação precisa combinar cenários automatizados, dados representativos e navegação real. Quando existe diferença, ela deve ser classificada como regressão, correção intencional ou decisão de produto — nunca tratada como impressão.

Em sistemas que não podem parar, legado e nova solução convivem por algum tempo. Tratar essa convivência como improviso cria duplicidade de estado, caminhos ocultos e suporte confuso. Tratá-la como requisito permite definir claramente quem lê, quem grava e qual sistema responde por cada fluxo.

A substituição acontece quando o recorte novo acumula evidência suficiente, não quando o calendário pede uma grande virada. Isso preserva opções de recuperação e mantém o risco proporcional ao tamanho da entrega.

Build, testes, deploy e operação saudável são provas diferentes. Um artefato pode compilar e não ser o que está atendendo usuários; um serviço pode iniciar e falhar na primeira integração real.

A validação final precisa conectar a revisão entregue à versão ativa, exercitar o fluxo no ambiente publicado e observar sinais coerentes de saúde. Essa disciplina fecha a distância entre código aprovado e resultado operacional.