SDD na Prática

Do Spec ao Pull Request com GitHub Spec Kit e um Coding Agent

Tipo: Tutorial · Autor: Aura Research Board · Data: Maio 2026 · Nível: Iniciante e Intermediário · Aura Company Companion do whitepaper: Spec-Driven Development - O Fim do Vibe Coding

O Que Você Vai Construir

Uma feature pequena entregue inteiramente pelo fluxo spec-driven: spec, depois plan, depois tasks, depois código, depois pull request. A experiência central é revisar o spec, e não o diff, como porta de qualidade. Para quem lidera, esse é o ponto: o spec versionado é o que torna a entrega agêntica auditável e repetível, o controle que a transformação corporativa exige antes de escalar.

Pré-requisito

Este tutorial assume o Spec Kit já instalado e inicializado no seu agente. Se ainda não fez isso, comece por Como Instalar o Spec Kit, que cobre o setup para Claude Code, Cursor, Windsurf, Kiro e GitHub Copilot. Os comandos abaixo (/specify, /plan, /tasks, /implement) são os mesmos em qualquer um deles.

O Exemplo Que Vamos Seguir

Para tornar concreto, vamos entregar uma feature real e pequena: validação de CPF no cadastro de cliente de uma API. O exemplo é ilustrativo, mas o fluxo é idêntico para qualquer feature.

Passo 1: Escrever o Spec

No agente, você descreve a intenção, não a implementação:

/specify Adicionar validação de CPF no endpoint POST /clientes.
O CPF deve ser validado quanto ao formato e aos dígitos verificadores.
CPF inválido retorna 422 com mensagem clara. CPF já cadastrado retorna 409.

O Spec Kit gera um arquivo de spec estruturado. Um trecho do que ele produz:

## Requisito: Validação de CPF no cadastro
### Critérios de aceite
- [ ] CPF com formato inválido retorna 422
- [ ] CPF com dígitos verificadores incorretos retorna 422
- [ ] CPF duplicado retorna 409
- [ ] CPF válido e inédito persiste o cliente e retorna 201
### Casos de borda
- CPF com pontuação (000.000.000-00) e sem pontuação devem ser aceitos
- CPF com todos os dígitos iguais é inválido

Passo 2: Como Seria uma Interação Real

O agente normalmente não sai implementando. Ele pergunta o que o spec deixou ambíguo. Uma troca típica:

Agente: O spec não define se a normalização remove a pontuação antes
de persistir. Você quer armazenar o CPF só com dígitos, ou preservar
o formato enviado?

Você: Só dígitos. Persistir sempre com 11 caracteres numéricos.

Agente: Anotado. Vou adicionar isso aos critérios de aceite do spec
antes de gerar o plano.

Esse é o momento em que o spec melhora. A decisão fica registrada no spec, não perdida no chat. É a diferença entre spec-driven development e vibe coding.

Passo 3: Gerar o Plano e as Tasks

Com o spec aprovado, você pede o plano técnico e a quebra em tarefas:

/plan
/tasks

O agente transforma o spec em um plano (onde mexer, qual validador usar, onde checar duplicidade) e em tarefas granulares. Revise o plano com olhar humano antes de qualquer código. É barato corrigir o plano e caro corrigir o código pronto.

Passo 4: Implementar com Verificação

/implement

O agente implementa tarefa a tarefa, gerando código e testes a partir do spec aprovado. A verificação é objetiva: rodar a suíte, e o spec define o que passar significa. Cada critério de aceite vira um teste.

Passo 5: Revisar o Spec, e Não Só o Diff, e Abrir o PR

No pull request, inclua o spec versionado junto com o código. O revisor avalia primeiro se o spec está certo, depois se o código implementa o spec. A revisão sobe um nível de abstração, do "essa linha está correta?" para o "estamos construindo a coisa certa?".

Quando o Spec Muda

Alterou um requisito? Atualize o spec e regenere o que for afetado. O código é regenerável, o spec é o ativo durável. Esse é o ponto que muda a economia da manutenção.

Erros Comuns

Spec vago, que produz lixo em escala.
Pular a revisão do plano e ir direto ao código, o que joga fora o ganho do SDD.
Tratar o spec como documento morto depois do merge, em vez de mantê-lo vivo.

Próximos Passos

Aprofunde a teoria em Spec-Driven Development - O Fim do Vibe Coding e veja o impacto em um caso real de migração em De Vibe Coding a Pipeline Agentico.

Conexões no Currículo

Módulos relacionados: M0.4 - Prompt Engineering para Desenvolvedores · M0.7 - Geracao de Codigo Efetiva

Disciplinas: D2 - Desenvolvimento AI-Native

Frameworks Aura: SDD · RIPER