Como usar spec-driven development para corrigir um bug: da reprodução até a spec da correção

Fala aí, beleza? Quase todo tutorial de spec-driven development que tu abre ensina a mesma coisa: feature nova, terreno limpo, do zero

só que o teu dia a dia raramente é terreno limpo

É bug

É código que alguém escreveu em 2023 e ninguém mais entende, é a regressão que já voltou duas vezes, é aquele comportamento estranho que só aparece com um cliente específico

Esse post é sobre aplicar o MESMO rigor de spec à manutenção: reproduzir o problema, delimitar o que deveria acontecer, escrever a spec da correção e, principalmente, definir o critério que prova que o bug morreu

E se tu chegou aqui digitando SSD na busca, dá uma passada rápida no post que explica por que o termo certo é spec-driven development, aí tu acha material de verdade sobre o assunto

O que você precisa antes de escrever a spec da correção

São duas frentes: a ferramenta e o insumo

Sem a segunda, a primeira só te dá um documento bonito de um bug que tu não entende…

Frente 1, a ferramenta:

Formação Recomendada

Formação Claude Code

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

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O caminho mais direto é o Spec Kit, toolkit open source do GitHub pra spec-driven development

Ele roda em fases e gera constitution.md, spec.md, plan.md e tasks.md, e o agente implementa a partir desses arquivos

Instalação e inicialização via uvx:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Só que correção de bug quase nunca começa em projeto novo, né?

Então o comando que interessa aqui é o de inicializar DENTRO do projeto que já existe:

specify init .

# ou, na mesma pasta
specify init --here

O Spec Kit funciona com mais de 30 agentes de código, entre eles Claude Code, GitHub Copilot, Cursor e Gemini CLI

Então tu não precisa trocar de ferramenta pra experimentar, ele se encaixa no que tu já usa

Tem também o caminho alternativo: o Kiro IDE, que trouxe o fluxo de Bugfix Spec na versão 0.10, lançada em 18 de fevereiro de 2026, com análise de causa raiz, desenho da correção e prevenção de regressão

Se tu quiser entender antes como o Kiro organiza as specs, tem post separado sobre isso

Frente 2, o insumo:

Essa é a parte que o pessoal pula e depois reclama que a IA "não entendeu o bug"

Tu precisa de reprodução confiável e da lista do que NÃO pode mudar

A boa prática que o Kiro recomenda pra descrever o bug antes da análise de causa raiz é justamente essa: passos de reprodução, comportamento atual, comportamento esperado e as restrições de código ou de comportamento que não podem mudar

Olha que interessante, o item mais esquecido é o último

Todo mundo sabe dizer o que está quebrado, quase ninguém escreve o que precisa continuar funcionando igual depois da correção

Passo a passo: da reprodução até a spec da correção

Bora ver na prática?

1. Reproduzir de forma determinística e anotar os passos exatos

Antes de qualquer arquivo .md, tu precisa fazer o bug acontecer quando TU quiser

Anota o passo a passo cru: dado de entrada, estado do sistema, sequência de ações, o que aparece na tela ou no log

Se tu não consegue reproduzir, tu não tem um bug, tu tem um relato

O erro comum deste passo: aceitar "às vezes acontece" como reprodução e seguir em frente

Spec construída em cima de intermitência gera correção que ninguém consegue validar depois

2. Descrever o bug em três blocos de comportamento

Esse é o recorte que o bugfix.md do Bugfix Spec do Kiro usa, e ele funciona em qualquer ferramenta porque é só uma forma honesta de pensar:

• Current Behavior: o que acontece hoje
• Expected Behavior: o que deveria acontecer
• Unchanged Behavior: o que não pode mudar

No Kiro IDE isso nasce pelo botão + na seção Specs do painel, ou pela opção Spec no painel de chat, e ele te pergunta se é Feature ou Bug

A partir daí o fluxo é o mesmo de três fases das Feature Specs, gerando bugfix.md (a análise do bug), design.md (arquitetura técnica) e tasks.md (plano de implementação)

Usando Spec Kit tu escreve esses três blocos com as próprias mãos e joga como descrição do problema

O erro comum deste passo: pular o terceiro bloco

O comportamento inalterado é o que segura a mão do agente pra ele não "consertar" o bug reescrevendo meia camada do sistema

3. Rodar o agente em leitura ANTES de deixar ele editar

Aqui é onde o vibe coding puro costuma cobrar a conta: o agente lê metade do contexto, decide uma causa e já sai editando

No Claude Code tem modo de planejamento pra exatamente isso, em que ele lê arquivos e responde sem alterar nada

Três jeitos de entrar:

• Shift+Tab até a barra de status mostrar ⏸ plan mode on
• iniciar a sessão com claude --permission-mode plan
• prefixar o prompt com /plan

claude --permission-mode plan

O ciclo do Shift+Tab é: default → acceptEdits (aprova edições automaticamente) → plan (propõe sem editar)

E tem um detalhe que muita gente não sabe: Ctrl+G abre o plano proposto no teu editor de texto padrão, pra tu editar ANTES de aprovar

Ou seja, tu não fica no sim/não, tu corrige a hipótese de causa raiz na mão e devolve

O erro comum deste passo: deixar o agente editar antes de vocês dois concordarem sobre a CAUSA

Correção em cima de causa errada não é correção, é sintoma escondido

4. Escrever a spec da correção

Com o problema delimitado, chama o comando de spec:

/speckit.specify

O template do spec.md no Spec Kit tem Overview, requisitos funcionais, cenários de usuário e Success Criteria

E os critérios de sucesso ali são exigidos como mensuráveis e agnósticos de tecnologia, verificáveis sem detalhe de implementação

Isso muda tudo numa spec de bug

"Trocar o if da linha 84" não é critério de sucesso, é palpite de implementação

"Pedido com cupom expirado é recusado e o carrinho continua intacto" é critério, dá pra verificar sem abrir o código

O erro comum deste passo: escrever critério de sucesso como detalhe de implementação

Quando tu faz isso, tu já entregou a solução pro agente e perdeu a chance de descobrir que a causa era outra

5. Fechar as lacunas antes de planejar

/speckit.clarify

Esse comando faz até cinco perguntas direcionadas sobre áreas subespecificadas da spec atual e grava as respostas de volta no spec.md

E ele pode rodar VÁRIAS vezes antes do plano, então não precisa tentar acertar tudo de primeira

Em bug isso é ouro, porque as perguntas normalmente caem no que tu deixou vago sobre o comportamento esperado

O erro comum deste passo: responder as perguntas no chat e não deixar a resposta virar spec

Se está só no histórico da conversa, sumiu

6. Validar a spec antes de quebrar em tarefas

/speckit.checklist

Ele gera um checklist de qualidade sob medida, descrito como "testes unitários dos seus requisitos", pra confirmar que a spec está completa, clara e consistente antes de virar tarefa

Massa, né? É revisão da spec, não do código

O erro comum deste passo: tratar o checklist como burocracia e correr pro plano

Spec ambígua não melhora sozinha na fase seguinte, ela só vira tarefa ambígua

7. Definir o que prova que o bug morreu

Esse é o coração do post

Correção sem prova é fé

O Kiro gera property-based tests pras três categorias do bugfix: testes que verificam que a implementação ATUAL tem o bug, testes de que a correção resolve o bug e testes de que o comportamento inalterado continua funcionando

Repara na primeira categoria, ela é a mais contra-intuitiva e a mais importante

Um teste que FALHA hoje é o que transforma a tua reprodução em algo automático

Se ele passa antes da correção, ou o teste está errado, ou tu não reproduziu o bug de verdade

Mesmo sem estar no Kiro, tu pode escrever esses três grupos como critérios de sucesso no spec.md:

• o cenário que hoje falha
• o mesmo cenário depois da correção
• os cenários vizinhos que não podem mudar de comportamento

Escrito assim, o critério de sucesso deixa de ser opinião e vira coisa que roda: os três grupos verdes, o bug morreu, e tu consegue mostrar isso pra qualquer pessoa do time

O erro comum deste passo: só escrever o teste do "depois"

Aí quando a suíte fica verde ninguém sabe se ela ficou verde porque o bug morreu ou porque o teste nunca cobriu o caso

8. Gerar plano, tarefas e checar consistência

/speckit.plan
/speckit.tasks
/speckit.analyze

O analyze é análise SOMENTE LEITURA de consistência entre spec.md, plan.md e tasks.md, apontando conflitos, lacunas e ambiguidades

Exemplo clássico que ele pega: tarefa sem requisito correspondente

Em correção de bug, tarefa órfã costuma ser exatamente aquela refatoração que ninguém pediu e que vai estourar em outro lugar 😀

O erro comum deste passo: aceitar tarefa que não amarra em nenhum requisito só porque "faz sentido"

9. Implementar e conferir o resultado contra a spec

/speckit.implement
/speckit.converge

O converge roda DEPOIS do implement e confere o código contra spec, plan e tasks

E ele é append-only: nunca edita nem apaga código

Se achar lacuna, ele acrescenta tarefas numa seção Convergence do tasks.md

É o fechamento do ciclo, o momento em que tu compara o que foi implementado com o que tu tinha combinado lá atrás

O erro comum deste passo: parar no implement e considerar entregue porque o sintoma sumiu na tela

Sintoma sumindo é evidência, não é prova

E o Spec Kit tem comando próprio pra bug?

Boa pergunta, e a resposta honesta é: não no fluxo oficial de hoje

A lista de comandos do processo central de SDD no Spec Kit é constitution, specify, clarify, plan, checklist, tasks, analyze, implement e converge, todos com o prefixo /speckit

Existe a issue #442 propondo comandos como /diagnose, /fix e /iterate pro pós-implementação, mas é proposta aberta

Então o caminho pra bug hoje é esse do post: usar os comandos que existem, com o recorte de comportamento que o Kiro formalizou

Quando vale abrir uma spec para o bug (e quando é exagero)

Se liga, ninguém aqui vai dizer pra tu abrir spec de typo

Vale o ritual quando:

• o código é terra de ninguém: ninguém no time domina aquele trecho, então a spec vira o entendimento compartilhado antes de mexer
• a regressão já voltou antes: bug reincidente é sinal de que faltou o teste do comportamento inalterado, e a spec força ele
• a correção toca comportamento que outros times consomem: aqui o bloco de "não pode mudar" vale mais que a correção em si
• o projeto é antigo e tem histórico: a spec precisa conviver com o que já existe, não fingir que o mundo começou hoje

Não vale quando é typo, ajuste de uma linha ou correção óbvia com teste que já cobre o caso

Ritual demais em bug pequeno só cria arquivo pra ninguém ler

Onde a spec da correção vai morar?

Esse é o problema real de projeto que já existe, e o Spec Kit tem guia oficial pra isso, o "Evolving Specs in Existing Projects", com três modelos de persistência:

Esse terceiro é o mais comum em bug, convenhamos

Tu escreve a spec achando que entendeu a causa, mexe no código e descobre que a causa era outra

Escolher o modelo ANTES evita aquela pasta de specs que vira cemitério de arquivo desatualizado

Vídeo: spec-driven development na prática

Pra começar do zero com spec-driven development, esse vídeo do canal apresenta o método e mostra o raciocínio por trás dele:

Conclusão

A spec de uma feature vive do que ela promete

A spec de uma correção vive do critério que PROVA que o bug acabou

É isso que separa o "consertei" do "consertei e consigo demonstrar", e é a parte que quase nenhum tutorial de spec-driven development cobre porque quase todos ensinam feature nova

O próximo passo é bem concreto: pega o último bug do teu backlog, aquele que tu já reproduziu

Escreve os três blocos de comportamento (atual, esperado e inalterado)

Roda specify init . no projeto que já existe e passa o fluxo inteiro do zero, com o agente em modo leitura primeiro

Depois compara o resultado com o que tu faria no impulso, direto no editor

A diferença normalmente não está na correção, está no que tu consegue provar depois dela…

Até o próximo post! =)