Spec-Driven Development: O Fim do Vibe Coding

Se você já usou uma IA para escrever código, provavelmente já passou por isso: você pede algo, a IA entrega algo que parece correto, mas quando vai testar… não era bem aquilo. O código compila, os nomes das variáveis fazem sentido, mas o comportamento não é o que você esperava. Isso tem um nome: vibe coding.

Nesse artigo vou apresentar o Spec-Driven Development (SDD), uma abordagem que muda a forma como trabalhamos com agentes de IA, saindo do “vai lá e faz” para um processo onde especificações são o contrato que a IA segue.

O que é Vibe Coding?

Vibe coding é quando você dá uma instrução vaga para a IA e torce para que ela entenda o que você quer. Funciona para coisas simples, mas em projetos reais vira uma bola de neve:

Código que parece correto mas não atende o requisito
Decisões de arquitetura tomadas aleatoriamente
Sem testes, sem validação, sem rastreabilidade
Cada sessão com a IA começa do zero, sem contexto

A real é que devs já usam IA em cerca de 60% do trabalho, mas delegam completamente apenas 0-20% das tarefas, segundo o relatório de tendências da Anthropic (2026). Isso acontece justamente porque não existe um contrato claro entre o que queremos e o que a IA produz.

SDD: Specs como Fonte da Verdade

O Spec-Driven Development muda o jogo. Em vez de “o código é a fonte da verdade”, passamos para: “a intenção é a fonte da verdade, com a IA tornando especificações executáveis.”

Na prática, isso significa produzir artefatos (PRD, arquitetura, stories) antes de sair codando. Esses artefatos formam um contrato que o agente de IA segue.

As Regras de Ouro

Esses são princípios que, independente do projeto ou stack, fazem diferença quando se trabalha com IA:

#	Regra	Por quê
1	Specs antes do código	IA sem specs produz código plausível mas errado
2	Pesquisa antes de implementar	Memória do agente pode estar defasada. Docs oficiais são atuais
3	Quality gates antes do commit	Code review + testes + build evitam regressões silenciosas
4	Specs vivas	Specs atualizadas após implementação, não só antes
5	Decisões viram regras	Um achado só num documento é desperdício. Deve virar regra ou story
6	Testes são contratos dos ACs	Cada critério de aceite mapeia para pelo menos um teste

O Ciclo de Vida: 6 Fases

O SDD não é cascata. É um ciclo onde cada fase alimenta a próxima e o feedback volta para atualizar as specs.

flowchart TB CON["1. Constituição"] SPEC["2. Especificar"] PLAN["3. Planejar"] BUILD["4. Implementar"] REVIEW["5. Revisar"] SYNC["6. Sincronizar"] RULES["Regras do projeto"] CON --> SPEC --> PLAN --> BUILD --> REVIEW --> SYNC SYNC -. Atualiza .-> SPEC REVIEW -. Vira regra .-> RULES RULES -. Alimenta .-> CON accTitle: Ciclo de seis fases do SDD accDescr: Um ciclo de seis etapas do Spec-Driven Development que vai de constituição até especificação, planejamento, implementação, revisão e sincronização, com feedback voltando para especificações e regras do projeto.

Bora ver cada fase:

Fase 1: Análise (Entender o Problema)

Aqui definimos visão, personas, métricas de sucesso e restrições do domínio. O resultado são documentos como o Product Brief e relatórios de pesquisa.

Parece burocracia? Na verdade é o oposto: sem isso, a IA vai inventar requisitos por conta própria.

Fase 2: Planejamento (Definir a Solução)

O agente PM produz o PRD (Product Requirements Document) com requisitos funcionais e não-funcionais. Cada requisito funcional tem critérios de aceite no formato Given/When/Then:

## FR-001: Cadastro de Usuário
**Prioridade:** P0 (Crítico)

**Critérios de Aceite:**
- DADO um novo usuário, QUANDO submeter email + senha válidos,
  ENTÃO conta é criada e email de verificação enviado
- DADO um email já existente, QUANDO tentar cadastro,
  ENTÃO erro genérico exibido (anti-enumeração)
- DADO OAuth selecionado, QUANDO autorização bem-sucedida,
  ENTÃO conta criada/vinculada automaticamente

Esse formato é muito bom porque cada AC se traduz diretamente em um teste automatizado.

Fase 3: Solucionamento (Projetar a Arquitetura)

O agente Arquiteto toma decisões técnicas documentadas como ADRs (Architecture Decision Records), um formato proposto por Michael Nygard em 2011. Cada ADR registra o contexto, opções consideradas, decisão, justificativa e consequências:

## ADR-001: Estratégia de Autenticação
**Status:** Aceito
**Contexto:** Precisamos de auth stateless para multi-plataforma
**Opções:** JWT + refresh tokens | Session-based | OAuth-only
**Decisão:** Session cookies (web) + Bearer tokens (mobile/API)
**Justificativa:** Cookies são mais seguros para web; Bearer para mobile
**Consequências:** Fluxo dual de auth, configuração CORS, rotação de tokens

Antes de começar a codar, roda uma validação de prontidão que verifica se PRD, UX, arquitetura e stories estão alinhados.

Fase 4: Implementação (Mão no Código)

Aqui entra o código, mas de forma estruturada:

O agente Scrum Master cria o arquivo da story com contexto completo
O agente Arquiteto valida a Definition of Ready (obrigatório)
O agente Dev implementa usando TDD: RED -> GREEN -> REFACTOR por AC
Code review adversarial e multi-perspectiva
Quality gates: testes + build + type-check
Commit, atualizar status, sincronizar artefatos

Fase 5: Revisão (Verificar Qualidade)

Code review de múltiplas perspectivas: arquitetura, segurança, lógica, performance, estilo, acessibilidade. Não é uma olhada rápida, é uma análise adversarial de verdade.

Fase 6: Sincronização (Fechar o Ciclo)

Essa é a fase que todo mundo ignora, mas é crucial: atualizar sprint status, route maps, docs de arquitetura, e as próprias specs. Specs são documentos vivos elas evoluem com a implementação.

Frameworks SDD: Quem Faz o Quê

Existem vários frameworks que implementam SDD na prática. Os principais são:

BMAD (Breakthrough Method for Agile AI-Driven Development) — simula um time ágil completo com múltiplos agentes de IA especializados. É o mais abrangente, cobrindo todo o ciclo de vida.
GitHub Spec-Kit — toolkit do GitHub com processo em 4 fases (Specify → Plan → Tasks → Implement). Bom pra projetos greenfield.
OpenSpec — framework leve e focado em projetos brownfield. Usa abordagem delta (ADDED, MODIFIED, REMOVED) pra gerenciar mudanças incrementais.

Nesse artigo eu citei os três porque eles ajudam a enxergar o espaço como um todo. Mas, pra deixar a explicação concreta, vou usar o BMAD como exemplo principal nesta seção. Ele é o mais didático pra mostrar papéis, handoffs e fluxo completo. As mesmas ideias de specs, readiness, implementação guiada e review continuam valendo quando você usa Spec-Kit, OpenSpec ou qualquer outro workflow parecido.

BMAD como Exemplo Concreto

O BMAD simula um time ágil completo usando agentes de IA especializados. Não estamos falando de pessoas reais: cada “membro” do time é um agente de IA que assume um papel específico. Quando digo “o Arquiteto valida”, é o agente de IA no papel de Arquiteto que faz isso.

Cada tipo de tarefa é roteada pro agente de IA certo:

Tarefa	Agente de IA	Quando usar
Pesquisa, discovery	Agente Analista	Novo domínio, análise de mercado
Requisitos, PRD	Agente PM	Definição de features, criação de FR/NFR
Design técnico	Agente Arquiteto	ADRs, design de sistema, DB schema
UX/Design	Agente UX Designer	Wireframes, componentes, interações
Sprint planning	Agente Scrum Master	Criação de stories, sequenciamento
Implementação	Agente Dev	Execução de stories, código, testes
Qualidade	Agente QA	Estratégia de testes, automação
Fix pequeno (< 3 arquivos)	Quick Flow	Bug fixes, one-liners
Code review	Agente Reviewer	Review adversarial pré-commit

O roteamento funciona de forma intuitiva:

flowchart TB LOGIN["Adicionar login"] --> PM["PM"] BUTTON["Corrigir botão"] --> QF["Quick Flow"] AUTH["Projetar auth"] --> ARCH["Arquiteto"] STORY["Implementar story 5-3"] --> DEV["Dev"] CODE["Revisar código"] --> REV["Reviewer"] accTitle: Exemplos de roteamento de agentes no BMAD accDescr: Um diagrama de roteamento mostrando itens de trabalho sendo enviados aos agentes de PM, Quick Flow, Arquiteto, Dev e Reviewer conforme o tipo de tarefa.

Greenfield vs. Brownfield

O BMAD tem dois fluxos principais:

Greenfield (projeto novo): passa por todas as 6 fases, começando pela análise e discovery
Brownfield (código existente): entra direto na Fase 2 ou 3, já que o código existe e o project context pode ser extraído do próprio codebase

Pra mudanças pequenas (bugs, features simples), existe o Quick Flow: um caminho simplificado onde um único agente de IA faz spec + dev + review, sem passar por todas as fases. Isso evita burocracia desnecessária pra coisas que não precisam de PRD ou arquitetura.

No BMAD, a regra é: toda mudança de código usa um agente BMAD. Em outros frameworks, essa mesma disciplina aparece com nomes e comandos diferentes, mas a ideia continua a mesma: não sair implementando sem contexto, critério e validação.

A Constituição do Projeto

O coração do SDD é um arquivo de constituição do projeto, algo como AGENTS.md, CLAUDE.md ou equivalente na ferramenta que você usa. Ele funciona como a constituição do projeto: um conjunto de regras que é carregado em toda sessão do agente.

AGENTS.md
├── Overview do projeto (o quê, por quê, tech stack)
├── Comandos comuns (build, test, lint, dev)
├── Visão geral da arquitetura (camadas, padrões, restrições)
├── Regras de ouro (princípios inegociáveis)
├── Regras de design system (se projeto UI)
├── Regras de linguagem (código vs UI)
├── Integração BMAD (fases, agentes, comandos)
└── Referências para regras detalhadas (progressive disclosure)

Umas dicas importantes pra essa constituição:

Limite de tamanho: Mantenha abaixo de 200 instruções (~40KB). LLMs seguem consistentemente ~150-200 instruções
Progressive disclosure: Conhecimento específico vai em arquivos de regras por escopo, não na constituição principal
Instruções positivas: Diga o que FAZER, não o que evitar. Em geral, trocar regras negativas por positivas reduz bastante violação de instrução
Efeito primazia/recência: Regras mais violadas vão no início e no final do arquivo

Considerações finais

SDD pode parecer muita estrutura pra quem tá acostumado a simplesmente pedir pra IA “faz aí”. Mas a verdade é que quanto mais complexo o projeto, mais essa estrutura se paga. Segundo o paper TDAD (Test-Driven Agentic Development), TDD com agentes reduz regressões em 70%. E segundo o Scrum.org, times com Definition of Ready/Done bem definidos fazem a transição para workflows com IA muito mais suave.

No próximo artigo da série vamos mergulhar na parte prática: quality gates, estratégia de testes, code review e o checklist completo pra configurar SDD num novo projeto.

Se você tá começando com dev assistido por IA, o conselho é: não tente implementar tudo de uma vez. Comece pela constituição do projeto (AGENTS.md, CLAUDE.md ou equivalente), adicione quality gates básicos (testes + build antes do commit), e vá evoluindo conforme sentir necessidade.