Desenvolvimento guiado por especificação com IA: escreva o plano antes do código (2026)

O que é desenvolvimento guiado por especificação?

Desenvolvimento guiado por especificação é um método que trata a especificação (spec) como a única fonte da verdade: você anota "o que precisa ser construído, por quê e como é o pronto" antes da primeira linha de código, e então deixa um agente de IA gerar código, testes e docs que sigam essa spec. Em resumo: a spec conduz a IA, em vez de a IA adivinhar o que você quis dizer.

O coração de tudo é aquela expressão, "única fonte da verdade". No jeito antigo de trabalhar, os requisitos ficam espalhados pela sua cabeça, por algumas mensagens de chat e por um ticket raso. A IA consegue ler muito pouco disso, então ela precisa inferir o resto — e a inferência é onde os bugs nascem. O SDD te obriga a reunir cada restrição importante em um único documento que humanos e agentes conseguem ler: o objetivo, o escopo, os critérios de aceitação e até as coisas que você deliberadamente não quer feitas (não-objetivos).

Isto não é um retorno ao "escreva um documento gigante antes de programar" do waterfall. Uma spec em SDD é curta, viva e normalmente ocupa só uma ou duas telas. É contexto antes do código — contexto suficiente para um agente esperto acertar de primeira, em vez de você remendar tudo à mão três ou quatro vezes. A Thoughtworks chama isso de um padrão que está remodelando como o software é escrito com IA (Thoughtworks, 2025).

Por que escrever um plano primeiro vence o "só na vibe"?

Vamos dar um nome que gruda ao problema central do "só na vibe": o "imposto da ambiguidade". Em cada ponto onde o seu requisito ainda está vago, a IA é forçada a preencher a lacuna. E ela preenche com um chute médio tirado dos dados de treino, não com a sua intenção real. Você paga esse imposto de volta na forma de ciclos de retrabalho: "não, não foi isso que eu quis dizer", "você esqueceu este caso", "por que você mexeu naquele outro arquivo inteiro?".

Se você é novo nesse estilo de largar a mão e deixar a IA liderar, leia primeiro o que é vibe coding para ter contexto — o SDD é o passo que coloca disciplina em cima do vibe coding, não uma rejeição a ele. O "só na vibe" é ótimo para exploração rápida; mas no momento em que uma tarefa tem requisitos claros, ele expõe três riscos:

• Desvio de requisito: a IA entrega algo que roda mas não é o que você precisava — casos de borda faltando, lógica de negócio mal interpretada, nomes e interfaces que quebram suas convenções.
• Desvio de arquitetura: cada prompt vira uma decisão de design improvisada. Depois de dez prompts, a base de código é uma colcha de retalhos que ninguém projetou de propósito.
• Custo de tokens inflando: cada ciclo de "por favor, conserta isso de novo" faz o agente reler o contexto e regenerar código. Três ou quatro rodadas de retrabalho custam muitas vezes mais tokens do que uma boa spec logo no começo.

O guiado por especificação inverte a ordem: você paga o "custo de pensar" uma vez, lá na frente, enquanto ele ainda é barato. Escrever critérios de aceitação te força a responder justamente as perguntas que a IA teria que adivinhar. Quando o contexto está claro, quase não sobra brecha para o agente chutar errado. É também por isso que um fluxo de trabalho de vibe coding maduro sempre tem um passo de escrever o plano costurado no meio, em vez de ficar dando prompt sem parar.

Spec vs plano vs tarefa — qual é a diferença?

Essas três palavras costumam se embaralhar, mas traçar uma linha clara entre elas é a chave do SDD. Em resumo: uma spec responde "o quê e por quê", um plano responde "como, e em que ordem", e uma tarefa é a menor unidade de execução.

Confusões comuns: enfiar o "como" na spec (a spec é microgerenciada cedo demais e perde flexibilidade), ou escrever um plano que pula os critérios de aceitação (o agente nunca sabe quando pode dar por pronto). Um truque para manter a linha: se a resposta é sobre "o que o usuário ou o sistema precisa", ela pertence à spec; se é sobre "o que a gente digita, qual arquivo editar primeiro", pertence ao plano.

Um exemplo DE VERDADE: uma spec + plano antes de qualquer código

Chega de teoria. Aqui está um artefato real de um recurso pequeno que eu costumo usar para ilustrar isto: adicionar um limite de taxa (rate limit) ao endpoint de login. Copie estes dois arquivos, ajuste algumas linhas para o seu projeto e pronto. Primeiro, o spec.md — ele só diz "o quê e por quê", nunca como:

# spec.md - Rate limit for the login API

## Goal
Block brute-force against POST /api/login by limiting the number of
attempts per IP + email, returning a clear error when the limit is passed.

## Why
Login currently has no limit -> passwords are easy to guess and the DB
can be overloaded.

## Acceptance criteria
- Max 5 failed attempts / 15 minutes per (IP, email) pair.
- Over the limit -> HTTP 429 + body { error: "too_many_attempts", retry_after }.
- A SUCCESSFUL login resets the counter for that (IP, email) pair.
- Automated tests for: under the limit, at the limit, over the limit, and reset.

## Non-goals
- NO CAPTCHA (deferred to a later phase).
- NO rate-limiting other endpoints this time.

## Edge cases
- Many users behind the same NAT/IP -> key on (IP, email), not IP alone.
- Clock/timezone: use UTC for the time window.

Em seguida vem o plan.md — agora, e só agora, ele diz "como, e em que ordem". Repare na coluna de arquivos a mexer e na seção de rollback:

# plan.md - Implementing login rate limit

## Steps (in order)
1. Add an attempt-counter store (Redis, key = login:{ip}:{email}, TTL 15m).
 -> File: src/lib/rate-limit.ts (new)
2. Write a checkLoginRateLimit middleware that reads/increments the counter.
 -> File: src/middleware/login-rate-limit.ts (new)
3. Attach the middleware to POST /api/login BEFORE the auth handler.
 -> File: src/routes/auth.ts (edit)
4. On successful login -> delete the counter key for that (IP, email).
 -> File: src/routes/auth.ts (edit)
5. Write tests for the 4 cases in the acceptance criteria.
 -> File: tests/login-rate-limit.test.ts (new)

## How to test
- npm test tests/login-rate-limit.test.ts
- Manual: send 6 wrong requests in a row -> the 6th must return 429.

## Risk & rollback
- Redis down -> fail-open (let it through) or fail-closed? Choose fail-open +
 log a warning, so infra failures do not lock out every user.
- Rollback: removing the middleware in step 3 returns the system to its
 original state.

O que acontece quando você deixa a IA rodar sobre esse plano: o agente trabalha na ordem certa, cria todos os arquivos e para no ponto certo porque os critérios de aceitação deixam claro o que "pronto" significa. Chega de sair refatorando todo o módulo de auth por acaso ou esquecer o caso de resetar o contador. Mesmo agente, mesma tarefa — a diferença é ter ou não um mapa.

O fluxo guiado por especificação com IA (6 passos)

Este é o ciclo que eu uso para quase todo recurso de médio a grande porte. Ele mapeia quase um-para-um no fluxo brainstorm -> plan -> cook -> ship:

1. Ideia e contexto: declare o problema a resolver e as restrições reais (stack, convenções, coisas que não podem ser tocadas). É aqui que você reúne a "verdade" do projeto.
2. Escreva a spec: preencha Objetivo / Não-objetivos / Critérios de aceitação / Casos de borda. Force-se a ser concreta nos critérios de aceitação — onde você for vaga, a IA vai adivinhar.
3. Revise a spec (humano + IA): peça ao agente para ler a spec e apontar contradições, casos faltando ou requisitos impossíveis — antes de existir uma única linha de código.
4. Escreva o plano e divida em tarefas: transforme a spec em passos ordenados que nomeiam os arquivos a mexer, como testar e o rollback. Fatie até cada tarefa ser verificável em uma só passada.
5. Deixe o agente programar tarefa por tarefa: rode uma tarefa de cada vez, sem pular na frente. Depois de cada tarefa, peça ao agente para conferir o trabalho contra o plano.
6. Verifique contra os critérios de aceitação: rode os testes e passe linha por linha pelos critérios. Só quando cada critério estiver verde é que o recurso está pronto — não quando "parece que roda".

O ponto crucial: os passos 3 e 6 são onde o SDD mais te salva. Pegar um bug na fase da spec é dezenas de vezes mais barato do que pegá-lo no código.

Fazendo guiado por especificação direito dentro do Claude Code

Você não precisa de nenhuma ferramenta especial para começar — o Claude Code já vem com três coisas que bastam para montar um ciclo enxuto de SDD:

• Plan Mode: o Claude Code rascunha um plano e deixa você aprová-lo antes de tocar em qualquer arquivo — exatamente o espírito de "plano primeiro, código depois" (Anthropic docs, 2026). Veja como tirar o máximo dele em planejamento com Claude Code (Plan Mode).
• CLAUDE.md como guarda-corpo permanente: coloque convenções, limites e não-objetivos de longa duração neste arquivo para o agente sempre lê-los — isso transforma restrições repetidas em "verdade" fixa do repositório. Isto é context engineering na sua forma mais simples.
• GitHub Spec Kit: um conjunto de comandos open-source que transforma o SDD num fluxo explícito, /specify -> /plan -> /tasks, usável com o Claude Code e muitos outros agentes (GitHub Blog, 2025).

Quer um fluxo guiado por especificação já pronto? Se você prefere não montar na mão CLAUDE.md + Plan Mode + Spec Kit, o pacote AgentKit — agora $149 (de $198) para o Claude Code empacota skills de brainstorm/plan/cook/ship e subagentes de review que seguem o mesmo fluxo spec -> plan -> code -> verify. Fiz um texto completo em o que é o AgentKit — leia para decidir por conta própria, sem pressa de comprar.

Ferramentas guiadas por especificação em 2026

Algumas opções populares, da mais leve à totalmente empacotada:

Não existe uma única ferramenta "certa". Markdown puro + Plan Mode basta para a maioria dos recursos; os kits mais pesados só compensam quando você faz SDD com frequência e quer padronizá-lo num time.

Quando você NÃO precisa de guiado por especificação?

SDD é uma ferramenta, não uma religião. Forçar uma spec em tudo sai pela culatra. Pule o SDD quando:

• Scripts pontuais ou tarefas descartáveis — escrever a spec demora mais do que simplesmente fazer.
• Protótipos/spikes exploratórios: o objetivo é aprender rápido, não acertar ainda. O "só na vibe" cai melhor nesta fase.
• Uma correção de bug de uma linha cuja causa você já entende — você não precisa de critérios de aceitação para mudar um caractere.
• Requisitos que mudam a cada hora: a spec vai ficar velha mais rápido do que você consegue escrevê-la.

Duas armadilhas para ficar de olho mesmo quando o SDD faz sentido: over-spec (escrever uma spec tão detalhada que fica rígida e mata a flexibilidade) e spec rot (a spec nunca é atualizada quando o código muda, virando um documento que mente). Uma boa spec é aquela que é só o suficiente para o agente acertar e ainda fácil de mudar — não a mais longa.

Perguntas frequentes (FAQ)

Como o desenvolvimento guiado por especificação difere do vibe coding?

Vibe coding é disparar prompts e deixar a IA liderar, o que combina com exploração rápida. O guiado por especificação coloca uma spec com critérios de aceitação como fonte da verdade antes de qualquer código, o que combina com recursos de requisitos claros. O SDD é o passo que adiciona disciplina ao vibe coding, não uma rejeição a ele.

Uma spec é diferente de um plano?

Sim. Uma spec responde "o quê e por quê" (objetivo, escopo, critérios de aceitação, não-objetivos). Um plano responde "como, e em que ordem" (passos, arquivos a mexer, como testar, rollback). A spec é mais estável; o plano pode mudar quando a abordagem muda.

Preciso de ferramenta dedicada ou Markdown já basta?

Markdown puro já basta para começar — só um spec.md e um plan.md. Ferramentas como GitHub Spec Kit ou Kiro só ajudam a padronizar o processo quando você faz SDD com frequência ou em um time.

O guiado por especificação te deixa mais lenta?

Mais lenta no começo, mais rápida no todo. Você gasta alguns minutos a mais escrevendo a spec, mas corta muitos ciclos de retrabalho em que a IA teria se desviado. Para tarefas pequenas/descartáveis realmente não vale a pena — aí é só ir na vibe.

Dá para usar guiado por especificação com Cursor ou Copilot?

Dá. SDD é um método, não preso a uma ferramenta. Você pode manter spec.md/plan.md no repositório e fazer qualquer agente (Claude Code, Cursor, Copilot) segui-los. O GitHub Spec Kit já foi pensado para ser multiagente desde o início.

Qual deve ser o tamanho de uma spec?

Longa o bastante para o agente não ter que adivinhar nada importante, geralmente uma ou duas telas. Se a spec é mais longa que o código que ela produz, você está exagerando na spec. O teste de verdade é: critérios de aceitação claros e não-objetivos claros.

Conclusão + próximos passos

O princípio cabe em quatro palavras: spec primeiro, código depois. Você paga o custo de pensar uma vez lá na frente — onde é mais barato — para que a IA não te cobre o imposto da ambiguidade com ciclos caros de retrabalho. A seguir: leia o fluxo brainstorm -> plan -> cook -> ship para ver onde o SDD se encaixa num ciclo de trabalho completo, e planejamento com Claude Code (Plan Mode) para pôr a mão na massa já.