Spec driven development funciona em projeto legado ou só em projeto do zero?

Fala aí, beleza? Todo material de spec driven development começa com a mesma cena: pasta vazia, comando de init, projeto novo brilhando na tela

Aí você olha pro repositório que paga a sua conta

Anos de código, módulo que ninguém entende direito, teste faltando, o cara que escreveu aquilo saiu da empresa em 2021

E bate aquela sensação de que o método não foi feito pra você

A pergunta certa, porém, não é "funciona em legado?"

É: em que ESCOPO funciona?

Neste post eu separo o que dá pra verificar hoje sobre isso no Spec Kit, no Kiro e no Claude Code, sem prometer fórmula mágica. Se você ainda não viu como o SDD funciona, começa por lá que aqui eu já assumo o básico

O que muda entre especificar do zero e especificar o que já existe

O fluxo é o mesmo no papel

O que muda é de onde vem a verdade

No projeto novo, a spec é a única fonte: não existe código pra contradizer ela

Na base existente, o código JÁ é uma fonte de verdade, e ele não pediu licença pra ninguém

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Essa linha da rede de segurança é o coração da diferença

Existe um nome antigo pra ela: teste de caracterização, conceito do Michael Feathers no Working Effectively with Legacy Code

É o teste escrito pra documentar o que o código faz HOJE, não o que ele deveria fazer, e preservar isso enquanto você mexe

Sacou a inversão? No zero você escreve o teste do futuro

No legado você escreve o teste do presente, pra ter coragem de mudar o futuro

E vale o aviso honesto: a documentação oficial do Spec Kit, o kit de spec driven development pra agentes de IA mantido no repositório github/spec-kit, ainda é focada em projeto novo

Tem inclusive uma issue aberta pedindo instruções pra projetos existentes, a #1285, de 04/12/2025

Ou seja: não é impressão sua, o caminho do legado é menos pavimentado mesmo

Por que a especificação retroativa é mais difícil

A spec gerada não parece o seu projeto:

Sintoma: você roda o init na base existente, abre os arquivos e parece spec de outro sistema, com nomes e estrutura que não existem ali

Causa: o specify init gera templates genéricos, que não refletem a stack, a arquitetura nem as convenções reais da sua base. Esse é justamente o motivo declarado das extensões de comunidade pra código legado

Solução: dar contexto de projeto ANTES de pedir spec. No Claude Code o CLAUDE.md na raiz é lido automaticamente no início da sessão e funciona como memória persistente, com padrões de código e decisões de arquitetura. No Kiro o equivalente são os arquivos de steering, em .kiro/steering/ na raiz do workspace, pra informar padrões, bibliotecas e convenções

Como prevenir: trate o contexto como pré-requisito, não como bônus. Template genérico não é bug da ferramenta, é falta de matéria-prima

Ninguém sabe qual comportamento é intencional:

Sintoma: você acha um arredondamento estranho, um retry esquisito, um if que trata um caso específico. É regra de negócio ou gambiarra de 2019?

Causa: base legada costuma não ter registro de decisão de arquitetura (ADR), tem pouca ou nenhuma cobertura de teste, e os engenheiros que conheciam a intenção original já saíram

Solução: teste de caracterização antes de mudar qualquer coisa. Você não precisa decidir se aquilo é certo, só precisa registrar que é assim que funciona hoje

Como prevenir: nunca escreva a spec do "como deveria ser" sem antes fixar o "como está". A spec do desejado sem a foto do atual é só um pedido de desculpas futuro

A spec sai ambígua e ninguém percebe:

Sintoma: o agente implementa, roda, e o resultado é plausível mas não é o que você queria. Aí você descobre que a ambiguidade estava lá desde o início

Causa: em legado a spec nasce cheia de subentendido, porque metade do contexto está na cabeça de quem leu o código, não no arquivo

Solução: usar os portões de qualidade do Spec Kit. O checklist gera uma checagem da PRÓPRIA especificação (se ela está completa, clara, não ambígua e consistente), não do código. Já o analyze, que na maioria dos agentes você invoca como /speckit.analyze (é o mesmo comando, só com o prefixo do Spec Kit), é somente leitura e nunca edita arquivo: ele cruza spec.md, plan.md e tasks.md e devolve um relatório de conflitos, lacunas e ambiguidades

Como prevenir: rode os portões justamente quando bater aquela preguiça de rodar. É onde eles pagam mais

Como escrever a spec de um módulo específico numa base que já existe

A ideia aqui é uma só: spec do delta

Você não vai especificar o sistema inteiro retroativamente. Vai especificar o recorte que a sua mudança encosta, e deixar cada bug fix, feature ou refactor virar uma oportunidade de acrescentar spec perto da área que mudou

Bora ver na prática?

1. Instala o kit dentro do repositório que já existe

A CLI já inicializa num projeto existente, sem criar pasta nova:

specify init .
# ou
specify init --here

A flag --here deposita a pasta .specify/, os templates e os arquivos de comando do agente ao lado do código existente, sem tocar no seu código

Se você não quer instalar nada permanente, dá pra rodar via uvx apontando pro repositório oficial. O comando documentado pro uso avulso é este, com nome de projeto:

uvx --from git+https://github.com/github/spec-kit.git specify init NOME_DO_PROJETO

Repara que essa forma é a do nome de projeto, não a do repositório que já existe. Pra encaixar na base que você já tem, o init que você quer continua sendo o . ou o --here de cima

E tem a variante @vX.Y.Z pra fixar uma release específica, o que é bem sensato em base grande

O erro comum deste passo: rodar o init na raiz de um monorepo achando que ele vai entender tudo sozinho. Ele instala a estrutura, não a compreensão

2. Registra o contexto do projeto antes de pedir qualquer spec

No Claude Code, é o CLAUDE.md na raiz

Padrões de código, decisões de arquitetura, convenções que já existem e você NÃO quer que sejam reinventadas

O erro comum deste passo: escrever um CLAUDE.md de ferramenta ("usamos React") em vez de um de decisão ("essa camada não pode chamar o banco direto, passa sempre pelo repositório"). O segundo é o que salva a spec

3. Documenta o comportamento atual do módulo, com teste de caracterização

Antes de mexer, congela o que existe

O teste de caracterização documenta o que o código faz hoje, não o que ele deveria fazer. É a sua rede

O erro comum deste passo: "corrigir" um comportamento esquisito enquanto escreve o teste. Se está esquisito, ANOTA e segue. Corrige depois, com a spec na mão, sabendo o que quebra

4. Levanta o terreno com o plan mode do Claude Code, sem escrever código

Pera, antes que role confusão: esse plan mode é recurso NATIVO do Claude Code, reconhecimento de terreno pra ele ler a base sem editar nada

Ele NÃO é a fase /plan do Spec Kit. Essa vem depois da spec, lá no passo 6, e a ordem do fluxo continua sendo specify antes de plan

Você aperta Shift+Tab até aparecer plan mode on, ou já inicia a sessão assim:

claude --permission-mode plan

Pra sair, aprova o plano ou aperta Shift+Tab de novo

Esse passo é ouro em legado, porque o agente lê e propõe sem sair editando arquivo que você nem sabia que existia

O erro comum deste passo: aprovar o plano no automático, no modo next, next e finish. O plano é exatamente o momento de discordar barato

5. Escreve a spec só do recorte, com requisito testável

Aqui vale roubar a notação EARS que o Kiro usa no requirements.md, no padrão WHEN <condição/evento> THE SYSTEM SHALL <comportamento esperado>

É chatinho de ler no começo, mas resolve o problema do requisito que não dá pra verificar

No Kiro, aliás, a feature spec é composta por três arquivos versionáveis: requirements.md (ou bugfix.md), design.md e tasks.md

O erro comum deste passo: deixar escapar um "o sistema deve ser rápido". Rápido quanto, medido onde, em qual condição?

6. Roda o fluxo, sem cerimônia desnecessária

O Spec Kit expõe os comandos constitution, specify, clarify, plan, checklist, tasks, analyze, implement e converge, que na maioria dos agentes aparecem como /speckit.*

Só o specify é estritamente obrigatório antes do plan

Caminho enxuto: specify → plan → tasks → implement

Caminho completo acrescenta clarify, checklist e analyze, que são portões de qualidade opcionais

Em legado, minha leitura é que os opcionais deixam de ser tão opcionais assim, justamente por causa da ambiguidade herdada

O erro comum deste passo: pular direto pro implement porque "é um módulo pequeno". Módulo pequeno em base antiga é o que mais tem dependência escondida

E se você repetir esse ritual em vários projetos, faz sentido empacotar ele. Os comandos personalizados do Claude Code hoje têm formato recomendado de skill, em .claude/skills/<nome>/SKILL.md, invocável por /nome, com o diretório .claude/commands/ marcado como legado. Tem um post aqui sobre empacotar esse fluxo numa skill reusável que fecha bem esse ciclo

Quando vale a pena e quando não vale

Feature nova encostada em módulo antigo: vale muito

É o caso mais confortável

O comportamento novo você especifica normalmente, como faria no zero

O trabalho extra fica só na fronteira: o que o módulo antigo garante hoje e você não pode quebrar

Bug fix que precisa preservar comportamento: vale

O Kiro aceita bugfix.md no lugar do requirements.md justamente nesse cenário

Faz sentido: bug fix raramente é "requisito novo", é "o comportamento certo era esse aqui e a gente vai provar"

Refactor ou modernização: é onde mais rende

Extrair spec do código legado é usado pra verificar que a modernização preserva o comportamento exigido

E pra separar o que é comportamento desejado do que é comportamento não documentado, com rastreabilidade de volta ao código-fonte

Essa distinção é o pulo do gato: nem tudo que o sistema faz hoje é regra, parte é acidente que virou tradição

Feature bem entendida e pequena: o portão pesa

Se todo mundo já sabe o que precisa ser feito, rodar clarify, checklist e analyze vira burocracia

O Kiro reconhece isso e oferece variantes: Feature Specs no modo Requirements-First e Design-First, além do Quick Spec, que gera os três artefatos sem portões de aprovação

Usa o formato do tamanho do problema, beleza?

Especificar o sistema inteiro retroativamente: não

Esse é o contraponto honesto do post

A recomendação recorrente pra base existente é spec do delta, mais granular perto da área de mudança, e não uma empreitada de documentar o monólito todo

Vale saber também que as extensões de bootstrap pra código legado no Spec Kit são de comunidade, de terceiros: wcpaxx/spec-kit-brownfield-extensions e Quratulain-bilal/spec-kit-brownfield, com a proposta de extensão registrada na issue #1436 do repositório oficial

Ou seja: existe gente resolvendo, mas não é caminho oficial ainda. Entra sabendo disso

A decisão prática para quem não vai reescrever o sistema

Meu veredito, sem ficar em cima do muro: adota por MÓDULO, no ritmo das mudanças que você já ia fazer de qualquer jeito

A spec vira subproduto do trabalho, não um projeto de documentação paralelo que morre no terceiro sprint

Compensa se você tem um sistema que vai continuar vivo por anos, mexe nele com frequência e sofre com regressão em coisa que ninguém lembrava que existia

Não compensa se a sua meta é documentar tudo antes de tocar em qualquer coisa. Isso não é spec driven development, é um plano de documentação com nome bonito

O que ainda é terreno instável, pra você entrar de olho aberto: a documentação oficial do Spec Kit é focada em greenfield, e o suporte a base existente hoje vem de comunidade e de discussão aberta

O que NÃO é o gargalo: compatibilidade

O Spec Kit declara suporte a mais de 30 agentes de IA, incluindo o Claude Code

E o Kiro versiona as specs junto do código por design, em .kiro/specs, commitadas no repositório

Inclusive os walkthroughs de comunidade do Spec Kit já incluem extensões de bases legadas bem gordas: um CMS em ASP.NET com cerca de 307.000 linhas e um runtime Jakarta EE com cerca de 420.000 linhas em 180 módulos Maven

Não é que "não dá em legado"

É que dá de um jeito diferente do que os tutoriais mostram

Conclusão

Resposta curta pro título: funciona em legado sim, desde que você especifique o DELTA e não o monólito

A spec no projeto do zero descreve o futuro

A spec no legado começa descrevendo o presente, e é essa etapa a mais que faz ela parecer mais difícil (porque é mesmo)

Próximo passo, e é pequeno de propósito: escolhe o próximo módulo que você JÁ ia tocar essa semana

Documenta o comportamento atual dele antes de mexer

E escreve a primeira spec só desse recorte, mais nada

Se funcionar, você repete no próximo módulo. Se não funcionar, você perdeu uma tarde e não um trimestre 🙂

até o próximo post!