IA & automação · Guia
O que é Spec-Driven Development (SDD) e como ele funciona
Spec-Driven Development (SDD) é um método em que a especificação vem antes do código: o time escreve e aprova o que o software deve fazer, com critérios de aceite, e só então agentes de código ou pessoas implementam a partir dela. A spec vira a fonte da verdade, e testes conferem se a entrega cumpre o combinado.
Master TimmAtualizado em 7 min de leitura
Como o Spec-Driven Development funciona
No SDD, cada mudança passa pela mesma sequência de documentos curtos, guardados em Markdown no repositório junto com o código. O agente de código lê esses documentos a cada tarefa, em vez de depender do que ficou no histórico de uma conversa.
- Princípios do projeto: As regras que valem para todo o trabalho, como padrões de código, testes obrigatórios e restrições de segurança.
- Especificação: O que o software deve fazer e por quê, em cenários com critérios de aceite verificáveis, sem escolher tecnologia.
- Plano técnico: Como construir, com arquitetura, stack, contratos de API e as decisões registradas em ADRs.
- Tarefas: O plano quebrado em passos pequenos, cada um ligado a um requisito da spec.
- Implementação e verificação: O agente implementa uma tarefa por vez, e os testes e a revisão humana conferem cada uma contra a spec.
Quando um requisito muda, a spec muda primeiro e o código vem depois. Assim a especificação continua descrevendo o sistema que está em produção, e não o que se planejou meses atrás.
Spec, ADR e critério de aceite: o que cada documento decide
Cada documento responde a uma pergunta diferente; quando um tenta responder às perguntas do outro, a spec fica longa e ninguém a usa. O exemplo abaixo é o cancelamento de pedidos em uma loja virtual.
| Documento | O que decide | Exemplo: cancelamento de pedido |
|---|---|---|
| SpecO comportamento esperado, em cenários | O que o sistema faz e por quê | O cliente pode cancelar um pedido até ele ser enviado |
| Critério de aceiteA condição verificável de um cenário | Quando a tarefa está pronta | Pedido não enviado e cancelado: o estoque volta e o reembolso é criado |
| ADRO registro de uma decisão de arquitetura e do motivo | Como construir e por que esta opção, não outra | Avisar o ERP por uma fila de eventos, não por chamada síncrona |
| TarefasOs passos do plano | A ordem do trabalho e o tamanho de cada pull request | Endpoint de cancelamento, evento para o ERP, teste E2E do fluxo |
No programa em que atuamos para a The Hackett Group, o modelo operacional com Spec-Driven Development reúne 39 ADRs, 45 specs, 14 RFCs e 139 requisitos funcionais e não funcionais com rastreabilidade.
SDD com agentes de código: da spec ao pull request
Um agente de código é rápido e literal: faz o que entendeu do pedido. Com a spec no repositório, o pedido deixa de ser um prompt solto e vira um documento revisado, que Claude Code, Codex, Cursor, Copilot ou OpenCode leem da mesma forma.
- Contexto estável: O agente começa cada tarefa lendo a spec, o plano e os ADRs, não o que sobrou de uma conversa anterior.
- Escopo pequeno: Cada tarefa cabe em um pull request que uma pessoa consegue revisar, ligado a um requisito.
- Revisão objetiva: Quem revisa compara o código com o critério de aceite, não com a própria lembrança do pedido.
- Troca de ferramenta sem retrabalho: A spec é Markdown no repositório, então o processo continua se o time mudar de agente.
Com SDD, a pessoa decide mais cedo: o tempo que ia para corrigir código passa a ir para especificar e revisar, e o merge continua sendo uma decisão humana.
Spec Kit e OpenSpec: as ferramentas de SDD que usamos
As duas ferramentas são de código aberto (licença MIT), guardam tudo em Markdown no repositório e funcionam com Claude Code, Codex, Cursor, Copilot e OpenCode. A diferença está em como cada uma organiza o trabalho.
| Ferramenta | Como funciona | Quando escolher |
|---|---|---|
| Spec KitO kit do GitHub para Spec-Driven Development | Princípios do projeto uma vez; depois specify, plan, tasks, implement e converge a cada funcionalidade, chamados como skills no chat do agente | Quando o time quer um roteiro completo, com etapas extras de clarificação, checklists e análise de consistência |
| OpenSpecO framework da Fission-AI, pensado para sistemas existentes | Cada mudança vira uma pasta com proposta, specs, design e tarefas; a spec descreve só o que muda (ADDED, MODIFIED, REMOVED) e entra na spec principal ao arquivar | Quando o trabalho é uma série de mudanças incrementais em um sistema que já está em produção |
Escolhemos uma delas por projeto, conforme o tamanho da mudança e o código que já existe. O método vale mais que a ferramenta: sem revisão da spec e sem testes, as duas viram só mais uma pasta de Markdown.
Quality gates: testes, cobertura e revisão humana
Uma spec só vale se alguém confere que o código a cumpre. No SDD, essa conferência é automática sempre que dá e humana onde precisa de julgamento.
- Testes a partir dos critérios de aceite: Cada cenário da spec vira pelo menos um teste automatizado.
- Cobertura mínima: O CI bloqueia o merge quando a cobertura cai abaixo da meta definida para o projeto.
- Análise estática e de segurança: Linters, checagem de tipos e varredura de segredos rodam em todo pull request.
- Revisão humana: Uma pessoa aprova o merge olhando a spec, o ADR e o diff juntos; o agente não aprova o próprio trabalho.
Na The Hackett Group, esse desenho sustenta cerca de 4.000 testes unitários e de integração com gates de 95% de cobertura.
Quando o SDD não vale a pena
O SDD cobra um custo fixo: escrever e revisar documentos antes do código. Esse custo se paga quando a mudança tem regra de negócio, envolve mais de uma pessoa ou vai viver muito tempo em produção. Nos outros casos, atrapalha.
- Protótipo descartável: Quando o objetivo é aprender se uma ideia funciona, a spec vem depois, se a ideia sobreviver.
- Correção trivial: Um ajuste de texto ou de configuração não precisa de plano nem de ADR; um critério de aceite basta.
- Requisito desconhecido: Se ninguém sabe ainda o que o software deve fazer, a primeira tarefa é descobrir, não especificar.
- Spec abandonada: Se o time não atualiza a spec quando o requisito muda, ela passa a mentir sobre o sistema, e isso é pior do que não ter spec.
Serviço relacionado
Automação de software com IA
Agentes de código no seu time, com specs e quality gates.
Conversa inicial gratuita · Resposta em até 1 dia útil
Veja também: Modernização de sistemas legados e Mentoria em tecnologia e IA.
Perguntas frequentes
SDD é burocracia?
Não precisa ser: a spec tem o tamanho da mudança, e uma funcionalidade pequena cabe em uma página com cenários e critérios de aceite. O que vira burocracia é documento que ninguém lê; no SDD, o agente lê a spec em toda tarefa e os testes a conferem em todo pull request.
SDD funciona para um time pequeno?
Funciona: com poucas pessoas, a spec substitui parte das reuniões de alinhamento e guarda decisões que ficariam na cabeça de alguém. Um time pequeno pode começar com o OpenSpec, ou só com modelos de spec e ADR no repositório, e acrescentar etapas quando o projeto pedir.
SDD substitui o product manager?
Não: o SDD dá ao product manager um lugar fixo para decidir. Quem conhece o negócio escreve ou aprova o que o software deve fazer e os critérios de aceite; a engenharia escreve o plano e os ADRs; o agente implementa. O método deixa explícito quem decide cada coisa.
Qual a diferença entre spec e user story?
A user story diz quem precisa de algo e por quê; a spec diz o que o sistema faz, em cenários verificáveis. Uma story costuma virar um ou mais cenários da spec, com critérios de aceite que os testes conseguem conferir, e a spec continua valendo depois que a story fecha.
Fontes
Master Timm · Atualizado em