IA em sistema legado sem quebrar o que está em produção

Por que o legado é o caso difícil

Num projeto novo, o código conta a história inteira: ele foi escrito recentemente, por gente que ainda está na empresa, seguindo um padrão que alguém consegue explicar. Num sistema com anos de estrada, o código conta só metade — a outra metade são decisões que ninguém registrou.

Aquele if aparentemente redundante existe porque um cliente específico opera diferente. Aquele campo que parece morto ainda é lido por um relatório que roda uma vez por ano, em janeiro. Aquela função duplicada não foi esquecimento: a versão unificada foi tentada e quebrou algo em produção. Nada disso está escrito. Está na memória de quem estava lá.

A inversão que importa

No legado, a IA não erra por ser incapaz. Ela erra por ser competente demais no que enxerga: entrega uma solução tecnicamente correta para o código que leu, e essa solução viola uma regra de negócio que nunca esteve no código. O resultado passa na revisão superficial e aparece na operação do cliente.

Isso torna o legado o caso mais arriscado — e, ao mesmo tempo, o de maior retorno. É onde existe mais conhecimento não escrito para recuperar, mais tempo perdido em arqueologia e mais dependência de pessoas específicas. Quando o preparo é feito, o ganho é proporcional ao tamanho da bagunça que existia antes.

O que a IA não deduz do código

Vale ser específico, porque é essa lista que define o que precisa ser escrito:

A intenção. O código mostra o que. O porquê — a exigência do cliente, a regra fiscal, o acordo comercial — não está lá.
O que já falhou. A refatoração tentada em 2022 que voltou atrás não deixa rastro no código atual. Sem registro, a IA propõe exatamente a mesma coisa, com toda a confiança do mundo.
O que não se toca. Módulos que só se altera com demanda explícita não têm marca no fonte. Para a máquina, todo arquivo é igualmente editável.
Onde a regra deveria morar. Se o padrão da casa é que certa validação viva no banco, e não na tela, isso é convenção — não é dedutível de um exemplo.
O que é exceção de um cliente só. Num sistema multiempresa, generalizar uma regra específica é o erro mais caro que existe: ele só aparece na base de outro cliente, semanas depois.

Quatro regras para operar sobre produção

01 · Leitura antes de escrita

O primeiro uso produtivo da IA num legado não é gerar código — é entender. Perguntar onde uma regra é aplicada, quais telas tocam determinada tabela, o que acontece quando um status muda. Isso já economiza horas de arqueologia sem nenhum risco de escrita, e serve de teste: se as respostas vierem erradas, o mapa ainda não está bom o suficiente para confiar em qualquer coisa além disso.

02 · O acesso a dado de produção é somente leitura

Investigação toca a base real; alteração, nunca. Escrita acontece em ambiente de teste, e o que precisar ir para produção vira comando revisado por uma pessoa antes de rodar. Essa separação não é burocracia — é o que permite investigar com liberdade sem que um engano custe o dia de um cliente.

03 · Limite escrito vale mais que instrução falada

"Não mexa nessa parte" dito numa conversa não sobrevive à conversa seguinte. O limite precisa estar no repositório, no caminho do trabalho, de forma que seja lido antes de qualquer proposta: o que exige aprovação, o que é intocável sem demanda, onde cada tipo de regra mora. É a diferença entre confiar na memória e ter uma trava.

04 · Mudança cirúrgica, sempre

Em sistema com cliente rodando, a alteração certa é a menor possível que resolve o problema. A tentação da IA — e a de qualquer desenvolvedor animado — é aproveitar a visita para "melhorar de passagem". Em legado, melhoria não pedida é risco não pedido. O que merece melhoria vira item registrado para decisão posterior, não um extra no mesmo commit.

Em sistema que não pode parar, a regra não é "faça o melhor código possível". É "mude o mínimo necessário, e deixe escrito por quê".

Documentar o legado como ele é

Aqui mora o erro que mais atrasa projetos: a equipe decide que vai documentar depois de organizar. Organizar um sistema maduro leva meses, disputa espaço com o roadmap e quase sempre é interrompido. O documento nunca nasce.

O caminho que funciona é o inverso: descrever o sistema exatamente como ele está, gambiarras incluídas. Se uma regra de negócio vive dentro do evento de uma tela, o mapa registra que ela vive ali — e, quando houver motivo, registra também por que ela ficou ali e o que seria preciso para movê-la. Um mapa fiel de um sistema imperfeito é infinitamente mais útil do que um mapa ideal de um sistema que não existe.

Critério prático

Se você precisa refatorar para poder documentar, inverta: documente o que existe, e deixe a refatoração virar uma decisão informada — com o custo, o risco e o ganho escritos. Muitas delas, uma vez escritas assim, revelam-se desnecessárias.

Por onde começar

Escolha um módulo, não o sistema. O que mais consome a semana da equipe e tem responsável claro. Mapear tudo de uma vez é projeto que não termina; mapear uma área entrega valor em dias.
Escreva o mapa dessa área. O que ela faz, onde encosta no resto, quais tabelas toca, o que nunca se altera sem demanda.
Registre as decisões que a explicam. Entreviste quem sabe, enquanto essa pessoa está por perto. É a parte que some primeiro e a única que não dá para recuperar depois.
Use a IA em leitura sobre essa área. Peça explicações, mapeamentos, buscas. Confira as respostas contra o que você sabe — é o teste de qualidade do mapa.
Só então avance para escrita, começando pelo que tem menor raio de impacto, com revisão humana obrigatória.
Repita na próxima área, agora com o método rodado e o formato definido.

Esse ciclo é o mesmo, independentemente do tamanho do sistema. O que muda é quantas voltas ele dá — e é isso que uma avaliação inicial dimensiona antes de qualquer compromisso de prazo.

Os erros que custam caro

Começar pela ferramenta. Distribuir acesso ao time antes de existir mapa e convenção produz código plausível em volume, e transfere todo o custo para a revisão.
Tratar o legado como problema a eliminar. Ele é o ativo: paga a folha e sustenta a base de clientes. O objetivo é operá-lo melhor, não substituí-lo por impulso.
Documentar num lugar separado do código. Wiki externa envelhece porque ninguém a abre no momento do trabalho. O mapa mora junto do fonte e é atualizado por quem mexe nele.
Deixar o porquê para depois. É a única parte com prazo de validade — ela vive em pessoas, e pessoas saem, esquecem e tiram férias.
Generalizar uma exceção de cliente. Em sistema multiempresa, é o erro mais caro: aparece na base de outro cliente, semanas depois, longe de quem fez a alteração.

Quem está escrevendo isto

A SG System mantém um ERP próprio em produção desde 2014, usado hoje por mais de 70 empresas, com módulos fiscais, financeiros e de operação que não podem falhar. As regras acima não vêm de bibliografia: cada uma existe porque a falta dela custou caro em algum momento — e é a mesma estrutura que permite operar IA sobre esse legado todo dia, sem quebrar cliente.

Quando esse preparo precisa ser instalado numa equipe, com o sistema dela e no ritmo dela, é disso que trata a implantação assistida para software house.

Perguntas frequentes

É seguro usar IA em um sistema legado que está em produção?

É seguro quando existem limites escritos que a IA lê antes de propor qualquer coisa: o que não se toca sem demanda, onde cada regra de negócio mora, o que exige aprovação humana e o que é somente leitura. Sem esses limites, o risco não é a IA errar — é ela acertar tecnicamente e violar uma regra de negócio que não estava escrita em lugar nenhum.

A IA consegue entender um sistema legado só lendo o código?

Ela entende o que o código faz, não por que ele faz. A intenção, a exigência do cliente que originou a exceção, a decisão que já foi tentada e falhou e o acordo informal que nunca virou comentário não estão no código-fonte. É essa camada de porquê que precisa ser escrita, e ela é o que separa um assistente que sugere de um que acerta.

Preciso modernizar ou refatorar o legado antes de usar IA?

Não, e tentar isso costuma travar o projeto. Documentar o sistema como ele é sai barato e vale imediatamente; refatorar antes é caro, arriscado e raramente termina. O mapa precisa ser fiel ao legado real, com as gambiarras e as exceções descritas — inclusive o porquê de cada uma continuar existindo.

Por onde começar a usar IA num sistema antigo?

Pelo módulo que mais consome a semana da equipe e que tenha um responsável claro. Escreva o mapa dessa área, as convenções que valem nela e as decisões que a explicam. Comece a IA em leitura e investigação, nunca direto em escrita sobre produção — e só depois amplie para o resto do sistema.

E se o legado tiver regra de negócio embarcada nas telas?

É o caso mais comum em sistema maduro e não impede o trabalho. A regra é registrar onde cada regra vive hoje, mesmo que o lugar não seja o ideal, e só então avaliar caso a caso o que vale mover. Mapa fiel ao que existe vale mais do que mapa de como o sistema deveria ter sido escrito.