Spec-Driven Development: o método completo para construir com IA (em 2026)

Tem uma coisa que ninguém te conta sobre programar com Claude Code, Cursor ou Copilot:

A parte difícil nunca foi escrever código. É saber o que escrever.

E é exatamente aí que 90% dos projetos com IA generativa desmoronam. O agente é rápido — gera mil linhas em três minutos. Mas sem direção clara, produz o equivalente digital de um castelo de cartas: impressionante à primeira vista, pronto pra desabar ao primeiro requisito mal entendido.

Spec-Driven Development (SDD) é a metodologia que resolve isso. É a base da tese workflow virou commodity e foi como eu construí 13 aplicativos em 70 dias numa cripto fintech, sozinho, com agentes guiados por especificação. Não foi mágica de produtividade. Foi disciplina de spec.

Esse guia é o método completo: os 4 pilares, o formato EARS pra escrever requisitos sem ambiguidade, os slash commands customizados do Claude Code, os subagentes especializados, e por que investir tempo pensando antes de fazer economiza tempo total.

O problema que ninguém fala

A ilusão da velocidade

Pedreiro rápido sem planta da casa. Isso é o que Claude/Cursor/Copilot são quando você os deixa rodar sem spec. Velocidade sem direção é só uma forma mais rápida de chegar ao lugar errado.

Eu já vi isso muitas vezes: o dev abre o cursor, digita “crie uma API REST de autenticação”, o agente cospe 800 linhas de código TypeScript em dois minutos. Parece funcional. Vai pra produção em uma semana. Em um mês, dá erro porque ninguém especificou o que acontece quando o refresh token expira. Em três meses, o sistema vira um monstro impossível de manter porque cada feature foi gerada num momento diferente, com critérios diferentes na cabeça do dev (e nenhum critério na cabeça do agente).

O custo real do retrabalho

Sem spec:

3-4 iterações por feature
8-12 horas por feature
30% do código jogado fora porque “não era isso que eu queria”

Com spec:

2 horas planejando
1 hora implementando (o agente faz a maior parte)
Quase zero retrabalho

Investir tempo em spec economiza tempo total. Não é nem economia marginal — é fator 3-4× no projeto inteiro.

Por que devs experientes resistem

Devs sênior tendem a achar que spec é burocracia. Faz sentido: ele coda com o modelo mental completo na cabeça. Sabe exatamente o que vai escrever, qual padrão usar, onde está cada componente. Pra ele, spec é overhead.

Mas o agente não tem esse modelo. O agente opera em presente eterno — esquece tudo a cada nova sessão, não conhece a história do projeto, não sabe por que aquela decisão foi tomada há três meses.

Specs são memória externa do agente. Sem elas, você fica refazendo o briefing toda vez, e cada execução do agente sai um pouquinho diferente.

A analogia do GPS

Sem GPS: você sabe vagamente onde fica o destino. Decide cada virada no momento. Se perde. Volta. Erra. Chega tarde, ou não chega.

Com GPS: destino claro, rota pensada antes, chegada previsível. O GPS não tira sua autonomia — ele previne ir pro estado errado. Você ainda decide se vai parar pra comer no caminho. Mas não vai errar a saída.

SDD é o GPS do projeto com IA. Não restringe — orienta.

O que é Spec-Driven Development

Definição direta

Metodologia onde especificações detalhadas são criadas e aprovadas ANTES da implementação, servindo como contrato entre o humano e o agente. A spec é o artefato primário. O código é consequência.

Esse simples reordenamento (spec primeiro, código depois) muda tudo. Porque agora:

O agente tem o briefing completo, não fragmentos de chat
Você revisa a decisão arquitetural antes do agente gastar tempo construindo
A spec serve como documentação viva
Próximo dev (ou próximo você em 6 meses) consegue entender o porquê

Os 4 pilares do SDD

A metodologia tem 4 fases, cada uma com seu artefato:

1. Requirements (O QUÊ) — requirements.md Comportamento observável do sistema. Linguagem de negócio. Sem tecnologia. O que o usuário vai conseguir fazer.

2. Design (COMO) — design.md Arquitetura técnica. Stack escolhida e justificada. Modelos de dados. Endpoints. Decisões de design.

3. Tasks (QUANTO) — tasks.md Decomposição em unidades de 2-4 horas. Cada task com critérios de aceitação e rastreabilidade ao requirement original.

4. Implementation (EXECUÇÃO) — código O código segue exatamente a spec. Cada commit é verificável contra os critérios. Feedback retorna pro próximo ciclo de spec.

Os gates: o segredo do controle

Entre cada fase tem um gate: aprovação humana explícita. O agente não avança sozinho.

Requirements → [gate] → Design → [gate] → Tasks → [gate] → Code

Isso parece overhead. Não é. É proteção. Erro pego no gate de requirements custa minutos. Erro pego no gate de design custa horas. Erro pego em produção custa dias e clientes.

Cada gate é um ponto de revisão obrigatório. Eu, o humano, leio o que o agente gerou, valido, ajusto, aprovo. Só então a próxima fase começa.

SDD vs outras metodologias

Aspecto	Waterfall	Agile/Scrum	SDD
Documentação	Extensiva upfront	Mínima	Estruturada por fase
Flexibilidade	Baixa	Alta	Média-alta
Feedback loops	Longos	Curtos	Por fase (gate)
Adequação pra IA	Ruim	Razoável	Excelente
Overhead	Alto	Baixo	Médio
Rastreabilidade	Alta	Baixa	Alta

SDD não é Waterfall escondido. Specs são vivas, evoluem, mas a mudança propaga conscientemente — não vira drift silencioso.

Quando usar SDD: projetos de mais de poucos dias, múltiplas features, qualquer coisa com agente de IA, arquitetura que importa, trabalho que cruza múltiplas sessões/dias.

Quando NÃO usar: script de 1 hora, prototipagem exploratória rapidíssima, escopo trivial em sessão única.

Anatomia de uma especificação

Estrutura de diretórios

projeto/
├── .claude/
│   ├── commands/          # slash commands customizados
│   ├── steering/          # contexto persistente do projeto
│   ├── specs/             # specs por feature
│   │   └── 001-auth/
│   │       ├── requirements.md
│   │       ├── design.md
│   │       ├── tasks.md
│   │       └── .status
│   └── agents/            # subagentes (architect, implementer, reviewer)
└── CLAUDE.md              # entry point — < 300 linhas

CLAUDE.md: o entry point

É a primeira coisa que o agente lê. Tem que ser conciso (< 300 linhas) e cobrir:

O que é o projeto
Stack principal
Convenções de código
Regras críticas (negativas — o que NUNCA fazer)
Workflow básico

Exemplos de regras críticas do TaskFlow Pro (sistema canônico do ebook):

- NUNCA exponha dados de um workspace para outro
- SEMPRE verifique permissões antes de operações
- SEMPRE use transações para operações multi-tabela
- NUNCA confie em dados do cliente — valide no servidor

Detalhes vão pra .claude/steering/ e são importados via referência.

Anatomia de requirements.md

A peça que define O QUÊ tem 6 seções:

Visão Geral — o quê e por quê
User Stories com critérios de aceitação observáveis
Requisitos Funcionais (RF) com prioridade MoSCoW (Must/Should/Could/Won’t)
Requisitos Não-Funcionais (RNF) — performance, segurança, escalabilidade
Glossário — termos do domínio
Fora do Escopo — delimitação NEGATIVA explícita

A seção “Fora do Escopo” é a mais subestimada. Sem ela, o agente alucina features que ninguém pediu. Listar o que NÃO vai ser construído evita 50% das discussões de escopo.

Formato EARS para escrever requisitos

EARS (Easy Approach to Requirements Syntax) tem 5 padrões + 1 combinado. Cada requisito segue um deles. Acabam ambiguidades porque a estrutura força clareza.

1. Ubiquitous (sempre verdadeiro):

O sistema DEVE validar permissões em todas as operações.

2. Event-Driven:

QUANDO uma tarefa for concluída, o sistema DEVE registrar timestamp.

3. Unwanted (proteção contra erro):

SE o usuário tentar criar mais de 50 subtasks, o sistema DEVE exibir erro.

4. State-Driven:

ENQUANTO a tarefa estiver arquivada, o sistema NÃO DEVE permitir edição.

5. Optional:

ONDE notificações estiverem habilitadas, o sistema DEVE notificar.

6. Complex (combinado):

QUANDO X E Y ACONTECEREM, o sistema DEVE Z ANTES DE W.

Vale a pena treinar EARS por uma semana — depois você não escreve requisitos de outro jeito. E o agente entende perfeitamente porque cada palavra-chave (QUANDO, ENQUANTO, ONDE) mapeia pra lógica condicional óbvia.

Escrevendo specs efetivas

O princípio da criança inteligente

Explique a spec como se fosse pra uma criança de 12 anos muito inteligente: sem jargão desnecessário, mas sem omitir nada essencial. Se você precisa de termo técnico, define no glossário. Se você acha que “é óbvio”, não é — o agente não tem o seu contexto.

Específico, não genérico

❌ “O sistema deve ser rápido”

✅ “p95 < 500ms para lista de até 1000 tarefas”

❌ “Boa segurança”

✅ “JWT expira em 1h + refresh token 7 dias; bcrypt cost factor 12; rate limit 10 logins/min/IP”

A diferença não é estilo. É operável vs não-operável. Spec genérica vira interpretação livre. Spec específica vira teste.

Use exemplos concretos

Pra cada validação, mostre uma tabela input → output esperado:

Input	Resultado
email vazio	erro “email obrigatório”
email mal-formado	erro “email inválido”
email já cadastrado	erro “email já em uso”
email novo válido	criação OK, retorna user

Exemplo elimina ambiguidade que descrição textual nunca elimina.

Antecipe as perguntas (FAQ inline)

Cada spec real tem perguntas óbvias que o agente vai fazer (ou pior, vai assumir resposta errada). Adicione FAQ inline na spec:

FAQ — Autenticação

Pode o usuário ter duas sessões ativas em devices diferentes? Sim. Cada device tem refresh token próprio.

O que acontece com refresh tokens existentes quando a senha é alterada? Invalidados. Force logout em todos os devices.

Email confirmado é obrigatório pra login? Sim. Bloqueia até confirmação.

Slash commands customizados

Claude Code (e similares) permite criar comandos slash. Cada um vive em .claude/commands/<name>.md e é invocado como /<name>.

`/spec-new [nome-da-feature]`

Cria pasta .claude/specs/XXX-nome/ com templates vazios de requirements/design/tasks
Cria arquivo .status com conteúdo requirements:draft
NÃO preenche conteúdo. Apenas estrutura.

`/spec-requirements`

Encontra spec com status requirements:draft
Faz perguntas estruturadas (problema, usuários, fluxos, casos de erro, performance esperada)
Preenche requirements.md
Apresenta pra revisão
Após aprovação humana, atualiza .status para requirements:approved

Regra central: NÃO avança sem aprovação explícita.

`/spec-design`

Lê spec com status requirements:approved
Lê .claude/steering/tech-stack.md pra entender stack do projeto
Cria design (Prisma models, endpoints REST, fluxos, real-time events)
Revisão → atualiza .status: design:approved

`/spec-tasks`

Lê spec design:approved
Decompõe em tasks de 2-4h com dependências claras
Organiza em fases (Backend Models → Services → Routes → Frontend)
Revisão → .status: tasks:approved

`/spec-implement [task-id]`

Encontra task pelo id
Verifica que dependências estão completas
Implementa seguindo convenções + design aprovado; escreve testes junto
Marca task como [x]
Sugere próxima task lógica

Regra: NUNCA modifica specs sem permissão. Se durante implementação descobre ambiguidade, PARA e pergunta.

Subagentes especializados

Em .claude/agents/<name>.md você define subagentes com papel restrito. Cada um tem expertise narrow + regras de comportamento.

Architect

Papel: arquiteto de software focado em decisões técnicas e trade-offs
Responsabilidades: decisões arquiteturais, interfaces entre componentes, escolha de tecnologias, identificação de riscos
Regras:
1. SEMPRE justifique decisões (não basta escolher, tem que dizer por quê)
2. SEMPRE considere trade-offs (cada escolha tem custo)
3. NUNCA escreva código de implementação
4. PRIORIZE simplicidade

Implementer

Papel: desenvolvedor focado em implementação limpa e testável
Regras:
1. SIGA a spec exatamente — não interprete, não adicione, não remova
2. ESCREVA testes junto com código
3. USE tipos TypeScript estritos
4. PARE se encontrar ambiguidade — não assume, peça clarificação

Reviewer

Papel: code reviewer focado em qualidade e segurança
Checklist em todo PR:
- Segue convenções declaradas
- Tipos corretos
- Error handling adequado
- Testes cobrem casos principais (sucesso + falha)
- Sem vulnerabilidades óbvias (SQL injection, XSS, secret leak)
- Performance aceitável

Esses 3 papéis cobrem 90% dos casos. Você pode criar outros (testEngineer, documentationWriter), mas resista a multiplicar agentes — cada um adiciona overhead cognitivo.

Stack canônica de ensino (do ebook)

Referências externas que ancoram o método: GitHub Spec Kit (implementação Microsoft de spec-driven), Anthropic Claude Code docs (referência da ferramenta), Barbara Minto, “The Pyramid Principle” (livro fundamental sobre estruturação de pensamento, base do método executivo).

Pra quem quer aprender SDD na prática, o ebook usa TaskFlow Pro como exemplo. Stack pública:

Monorepo: Turborepo (caching, workspace deps)
Frontend: Next.js 14 App Router + shadcn/ui + Tailwind + Zustand + React Query + React Hook Form + Zod + @dnd-kit
Backend: Fastify (2-3× Express + TS melhor) + Prisma + Zod + @fastify/jwt + Socket.io (rooms, reconexão) + BullMQ (retry, delayed jobs)
Infra: Redis, Resend (email)

Versões fixadas pra reprodutibilidade. Spec inclui justificativa pra cada escolha — não é “porque eu gosto”. É “Fastify porque benchmark X, Socket.io porque fallback Y”.

Anti-patterns que matam o SDD

1. Pular gates “só dessa vez” Você decide ir direto do requirements pro código porque “é uma feature simples”. Era. Agora não é mais. Spec virou ficção; código virou improviso.

2. Spec genérica copy-paste Você reaproveita uma spec de outro projeto sem adaptar. Fica plausível mas não específica. Agente alucina detalhes pra preencher os buracos.

3. CLAUDE.md gigante (>500 linhas) Vira ruído. Agente não consegue priorizar o que importa. Volta tudo pra steering/ e mantém CLAUDE.md como índice.

4. Modificar spec depois de implementar sem refletir no código A spec vira mentira histórica. Próximo dev (ou você em 3 meses) acredita na spec, descobre que o código faz outra coisa, perde 4 horas debugando até entender.

5. Implementer fica “esperto” e improvisa Você não disse o que fazer quando o input é null. Implementer assume “vou retornar erro 400”. Outro implementer assume “vou retornar null”. Comportamento inconsistente, bug em produção. PARE e ESPECIFIQUE.

Próximos passos

SDD não é leitura — é prática. Pra começar agora:

Pega um projeto pequeno (1-2 features) que você ia codar do zero essa semana
Cria .claude/ com a estrutura acima (10 minutos)
Escreve a primeira spec (requirements de 1 feature, formato EARS, 30-60 minutos)
Aprova mentalmente, gera design com o agente (/spec-design, 20-40 min)
Implementa via tasks (/spec-tasks + /spec-implement)

No segundo projeto, você vai estranhar. No terceiro, vai virar reflexo. No quinto, você não consegue voltar pro “escrever código direto” sem se sentir desorganizado.

Se você quer o caminho guiado — com revisão, com templates prontos, com prática em projeto real:

→ Formação Consultor AI — método antes da ferramenta (Academy)

→ Ebook SDD: O Guia Definitivo (Library, gratuito com email)

Perguntas frequentes

SDD funciona com Cursor e Copilot, ou só com Claude Code? Funciona com qualquer agente que aceite contexto persistente. Cursor tem .cursorrules, Copilot tem .github/copilot-instructions.md. A ideia é a mesma: spec externa como memória do agente. Os comandos slash são específicos do Claude Code, mas você pode replicar em Cursor com workflows.

Quanto tempo demora pra escrever uma spec antes de começar a codar? Pra feature pequena: 30-60 min de requirements + 30-60 min de design + 20 min de tasks. Total ~2h. Comparado às 8-12h que você gastaria iterando sem spec, é economia clara.

E se eu não souber o design antes de implementar? A /spec-design foi feita pra isso. Você descreve o problema (requirements) e o agente propõe o design. Você revisa, ajusta, aprova. Não precisa saber tudo — precisa decidir, com o agente sugerindo.

SDD funciona em projeto legado? Sim. Crie .claude/ no repo existente. Comece especificando a próxima feature nova com SDD. Vai gerar muito menos atrito que tentar especificar tudo retroativamente (que é Waterfall mascarado).

É overhead pra projeto pequeno? Pra script de 1h ou prototype exploratório, sim — pula. Pra qualquer coisa que dure mais que 1 dia ou tenha mais de 1 feature, vale. A regra prática: se você abrir o projeto amanhã e tiver dúvida sobre “por que decidi assim?”, precisa de spec.

Como SDD muda code review? PR não é mais sobre “está bom?”. É sobre “implementa a spec corretamente?”. O reviewer compara código contra requirements/design. Discussão fica sobre desvio de spec, não estilo pessoal.

Posso usar SDD pra escrever conteúdo, não código? Funciona. Spec pra artigo = brief + outline + critérios de aceitação. Pra ebook = capítulos + objetivos por capítulo + métricas de sucesso. O método é genérico.

Posso compartilhar a metodologia com meu time? Sim, esse guia é livre. Linkar pra Base25 é apreciado mas não obrigatório. O ebook completo (200+ páginas com TaskFlow Pro inteiro) está disponível gratuito.