Como Soltar a IA em Código Legado Antigo Sem Quebrar Nada

Imagine um cenário típico: você herdou um projeto com cinco anos de histórico. Não há documentação, o autor original do código saiu há três anos, e a lógica de negócio está espalhada por centenas de arquivos. Conectar um agente de IA como Claude Code ou Cursor a uma codebase assim é aterrorizante. Você pede para ele corrigir uma função — ele reescreve o módulo vizinho e destrói dependências implícitas que ninguém sequer sabia que existiam.

Recentemente, uma ferramenta interessante chamada Reversa apareceu no GitHub, criada por um desenvolvedor com o nome de usuário sandeco. O framework resolve esse problema de uma maneira original: ele mergulha em um projeto legado, realiza engenharia reversa e transforma o código-fonte em especificações executáveis.

Por Que Substituir Código por Especificações

A maioria dos agentes de codificação é excelente em criar projetos do zero. Você escreve um prompt, a ferramenta gera uma estrutura limpa e código funcional. Esse truque não funciona com código legado. Se o agente não entende as restrições arquiteturais e o contexto, ele trabalha às cegas.

O Reversa atua como uma ponte entre código antigo e assistentes de IA modernos. A ferramenta não escreve documentação para humanos no sentido tradicional. Em vez disso, gera contratos operacionais. Com base nesses contratos, qualquer agente de codificação pode imediatamente ver as regras do jogo, tabelas de banco de dados, matrizes de permissões e algoritmos que não devem ser violados.

Como Funciona o Processo de Pesquisa

A instalação é executada na raiz do projeto através de um único comando:

npx reversa install

O instalador detecta automaticamente os mecanismos instalados no sistema — Cursor, Claude Code, Codex, Windsurf ou Copilot. Depois disso, ele copia os conjuntos de habilidades para o diretório .agents/skills/ e cria um arquivo de configuração.

Quando você executa o comando /reversa dentro do seu cliente de IA, um pipeline de vários agentes especializados é ativado. Cada um desempenha seu próprio papel no processo de análise:

• Scout escaneia a estrutura superficial, identifica linguagens, frameworks e pontos de entrada.
• Archaeologist mergulha profundamente nos módulos, analisa estruturas de dados e algoritmos complexos.
• Detective extrai regras de negócio implícitas, diagramas de estado e regras de acesso.
• Architect compila os dados coletados em diagramas C4, esquemas ERD e mapas de integração.
• Writer formata as especificações finais como contratos com referências a linhas específicas de código.

Um detalhe interessante: o Reversa marca cada afirmação nos documentos finais com um badge especial de precisão. O ícone 🟢 significa que a regra é diretamente respaldada por código com referências de arquivo e linha. O ícone 🟡 é colocado onde a IA fez uma inferência lógica. O marcador vermelho 🔴 indica "pontos em branco" onde o código não conseguiu explicar algo e é necessária intervenção humana.

Seguro por Padrão

O medo principal ao lançar qualquer utilitário automatizado sobre um repositório complexo é a perda de dados ou edições acidentais. Os criadores do Reversa enfatizaram o isolamento completo.

O framework segue uma regra estrita: o código-fonte do projeto nunca é modificado ou excluído durante a análise. Todos os resultados são escritos pelos agentes em apenas duas pastas de serviço: .reversa/ para o estado da análise e _reversa_sdd/ para as especificações finalizadas.

Além disso, a ferramenta não solicita ou transmite chaves de API. Todo o trabalho analítico é transferido para a ferramenta de IA que você já tem em execução localmente.

O Que Acontece Após a Extração de Dados

Criar especificações é apenas o primeiro passo. Com base na pasta _reversa_sdd/ gerada, você pode iniciar outros fluxos de trabalho através de comandos adicionais.

• /reversa-forward ajuda a evoluir o sistema passo a passo, transformando novos requisitos em código funcional com controle de regressão.
• /reversa-migrate prepara um plano para migrar a stack legada para uma arquitetura moderna.
• /reversa-docs compila os dados coletados em um site HTML estático com gráficos D3 interativos e um mapa de arquitetura 3D.
• /reversa-debugger registra bugs e os vincula causalmente às especificações.

Se você precisar executar um ciclo completo sem paradas e confirmações constantes, existe o modo autônomo /reversa-autonomous. Nele, o utilitário faz todas as perguntas esclarecedoras durante uma entrevista inicial e depois trabalha de forma independente.

Onde os Resultados São Salvos

Dentro da pasta _reversa_sdd/, aparece uma estrutura clara de arquivos Markdown. Lá você pode encontrar um dicionário de dados, descrição do domínio, matrizes de papéis, especificações OpenAPI e diagramas de sequência em formato Mermaid.

_reversa_sdd/
├── inventory.md              # Инвентаризация файлов
├── dependencies.md           # Зависимости и версии
├── code-analysis.md          # Помодульный технический анализ
├── data-dictionary.md        # Словарь данных
├── domain.md                 # Бизнес-правила и глоссарий
├── state-machines.md         # Конечные автоматы в формате Mermaid
├── architecture.md           # Обзор архитектуры
├── confidence-report.md      # Отчет о точности анализа 
└── sdd/                      # Спецификации отдельных компонентов

Se você modificar o código através do /reversa-forward durante o refinamento do sistema, um agente Sync especial adiciona cuidadosamente informações sobre novos recursos à pasta _reversa_sdd/addenda/, preservando o histórico de alterações.

Vale a Pena Adotar

O Reversa parece ser uma tentativa madura de trazer ordem ao caos de projetos legados antes de entregá-los à IA. O projeto está em desenvolvimento ativo, e um preprint recente no arXiv de maio de 2026 respalda a arquitetura do framework com uma abordagem acadêmica.

A ferramenta será útil para equipes que herdaram serviços negligenciados sem documentação, assim como para aquelas que planejam uma migração faseada de stacks antigas. Você pode experimentar o utilitário em qualquer repositório de teste, já que ele não altera nenhum arquivo existente.

Para uma início rápido, basta executar npx reversa install no terminal e abrir o projeto no seu editor de IA habitual.