O que é Spec-Driven Development? Um guia prático (e quando não usar)
Spec-Driven Development é o método que usei para entregar uma fintech cripto com 13 apps em 70 dias, sozinho, com agentes de IA. O que é uma spec, os quatro pilares, um exemplo completo, o formato EARS e quando não usar.
A especificação não é documentação. É a memória que o seu agente de IA não tem. Escreva, ou o agente reinventa as suas decisões a cada execução.
Coloco código em produção há 25 anos. No fim de 2025 usei spec-driven development para construir uma fintech cripto completa, 13 apps com 3 APIs, 3 bancos de dados e Kubernetes em produção, em 70 dias, sozinho, com agentes de IA. O estudo de caso tem os números reais. Este texto é o método.
Tem uma coisa que ninguém vendendo ferramenta vai te dizer com todas as letras: a empresa que faz o modelo que você usa já mandou você fazer isso. A orientação da própria Anthropic para o Claude Code é planejar antes de codar. A maioria dos devs pula essa etapa, vê o agente produzir algo rápido e errado e culpa o modelo. O modelo está ótimo. O que falta é processo.
Spec-driven development, definido
Essa inversão é a ideia inteira. Parece burocracia até você lembrar para quem está escrevendo agora. Não é o próximo mantenedor humano. É um colaborador que esquece tudo no instante em que a sessão termina.
Quem faz o modelo manda planejar primeiro
Esquece os blogs de fornecedor por um segundo e lê o manual de quem faz o modelo. As boas práticas do Claude Code, da Anthropic, descrevem um ciclo de quatro passos: explorar, planejar, implementar, commitar. Existe um plan mode dedicado no produto, cujo único trabalho é impedir o agente de escrever código enquanto pensa. O engenheiro que criou o Claude Code diz que a maioria das sessões dele começa em plan mode.
O raciocínio deles é direto. Nas palavras da Anthropic, “deixar o Claude pular direto para o código pode produzir código que resolve o problema errado”. E sobre o que uma boa spec contém: “as specs mais úteis são autocontidas: nomeiam os arquivos e as interfaces envolvidas, dizem o que está fora do escopo e terminam com um passo de verificação ponta a ponta que prova que a feature funciona.”
Eles publicam até o prompt. Este é o template da própria Anthropic para transformar uma ideia em spec antes de existir uma linha de código:
I want to build [brief description]. Interview me in detail using the
AskUserQuestion tool. Ask about technical implementation, UI/UX, edge
cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the
hard parts I might not have considered. Keep interviewing until we've
covered everything, then write a complete spec to SPEC.md.Depois você abre uma sessão nova e executa a spec. Isso é spec-driven development em três frases, dito por quem treinou o modelo. Todo o resto abaixo é como fazer isso bem.
O problema é memória, não inteligência
Contrata o pedreiro mais rápido do mundo. Paredes em minutos, encanamento em segundos, telhado antes do almoço. Só esquece a planta. Você ganha uma casa que fica de pé, com o banheiro onde era a cozinha e uma escada que dá na parede. Claude Code, Cursor, Copilot: esse é o pedreiro. Velocidade nunca foi o problema. Direção é.
A causa raiz não é o agente ser burro. É o agente não ter memória entre sessões. Toda conversa começa do zero. Ele não lembra da decisão que você tomou ontem nem da restrição que vocês combinaram semana passada.
É por isso que a falha fica escondida até sair cara. O código compila. A sintaxe é perfeita. Só que ele resolve um problema que você nunca descreveu por inteiro, com premissas que você nunca assumiu. Código de pagamento vai para produção sem chave de idempotência. Um retry cobra o cliente duas vezes. Você corrige o código. Na próxima vez que o agente regenerar aquele módulo, o mesmo buraco volta, porque a restrição morava na sua cabeça, não na spec.
Tem um resultado aqui que deveria parar qualquer dev experiente. Num ensaio clínico randomizado de 2025, o METR acompanhou 16 devs open-source experientes trabalhando em 246 issues reais de codebases grandes e maduras. Os devs esperavam que a IA os deixasse 24% mais rápidos. Na prática ficaram 19% mais lentos com ela. E depois ainda achavam que ela tinha acelerado o trabalho em uns 20%. Quanto mais capaz o modelo, mais longe uma instrução vaga o leva na direção errada. Capacidade amplifica direção. Não a fornece.
Prompt primeiro, sem spec
- 01prompt, gera, percebe que falta algo
- 02novo prompt, quebra algo, corrige, novo prompt
- 03repete até mais ou menos funcionar
- 048 a 12 horas para uma feature de verdade
Spec primeiro
- 01uma ou duas horas definindo a spec
- 02gera a partir da spec
- 03pequenos ajustes
- 04certo na primeira passada real
Uma spec não é um prompt, e a diferença é o jogo inteiro
A palavra “spec” foi esticada até não significar nada. Metade da indústria hoje usa para dizer “um prompt detalhado”. Resolva isso primeiro, porque prompt e spec falham de jeitos diferentes, e só um deles vale a pena defender.
Um prompt é uma instrução para um turno. Uma spec é um contrato para a feature inteira. Um PRD diz o que construir para o negócio. Uma spec diz ao agente como o sistema precisa se comportar, com precisão suficiente para implementar sem chutar. Um design doc explica uma decisão para humanos. Uma spec é escrita para ser executada.
Uma spec versus as coisas com que confundem
| Artefato | Escrito para | Vida útil | Fonte da verdade? |
|---|---|---|---|
| Prompt | Um turno do agente | Segundos | Não, perde a validade na hora |
| PRD | Stakeholders | Um release | Parcial: o quê, não o como |
| Design doc | Revisores humanos | Até ser construído | Não, ele explica, não governa |
| Spec (SDD) | O agente de IA | Vive junto com a feature | Sim, o código é gerado a partir dela |
Os quatro pilares, e o que vai de fato em cada um
SDD são quatro fases com um gate de aprovação humana entre cada uma. O agente não avança para a próxima fase sem o seu ok. Isso não é cerimônia. É como você pega um erro enquanto ele ainda é barato.
Os quatro pilares
Entrada
Um comportamento a construir. Comece pelo que o sistema precisa fazer, não pelo código.
- 01Requisitos: o quê
O que o sistema precisa fazer, na linguagem do negócio. Comportamentos observáveis, independentes de tecnologia. Gate antes do design.
- 02Design: como
Arquitetura, modelos de dados, contratos de API, escolhas de tecnologia com justificativa. Cada requisito mapeado para uma decisão. Gate antes das tasks.
- 03Tasks: quanto
Quebre em unidades de 2 a 4 horas, cada uma testável de forma independente, com dependências explícitas. Gate antes da implementação.
- 04Implementação: execução
O código segue a spec. Cada task verificada contra os seus critérios de aceite. O que você aprende volta para a spec.
Saída
Um rastro do porquê até o como, e código que bate com o que você de fato pediu.
Requisitos é onde você decide o que “pronto” significa, em frases simples que alguém de fora da engenharia conseguiria checar. Sem stack, sem bibliotecas, sem schema. Se aparece “React” ou “Postgres”, pertence à próxima fase. A saída é uma lista de comportamentos e os critérios de aceite que provam cada um.
Design é onde a engenharia mora. Modelos de dados, o contrato da API, as integrações com terceiros, os edge cases e as escolhas de tecnologia com a justificativa junto. Não “use Postgres”, e sim “use Postgres porque registros de pagamento precisam de garantias ACID”. A justificativa é o que impede o agente de trocar por outra coisa três sessões depois. Cada requisito da fase um é mapeado para uma decisão de design aqui, para nada cair pelo caminho sem ninguém ver.
Tasks é onde você corta o trabalho em pedaços pequenos o bastante para verificar. Duas a quatro horas cada. Se uma task não pode ser testada sozinha, está grande ou vaga demais. Cada task diz os arquivos que toca, suas dependências e como você vai saber que passou.
Implementação é a única fase em que se escreve código, e ela só começa depois que as tasks são aprovadas. O gate é o ponto. No meu kit o gate é literalmente um arquivo de uma linha, um .status por feature que diz requirements:approved, depois design:approved, depois tasks:approved. O agente lê esse arquivo antes de fazer qualquer coisa. A regra é seca: um design.md parado no disco não é aprovação. Só o token de status é. Essa única restrição impede um agente afoito de sair codando em cima de um rascunho que ninguém assinou.
A conta é o motivo para se dar ao trabalho. Um erro pego nos requisitos custa minutos. O mesmo erro pego na implementação custa dias. Pego em produção, com dinheiro de verdade circulando, custa semanas e um pedido de desculpas. Os gates existem para puxar cada erro o mais para a esquerda possível.
Uma spec real, do início ao fim
A maioria dos guias descreve uma spec e nunca mostra uma. Aqui vai uma completa para um caso difícil: criar uma cobrança, em que um retry nunca pode cobrar o cliente duas vezes. É bem próxima do que eu de fato escrevi para a fintech.
# Spec: Create a payment charge (POST /v1/charges)
# Status: requirements:approved
## Overview
A merchant creates a charge against a customer. This moves money, so it
must be safe to retry and impossible to double-bill.
## In scope
- Create a charge from an authenticated merchant request.
- Return the charge id and status.
- Guarantee exactly-once billing under client retries.
## Out of scope (v1)
- Refunds (separate spec: 005-refunds).
- Partial captures.
- Multi-currency. All amounts are BRL, stored as integer cents. Never float.
## Functional requirements (EARS)
- FR-1 WHEN a merchant POSTs a charge with a valid Idempotency-Key,
THE SYSTEM SHALL create at most one charge for that key.
- FR-2 WHEN the same Idempotency-Key is replayed within 24h,
THE SYSTEM SHALL return the original charge and create no new one.
- FR-3 IF the amount is <= 0,
THE SYSTEM SHALL reject with 422 "amount must be positive".
- FR-4 IF the merchant is over its rate limit,
THE SYSTEM SHALL reject with 429 and a Retry-After header.
- FR-5 WHILE a charge is pending,
THE SYSTEM SHALL NOT allow a second capture.
## Acceptance criteria (examples the agent must satisfy)
- amount=1000, key=abc -> 201, status=pending
- same key=abc, replayed -> 200, same charge id, no new row
- amount=0 -> 422 "amount must be positive"
- amount=-50 -> 422 "amount must be positive"
- 6th request in 1s, one merchant -> 429, Retry-After: 1
## Non-functional
- p95 latency under 300ms at 200 requests/sec per merchant.
- Every money value is an integer. No floating point anywhere in the path.
## Data
- charges(id, merchant_id, amount_cents, currency, status,
idempotency_key, created_at)
- UNIQUE(merchant_id, idempotency_key) # this is what enforces FR-1
## Verification
- Integration test replays one key 50x concurrently; assert exactly one
row and one ledger entry.
- Load test holds p95 < 300ms at 200 rps.
## Confirm before building
Do not write code until you restate FR-1 through FR-5 and the uniqueness
constraint in your own words. If any acceptance criterion is ambiguous,
ask before implementing.Repare no que essa spec faz. Ela nomeia os comportamentos exatos, diz o que não vai fazer, fixa o tipo do dinheiro em inteiro para o agente não ter como usar float, coloca a defesa contra cobrança duplicada no banco como uma unique constraint em vez de torcer para o código lembrar, e termina mandando o agente provar que entendeu antes de digitar. Essa última linha não é enfeite. É a prevenção de bug mais barata que você vai escrever na vida.
O que fez essa spec funcionar
Uma boa spec tem uma propriedade testável: entregue para alguém sem nenhum do seu contexto, e a pessoa ainda assim constrói a coisa certa. Quatro movimentos levam você até lá.
Escreva para uma criança esperta
Explique o sistema para uma criança brilhante de 12 anos, que faz perguntas afiadas e não conhece nada do seu contexto. Você não diria “faz aquele negócio com as tasks”. Diria “quando alguém cria uma tarefa, salva o título, confere se a pessoa tem permissão naquele workspace e avisa todo mundo que está vendo a lista”. O agente precisa exatamente desse nível. Não porque é lento, mas porque, como a criança, não tem nada do seu conhecimento implícito. O objetivo do princípio é trazer as regras tácitas (“confere a permissão”) para a luz, onde deixam de ser algo que o agente precisa adivinhar.
Seja específico, ou o agente chuta
Adjetivo não é requisito. “Rápido”, “limpo”, “seguro”, “robusto”: cada um é um convite para o agente inventar a própria definição.
Vago versus executável
| Vago: o agente chuta | Executável: o agente sabe |
|---|---|
| "O sistema deve ser rápido." | GET /api/v1/tasks responde em menos de 500ms no p95 para listas de até 1.000 tarefas. |
| "Valide o título." | vazio -> "Título é obrigatório"; 1 caractere -> "Mínimo 2 caracteres"; 501 caracteres -> "Máximo 500". |
| "Trate os erros com elegância." | Em timeout do provedor, tenta 3x com backoff e depois manda para a fila de revisão manual. |
Escreva requisitos em EARS
Aqui está a técnica que quase nenhum guia ensina, e é a de maior alavanca. Escreva os requisitos funcionais em EARS, o Easy Approach to Requirements Syntax. É um formato de 30 anos, vindo da engenharia de requisitos, feito exatamente para o tipo de ambiguidade que o SDD combate. Cinco formatos de frase cobrem quase tudo, e cada um não deixa espaço nenhum para o agente interpretar.
Os padrões EARS, com exemplos reais
| Padrão | Template e exemplo |
|---|---|
| Ubíquo | THE SYSTEM SHALL validate workspace permissions on every task operation. |
| Orientado a evento | WHEN a task is completed, THE SYSTEM SHALL record the timestamp and the user. |
| Orientado a estado | WHILE a task is archived, THE SYSTEM SHALL NOT allow edits. |
| Comportamento indesejado | IF more than 50 subtasks are created, THE SYSTEM SHALL show "Subtask limit reached". |
| Opcional | WHERE notifications are enabled, THE SYSTEM SHALL notify assignees on change. |
Diga o que você não vai construir
Escopo negativo é a melhor defesa contra um agente que, “querendo ajudar”, constrói algo que você nunca pediu. Escreva cedo, escreva seco: sem tarefas recorrentes, sem integração com calendário até a v2, sem controle de horas, só subtarefas. Cada linha que você exclui é um desvio no modelo de dados que o agente não toma. A mecânica completa disso, com um template para copiar e colar, está no texto complementar: como escrever uma spec a partir da qual um agente de IA consegue construir.
Escolha o seu nível de rigor
Você não precisa ir com tudo. SDD é um dial, e escolher a posição é o que mata o argumento de que “spec é exagero” antes de ele começar. A pergunta nunca é se escrever spec. É quanto este trabalho específico merece. Essa taxonomia vem do trabalho da Birgitta Böckeler na Thoughtworks, e é o jeito mais limpo de pensar nisso.
Quanta autoridade a spec tem sobre o código?
| Nível | A spec é | Melhor para |
|---|---|---|
| Spec-first | Uma plataforma de lançamento. Guia o primeiro build, depois você larga. | MVPs, protótipos, features pontuais |
| Spec-anchored | Um documento vivo, mantido em sincronia com o código conforme ele muda. | Sistemas em produção (o ponto ideal) |
| Spec-as-source | O único arquivo que um humano edita. O código é regenerado a partir dele. | Fronteira, ainda experimental |
SDD não é TDD, BDD nem vibe coding
SDD não é novo. É o ponto mais recente de uma linha de 30 anos. O TDD do Kent Beck guiava o código por testes. O BDD guiava por exemplos de comportamento. O SDD guia por uma especificação aprovada. Um jeito útil de ver: TDD é SDD no nível da unidade. O enquadramento acadêmico, num paper de 2026 sobre o tema, é que a especificação vira a fonte da verdade e o código vira um artefato gerado ou verificado. Veja onde cada método guarda a sua verdade.
Onde mora a verdade?
| Método | A verdade mora em | Modo de falha típico |
|---|---|---|
| Vibe coding | O último prompt | Rápido, confiante, errado |
| TDD | Testes unitários | Testes verdes, arquitetura errada |
| BDD | Exemplos de comportamento | Cenários se descolam do código |
| SDD | A spec aprovada | Spec desatualizada se você não a mantém viva |
Se você está vindo do lado do vibe coding, a comparação cronometrada, mesma tarefa com e sem spec, é um artigo à parte.
Um milhão de tokens de contexto não vai te salvar
Essa é a objeção mais afiada de 2026, e quase ninguém responde. Se cabe a minha codebase inteira na context window, para que escrever spec?
Porque tamanho de contexto e precisão de contexto são problemas diferentes. Um milhão de tokens de código diz ao agente o que o sistema é hoje. Não diz nada sobre o que ele deve se tornar: a sua intenção, as suas restrições, os edge cases que importam para você, o que está fora de propósito. Uma janela maior deixa o agente mais bem informado sobre o presente e nem um pouco mais sábio sobre o destino. Pior: mais contexto é mais superfície para o agente copiar o precedente errado.
Uma spec não é entrega de informação. É um conjunto de decisões. A context window deixa o agente ciente. A spec deixa o agente alinhado. Janelas maiores aumentam o valor de uma spec clara, porque agora o limite da qualidade não é quanto o agente consegue ver. É quão claro você foi sobre o que ele deve fazer.
Quando não escrever spec
Um método honesto diz onde ele não se aplica. SDD tem overhead real, e para muito trabalho esse overhead é puro desperdício. A Anthropic traça a linha numa frase: “se você consegue descrever o diff em uma frase, pule o plano.” Concordo. Pule a spec quando o retorno não compensa.
Esse trabalho merece uma spec?
| Critério (peso) | Script pontual | Spike exploratório | Feature de produção |
|---|---|---|---|
| Vive mais que alguns dias (3) | 1 | 2 | 5 |
| Atravessa várias sessões (3) | 1 | 1 | 5 |
| Várias features ou serviços complexos (2) | 1 | 2 | 5 |
| Corretude ou compliance importam de verdade (3) | 1 | 1 | 5 |
| Pontuação ponderada | 11 | 16 | 55 |
Scale 1-5 (5 = best). Highlighted column: winner by weighted score.
Vai construir um utilitário de uma hora? Escrever spec antes é a burocracia de que os céticos falam. Use SDD quando o trabalho dura mais que uma sentada, envolve arquitetura de verdade ou atravessa várias sessões, porque é exatamente aí que a falta de memória do agente começa a te custar dinheiro.
Não, isso não é waterfall
A diferença é precisa o bastante para ser dita. O problema do waterfall nunca foi planejar antes. Foi o planejamento congelado: um ciclo de feedback tão longo que uma decisão de meses atrás não tinha como responder ao que você aprendeu depois. Specs de SDD são vivas. Você revisa um requisito e a mudança se propaga, de propósito, pelo design e pelas tasks. O ciclo é por fase, não por projeto.
Tem um alerta que vale guardar, porém, e ele vem de novo da Böckeler. O model-driven development tentou isso nos anos 2000, gerando código a partir de modelos formais, e praticamente morreu: DSLs rígidas, geradores gigantes, o nível errado de abstração. LLMs removem parte desse overhead. Mas os modos de falha que mataram o MDD, spec desatualizada, especificar demais cedo demais, piorar a coisa em nome do rigor, são riscos que o SDD ainda pode repetir se você for descuidado. Mantenha a spec proporcional à fase, e mantenha a spec viva.
Como fica em escala
Vou ser breve, porque isso tem um estudo de caso próprio. Mas, para deixar o método concreto, aqui está o que o SDD produziu num projeto real.
Uma fintech cripto, um dev, guiada por spec
- 13
- apps em produçãomonorepo
- 3
- APIs, 3 bancos de dadosauth, pagamentos, exchange
- 70
- diasbuild solo
- 28
- arquivos de speco contexto fixo do agente
Isso foi um dev sozinho. Quando uma organização de engenharia inteira tenta trabalhar assim, com produto, design e vários squads, o framework que aparece é o AI-DLC, o ciclo que a AWS construiu sobre a mesma ideia: a IA conduz, as pessoas decidem nos gates, e toda decisão fica em arquivos versionados. Ele assume que o seu time já especifica. Por isso eu vejo SDD como o degrau antes dele, e defendi isso em AI-DLC vs Spec-Driven Development.
FAQ
O que é spec-driven development, em termos simples?
É um jeito de construir software com IA em que você escreve e aprova uma especificação detalhada antes de qualquer código ser gerado, e essa spec vira a fonte da verdade a partir da qual o agente constrói.
A mudança é que a spec é o artefato principal e o código é a consequência, o inverso de como a documentação costuma funcionar.
A Anthropic recomenda spec-driven development?
Na prática, sim. As boas práticas do Claude Code, da Anthropic, descrevem um ciclo de explorar, planejar, implementar e commitar, e um plan mode dedicado, e publicam um template de prompt para te entrevistar até chegar numa spec antes de qualquer código.
O motivo declarado: deixar o modelo pular direto para o código pode produzir código que resolve o problema errado.
Spec-driven development é a mesma coisa que test-driven development?
São parentes, não a mesma coisa. TDD guia o código por testes. SDD guia por uma especificação aprovada. Um enquadramento útil é que TDD é SDD no nível da unidade.
SDD trabalha numa altitude maior, requisitos, design e tasks, e foi pensado para guiar agentes que não têm memória entre sessões.
SDD é só waterfall com outro nome?
Não. O problema do waterfall era o planejamento congelado, de ciclo longo. Specs de SDD são documentos vivos: você revisa e a mudança se propaga pelo design e pelas tasks de forma controlada.
O ciclo de feedback é por fase, não por projeto.
Uma context window grande torna a spec desnecessária?
Não. Uma context window grande diz ao agente o que o código é hoje. Não diz o que o código deve se tornar, nem o que está fora do escopo de propósito.
Tamanho de contexto e precisão de contexto são problemas diferentes. Janelas maiores aumentam o valor de uma spec clara.
Quando não usar spec-driven development?
Para scripts pontuais, protótipos descartáveis, spikes exploratórios ou qualquer coisa que você termina numa única sessão de prompt. A regra de bolso da própria Anthropic: se você consegue descrever o diff em uma frase, pule o plano.
Use SDD quando o trabalho dura mais que uma sentada, atravessa várias sessões ou envolve arquitetura e requisitos de corretude de verdade.
De que ferramentas eu preciso para SDD?
Nenhuma em particular. SDD é um método, não um produto. Dá para rodar com arquivos markdown simples e qualquer agente de código competente.
Toolkits como o GitHub Spec Kit, o OpenSpec, o AWS Kiro e o meu pi-sdd-kit codificam o workflow, mas o método funciona com um editor de texto e disciplina.
Para onde ir agora
SDD não é sobre escrever mais. É sobre escrever as coisas certas, porque o seu colaborador mais rápido esquece tudo no segundo em que a sessão termina, e a spec é a única memória que ele tem.
Comece pequeno. Escolha uma feature. Escreva os três documentos, requisitos, design e tasks, e entregue para o seu agente. A primeira spec é lenta. A segunda leva metade do tempo. Na terceira já é automático.
A newsletter
Don’t Code, Specify. Toda semana, agentes de IA em produção de verdade. Sem hype: o que funcionou e o que quebrou.
Assinar no Substack (abre em nova aba)O código agora se escreve sozinho. A spec, não. Esse é o trabalho inteiro.