Altere um sistema existente com segurança

Identifique os contratos em torno da alteração

Software existente tem componentes que o chamam, dados armazenados, jobs agendados e procedimentos operacionais. Algumas dependências não aparecem no arquivo que você quer editar. Um agente pode produzir uma alteração localmente correta que quebra um desses contratos.

Antes de implementar, identifique quem lê e quem escreve os dados afetados. Inspecione rotas, jobs em segundo plano, relatórios e integrações externas. Verifique se outras equipes ou versões antigas de clientes dependem do comportamento atual.

Peça ao agente que mostre as evidências desse mapa. Um resultado de busca é um ponto de partida útil, mas chamadas dinâmicas e sistemas consumidores externos podem exigir a confirmação de um responsável.

Torne o comportamento atual observável

Para um módulo mal documentado, acrescente verificações focadas nos comportamentos que precisam permanecer estáveis. Essas verificações descrevem o contrato atual. Não comprovam que todo comportamento existente seja desejável.

Se o comportamento atual contrariar um requisito, registre o conflito. Não preserve um defeito de segurança apenas porque um teste o registrou. Obtenha a decisão necessária para distinguir o comportamento pretendido de um defeito.

Use fixtures realistas e sem dados sensíveis. Inclua formatos antigos de dados e registros incompletos quando puderem ocorrer. Um novo schema testado apenas com dados recém-criados pode ocultar problemas de migração.

Revise a transição entre versões

Considere uma renomeação fictícia de customer_name para display_name. A renomeação imediata pode quebrar uma instância antiga da aplicação durante o deployment. Atualizar os dois arquivos em um pull request não torna o deployment atômico.

Uma abordagem gradual pode preservar a compatibilidade:

1. Adicione o novo campo sem remover o antigo.
2. Defina como novas escritas mantêm os valores necessários consistentes.
3. Preencha o novo campo nos registros existentes com um processo que possa ser retomado.
4. Verifique a completude e o comportamento dos componentes que leem os dados.
5. Migre esses componentes para o novo campo.
6. Remova o campo antigo somente quando não houver mais componentes que o utilizem.

O método exato depende do banco de dados e dos padrões de escrita. Escritas duplas podem gerar inconsistência se uma delas falhar. Uma transação no banco de dados ou outro método explícito de sincronização pode ser necessário. Não aplique esse exemplo sem verificar as garantias do sistema.

Martin Fowler descreve essa transição geral como alteração paralela, também chamada de expansão e contração. A ideia principal é fazer uma transição compatível antes da remoção.

Planeje a recuperação separadamente do rollback

O rollback de código restaura uma versão anterior da aplicação. Ele não desfaz automaticamente uma migração de dados. A versão antiga pode não entender os novos dados. Uma migração destrutiva pode remover informações que um rollback de código não consegue recuperar.

Identifique a ação de recuperação de cada etapa. Um preenchimento retroativo retomável pode ser seguro de continuar. Uma transformação errada pode exigir uma correção a partir de dados de origem preservados. Uma operação destrutiva pode exigir um procedimento de restauração verificado.

Pergunte quem é responsável pela decisão de recuperação e quanto tempo ela pode levar. Evite tratar “temos backups” como evidência de que a recuperação atende ao requisito do serviço.

Mantenha a alteração fácil de revisar

Separe limpezas sem relação com a tarefa da alteração funcional. Inclua no pull request o plano de compatibilidade, os resultados das verificações e as condições de remoção. Marque o ponto a partir do qual o rollback exige trabalho adicional.

Um agente pode ajudar a inspecionar os componentes consumidores e preparar o código de migração. Um responsável ainda precisa aceitar o plano de transição e recuperação. O projeto final é apenas uma parte de uma alteração segura.