Como transformar sistemas legados em especificações executáveis para agentes de IA: uma análise do Framework Reversa

Por André Souza | AI Engineer · Engenheiro de Software Sênior

Toda empresa de tecnologia com mais de cinco anos de mercado tem um sistema que ninguém quer tocar.

É aquela aplicação que roda há uma década, processa pagamentos todos os dias, fatura milhões no final do mês, mas ninguém sabe com precisão o que acontece por dentro. Os engenheiros que escreveram o código original já mudaram de empresa, a documentação se perdeu e qualquer alteração de rotina vira motivo de apreensão.

Nos últimos dois anos, a resposta padrão para lidar com isso tem sido colar o código na janela de contexto de um modelo de linguagem e pedir para refatorar ou explicar o que a função faz.

O resultado costuma ser desastroso. Sem governança de contexto, a inteligência artificial gera código que parece correto na superfície, mas que ignora regras de negócio tácitas, viola comportamentos históricos e quebra integrações em silêncio.

Para resolver essa lacuna de engenharia, o professor Sandeco Macedo desenvolveu o Framework Reversa.

Trata-se de um framework aberto de engenharia reversa de especificações. Ele transforma bases de código não documentadas em contratos operacionais e especificações formais de Spec-Driven Development (SDD), prontos para orientar agentes modernos de desenvolvimento.

Tive a oportunidade de aplicar o Reversa na prática, inclusive na governança e arquitetura do meu próprio portfólio (como no projeto SHM). Neste artigo, analiso como o framework opera, por que SDD e TDD são o seu verdadeiro DNA e como a orquestração de agentes especializados resolve um dos maiores gargalos da indústria de software.

O problema do legado com agentes autônomos

Modelos de linguagem são estatísticos. Quando você entrega uma base extensa de código legado para um agente como Claude Code, Antigravity ou Codex sem limites formais, ele trabalha por aproximação de padrões.

A IA não tem como adivinhar por que um cálculo tributário possui uma condição específica na linha 412. Ela tende a simplificar essa condição achando que é código redundante, gerando impacto financeiro em produção.

O Reversa ataca esse gargalo por um princípio direto: a IA não deve tentar refatorar código antes de compreender e formalizar o domínio.

Em vez de gerar código por impulso, o Reversa instala-se na raiz do projeto (npx reversa install) e coordena uma equipe de agentes especialistas que analisam o sistema camada por camada, sem alterar nenhum arquivo original. Todo o conhecimento extraído fica restrito às pastas .reversa/ e _reversa_sdd/.

A esteira de especialistas: 5 fases de extração e interpretação

A engenharia reversa executada pelo Reversa segue um pipeline de 5 fases, onde cada agente cumpre um papel delimitado:

 Fase 1          Fase 2        Fase 3               Fase 4        Fase 5
Reconhecimento   Escavação     Interpretação        Geração       Auditoria
    Scout        Arqueólogo    Detetive + Arquiteto  Redator       Revisor

Fase 1: Reconhecimento (O Scout)

O Scout faz a primeira vistoria do território. Ele não abre arquivos complexos: apenas cataloga módulos, tecnologias, dependências com versões exatas e gera um inventário estruturado (surface.json). É a partir desse mapa que o plano de análise dos módulos seguintes é montado.

Fase 2: Escavação (O Arqueólogo)

O Arqueólogo realiza o trabalho descritivo módulo por módulo. Ele não interpreta e não emite julgamentos: apenas cataloga funções, fluxos de controle, estruturas de dados, algoritmos e gera o dicionário de dados e fluxogramas em Mermaid. Analisar um módulo por vez evita estourar a janela de contexto e preserva a atenção do modelo.

Fase 3: Interpretação (O Detetive e o Arquiteto)

Aqui a análise deixa de ser descritiva e passa a ser investigativa:

• O Detetive: investiga o código catalogado pelo Arqueólogo e o histórico do Git para responder por que a regra existe e quem tomou a decisão. Ele levanta regras de negócio implícitas, decisões arquiteturais retroativas (ADRs), máquinas de estado e matrizes de permissão.
• O Arquiteto: sintetiza as descobertas em documentação formal de arquitetura: diagramas C4 em três níveis (Contexto, Contêineres e Componentes), modelo de entidade-relacionamento (ERD) e mapa de dívida técnica.

Fase 4: Geração de Contratos (O Redator)

O Redator consolida o conhecimento em contratos formais de SDD por componente, especificações OpenAPI e histórias de usuário. Cada afirmação recebe um nível de confiança:

• Confirmada: apoiada diretamente no código.
• Inferida: deduzida pela lógica de negócio.
• Lacuna: comportamento não documentado que exige validação humana.

Fase 5: Auditoria Crítica (O Revisor)

O Revisor atua de forma adversarial: o papel dele é tentar quebrar as especificações geradas. Ele aponta contradições internas, afirmações marcadas como confirmadas que são na verdade inferências e regras com comportamento dúbio. O resultado é um relatório de lacunas e um índice de confiança que orienta o engenheiro humano.

SDD e TDD: o DNA do Reversa

No Framework Reversa, SDD e TDD são a espinha dorsal do método.

O ciclo funciona em duas etapas integradas:

1. Reversa Discovery (/reversa ou /reversa-autonomous): extrai do legado as especificações compactas (PRD, Arquitetura, Regras de Negócio e Contratos de API).
2. Reversa Forward (/reversa-forward): utiliza a especificação recém-gerada para guiar a evolução do sistema, aplicando Test-Driven Development (TDD) estrito.

No ciclo Forward, o agente não gera código de funcionalidade sem antes ter um teste automatizado escrito e falhando. Ele implementa o código estritamente necessário para fazer o teste passar e refatora em seguida.

Isso elimina o risco de regressão: o sistema só avança sobre base testada e especificada.

O caso extremo: migrando um caixa eletrônico em COBOL de 1994 para Go

Para demonstrar o poder desse método no limite prático, o professor Sandeco Macedo publicou um estudo de caso impressionante em seu canal do YouTube: a modernização completa de um sistema bancário de caixa eletrônico (ATM), originalmente escrito em COBOL em 1994, migrado para a linguagem Go com paridade total e interface touchscreen moderna.

O caso completo foi documentado no vídeo Modernizando Sistema Legado de 1994 em COBOL para Go com Reversa e Claude Code, no canal do professor Sandeco.

O desafio era complexo por definição:

• Origem: código COBOL com 30 anos de existência, interface em tela de caracteres e persistência em arquivos planos (.dat).
• Objetivo: migrar para Go puro, substituir os arquivos planos por SQLite, garantir 100% de paridade nas regras de saque, depósito e extrato, e evoluir a interface para um aplicativo desktop touchscreen em tela cheia.

O resultado da esteira do Reversa com o Claude Code foi notável:

1. Descoberta: o Reversa gerou 11 especificações detalhadas em SDD cobrindo os módulos do caixa eletrônico, atingindo 97,1% de índice de confiança.
2. Tradução de paradigma com Migration Agents: o módulo reversa migrate analisou a mudança de paradigma estruturado do COBOL para a modularidade do Go, desenhando a transição dos arquivos .dat para tabelas relacionais em SQLite.
3. Paridade estrita no terminal: antes de mudar a interface, o agente reversa reconstructor gerou a versão em Go mantendo a mesma interface de terminal do COBOL. Rodando ambas lado a lado, comprovou-se paridade absoluta nos cálculos de saldo e extratos de transações.
4. Modernização com Visor e Design System: através dos comandos reversa visor e reversa system, capturaram-se as telas e a paleta de cores original (incluindo o amarelo clássico do terminal de 1994). O sistema então evoluiu via reversa forward para uma interface desktop moderna, operada por toque e desacoplada do motor transacional em Go.

Todo esse ciclo, que em projetos corporativos tradicionais consumiria meses de reuniões e risco de perda de regras de negócio, foi executado de forma estruturada em aproximadamente 25 minutos de sessão técnica.

A segurança operacional que o ambiente corporativo exige

Para quem responde pela governança técnica de uma empresa, a segurança do Reversa traz garantias claras:

• Imutabilidade da base original: os agentes escrevem apenas nas pastas .reversa/ e _reversa_sdd/. Nenhum arquivo existente do repositório é modificado ou apagado durante a engenharia reversa.
• Independência de chaves de API: o framework não solicita, não guarda e não transmite chaves de API para servidores externos. Ele roda utilizando o agente que já está configurado no seu ambiente de trabalho (Claude Code, Antigravity, OpenCode).
• Salvaguardas no modo autônomo (/reversa-autonomous): o modo autônomo concentra as perguntas em uma entrevista inicial única e roda com travas estritas: nenhum comando externo ou destrutivo (como deploy, push ou remoção de arquivos) é executado sozinho.

Modernização de software com método

A modernização de sistemas legados sempre foi um dos processos mais caros e arriscados da tecnologia. Tentar reescrever do zero costuma consumir recursos desproporcionais e falhar porque o conhecimento prático acumulado em anos de produção nunca foi documentado.

O Framework Reversa oferece um caminho seguro: extrair o conhecimento do legado, formalizar esse conhecimento em contratos de SDD e blindar as regras com suítes de TDD.

Com método e governança, os agentes de inteligência artificial deixam de ser uma fonte de alucinação e passam a atuar como ferramentas de alta precisão na mão de engenheiros experientes.

Para conhecer a documentação oficial, os comandos e a arquitetura do framework, acesse o portal oficial do projeto:
👉 sandeco.github.io/reversa

Assista à demonstração prática da migração do COBOL para Go no canal do professor Sandeco Macedo:
👉 Vídeo no YouTube: Reversa na Prática (COBOL para Go)

Como a sua empresa tem lidado com a modernização de sistemas legados? Compartilhe sua experiência nos comentários.

André Souza
Engenheiro de Software Sênior · AI Engineer
Consultoria em Engenharia de Software, Governança e Agentes de IA