Do legado ao SDD: refatorando um módulo bagunçado a partir de uma specification reversa

A maior parte dos tutoriais de Spec-Driven Development começa com mkdir projeto-novo. Bonito. Funciona pra demo. Mas se você abre o repositório real, o que tem é um módulo de 4 mil linhas, comentado pela metade, com três pessoas que entendem ele e duas já saíram da empresa. SDD parece ter sido escrito pra outra plateia.

Não foi. A técnica que falta nos tutoriais chama-se reverse-spec, virar a seta. Em vez de partir da spec e derivar código, você parte do código e deriva a spec. O agente lê o que está lá, descreve em formato de specification, você revisa com gente que conhece o domínio, e a partir daí o ciclo SDD clássico começa a rodar.

Neste post vou mostrar como aplicar reverse-spec num módulo legado real, em 4 passos: inventário, geração da spec, revisão humana e refatoração guiada. Sem reescrever do zero, sem precisar esperar comando oficial em ferramenta nenhuma.

TL;DR

• O que é: técnica de extrair specification a partir de código existente para destravar SDD em projetos maduros.
• Stack: agente CLI (Claude Code, Cursor, Codex), Markdown, código atual do projeto.
• Custo/Acesso: depende do agente que você roda; o método é independente.
• Link útil: GitHub Spec Kit e a discussão aberta sobre reverse-spec em legado.

SDD virou hype, e o legado virou ruído

A tese do SDD é simples: spec é o artefato primário. Código é saída derivada. O post oficial do GitHub que apresenta o Spec Kit cunha bem isso: "intent is the source of truth". O fluxo formal é /specify, /plan, /tasks e implement, com agente executando cada passo contra a spec.

Pra greenfield é direto. Você descreve o problema, o agente desenha, você refina, parte para implementação.

Pra legado, todo mundo trava. O comando que faltava, analyze, que faria reverse engineering de codebase existente em spec, está em issue aberta no spec-kit desde setembro de 2025. A comunidade já pediu: tem discussão de adoção em legado sem resposta da equipe. E enquanto isso, dev sênior em projeto maduro fica vendo demo de TODO list MVC e desconfiando que SDD é coisa pra startup que ainda não escreveu linha 1.

Não é. A própria Anthropic posiciona Claude Code para legado falando em preservar lógica crítica de negócio enquanto moderniza para frameworks atuais, com "incremental refactoring strategies while keeping humans in the loop". O que falta é parar de esperar o comando pronto. Reverse-spec é técnica, não ferramenta. Você implementa com prompt e disciplina.

O que é reverse-spec na prática

Reverse-spec é gerar uma specification que descreve o que o código faz hoje, não o que ele deveria fazer.

Esses dois divergem em legado. E essa divergência é informação valiosa, não ruído. Cada lugar onde o comportamento real difere do "esperado" pode ser:

• Bug histórico que virou feature por costume.
• Regra de negócio real que ninguém documentou.
• Workaround pra uma integração que não existe mais.
• Pegadinha de banco que vai te morder se você reescrever sem saber.

Documentar código legado é descrever estrutura. Reverse-spec é descrever comportamento, invariantes e regras embutidas num formato que serve de input pra mudança. Por isso ela não é narrativa solta tipo "essa função faz X, Y e Z". É estruturada nas mesmas seções de uma spec normal: requisitos, comportamentos observáveis, regras, edge cases.

E por isso a revisão humana não é opcional. O agente vai capturar bug como se fosse feature, e linha de código morta como se fosse caminho ativo. Trabalho do dev sênior na revisão é separar regra real de acidente histórico antes da spec virar fonte de verdade.

Pré-requisitos

Antes de começar:

• Módulo isolado, ou isolável. Não tente reverse-spec em monolito inteiro de uma vez. Recorta domínio.
• Suíte de testes mínima, ou plano explícito de criar uma. Refatorar guiado por spec sem rede de teste é roleta.
• Acesso a quem conhece o domínio. Você, um PM, um dev veterano. Alguém que reconheça uma regra real quando ler.
• Agente CLI rodando no repo com permissão pra ler o código.

Mão na massa, 4 passos

Passo 1: Inventário do módulo

Antes de pedir spec, peça mapa. Spec sem mapa de fronteiras vira ficção genérica.

Você é um engenheiro de software lendo código legado. Antes de qualquer
descrição de comportamento, gere um inventário do módulo em
app/Services/Pricing/ contendo:

1. Pontos de entrada (controllers, jobs, comandos artisan, eventos).
2. Dependências externas (HTTP, banco, fila, cache, outros services).
3. Side effects (escrita em DB, disparo de eventos, jobs enfileirados).
4. Modelos Eloquent tocados e quais atributos são lidos/escritos.
5. Configurações lidas (config/, .env).

Saída em Markdown, sem prosa. Tabela quando fizer sentido.

A saída desse passo é um arquivo INVENTORY.md que vira contexto pra todos os passos seguintes. Sem ele, o agente vai inventar fronteiras.

Passo 2: Geração da spec reversa

Agora a spec. O prompt estrutura por seção e inclui, propositalmente, uma seção de "pontos surpreendentes". Essa é a chave.

Com base em INVENTORY.md e no código de app/Services/Pricing/,
gere SPEC_REVERSA.md com as seções:

## Comportamento observável
Para cada ponto de entrada do inventário, descreva input, transformação
e output. Seja específico em formato (tipos, estrutura).

## Regras de negócio implícitas
Listar regras que o código aplica e que não estão documentadas
em outro lugar. Cite arquivo:linha como evidência.

## Invariantes
Estados que o código garante. Ex: "preço final nunca é negativo".
Cite onde isso é forçado (validation, guard clause, constraint).

## Pontos surpreendentes
Trechos onde o comportamento parece inconsistente, contraditório
ou divergente do nome da função/classe. Marque como [REVISAR HUMANO]
e explique o que te incomodou. NÃO tente racionalizar. Quanto mais
itens nessa seção, melhor.

## Edge cases observados
O que acontece com input vazio, null, números negativos, strings
gigantes, datas no futuro, etc.

Não infira intenção. Descreva apenas o que está no código.

A última instrução é importante. Sem ela, o agente vira escritor de release notes, começa a inventar motivação. Você quer descrição de comportamento, não justificativa.

Passo 3: Revisão humana

Imprime a SPEC_REVERSA.md e senta com quem conhece o domínio. Pra cada item, três perguntas:

1. Regra está correta? Mantém na próxima versão.
2. Regra é bug histórico? Vira item de tarefa explícita: "spec nova precisa fazer X em vez disso".
3. Falta alguma regra que o código não captura? Adiciona.

A seção de "pontos surpreendentes" é onde sai mais valor. Cada item ali é uma decisão pendente. Marca uma a uma. Algumas viram bug fix dentro do próprio refactor. Outras viram débito assumido (mantém o comportamento estranho porque mudar quebra cliente).

Saída: SPEC_V2.md, a spec aprovada que vai guiar a refatoração.

Esse passo é onde o método se diferencia de "rodei IA pra documentar legado". Sem revisão, você só transferiu o problema do código pro markdown. Com revisão, você fez engenharia: decidiu o que fica, o que muda, o que vira tarefa.

Passo 4: Refatoração guiada pela spec

A partir daqui, é SDD clássico. SPEC_V2.md entra no fluxo /specify, /plan, /tasks do Spec Kit, ou no equivalente que seu agente usar (frameworks como cc-sdd e claude-code-spec-workflow suportam vários agentes).

A diferença em relação a greenfield é uma só, e é poderosa: existe baseline. O código atual é oráculo. Cada task gerada pode rodar contra a suíte de regressão. Onde a regressão quebra com a mudança, ou a spec_v2 está prevendo isso (mudança intencional) ou o agente errou (revisita).

Esse loop, spec, plan, diff, teste, revisão, próxima task, é onde mora o que a galera está chamando de harness engineering. É deixar de tratar o agente como autocomplete e começar a tratar como executor dentro de um sistema com testes, observabilidade e gates. Em legado, o harness é literalmente o que separa "refatorei e rezei" de "refatorei e medi".

Limitações e pontos de atenção

• Agente confunde bug com feature. Já dito, vale dizer de novo: sem revisão humana, a spec_v2 perpetua lixo. O método cai por inteiro nesse passo.
• Módulos grandes geram spec superficial. Acima de uns 2 mil linhas o agente começa a generalizar. Quebra o domínio antes de pedir spec, submódulo por submódulo.
• Privacidade. Código com regra de negócio sensível, dado de cliente embutido em fixture, credencial em config: passar por agente hospedado significa ler termos. Quando em dúvida, mascara antes ou usa modelo em ambiente próprio.
• Não substitui teste. Spec aprovada sem cobertura é wishful thinking. Se o módulo legado não tem teste, o passo zero é gerar uma suíte mínima de regressão (o próprio agente ajuda nisso) antes de tocar em refatoração.
• Reverse-spec é foto. Quando o módulo muda, a spec envelhece. Trate como artefato vivo dentro do fluxo de PR, assim como CHANGELOG.

FAQ

Funciona em qualquer linguagem? Sim, em tese. Na prática a qualidade depende do quanto o ecossistema está coberto pelo modelo. PHP/Laravel, Python, TypeScript e Go estão bem servidos em 2026. Linguagens nicho exigem mais correção humana no passo 3.

Posso pular a revisão humana se confio no agente? Não. A revisão é onde o "está assim porque foi sempre" vira "está assim porque é certo". Sem essa separação, você está só formalizando o caos que já tinha.

Reverse-spec substitui documentação técnica? Não. Documentação descreve estado para quem lê. Spec descreve comportamento esperado para quem muda. Servem propósitos diferentes. Idealmente, depois da refatoração, a spec aprovada vira base também pra documentar, mas é um passo a mais, não substituição automática.

Qual a diferença prática pra "explicar código com IA"? Explicação é narrativa, serve pra entender. Spec é estrutura, serve pra mudar. Você pode pedir explicação rapidinho. Reverse-spec é processo deliberado, com humano na revisão e saída versionada no repo.

Conclusão

SDD não é metodologia exclusiva de greenfield. A barreira que separava dev de projeto maduro do hype era falta de técnica pra entrar, não falta de aplicabilidade. Reverse-spec resolve isso: o código existente vira input do ciclo, não obstáculo.

A próxima fase do SDD passa por tratar codebase como dado de entrada estruturado, com a mesma seriedade que tratamos requisito. Ferramenta vai chegar (o analyze do spec-kit é só questão de tempo), mas quem espera comando pronto para começar a aplicar reverse-spec já está atrasado em relação a quem montou um harness próprio com prompt e disciplina.

Esse tipo de loop, agente executando dentro de um sistema com testes, gates e revisão, é exatamente o tema do workshop Harness Engineering com Claude Code, nos dias 16 e 17 de maio: dois dias construindo, do zero, um app real que recebe link de produto, pesquisa alternativas em e-commerces e devolve recomendação estruturada, com Claude Code, Laravel e NativePHP, tratando o agente como peça de produto e não como brinquedo de chat.