Spec-Driven Design

Por muito tempo eu comecei tarefa abrindo o editor e digitando código. Hoje, com agentes de IA escrevendo junto comigo, esse hábito virou gargalo. O código deixou de ser o lugar onde a intenção nasce, virou consequência.

O que nasce primeiro é a especificação, e é ela que dirige o trabalho da IA, do build, dos testes e da revisão. Esse é o coração do Spec-Driven Design (SDD, Design Orientado por Especificações).

Pra organizar e divulgar essa forma de trabalhar, montei o Spec-Driven Guide (SDG), disponível em specdrivenguide.org. Quero compartilhar aqui o porquê dessa virada e como ela muda o dia a dia de quem programa com IA.

Conceitos fundamentais

A virada: do código primeiro para a especificação primeiro

Sean Grove, da OpenAI, abriu o AI Engineer World’s Fair de 2025 com uma fala direta: cerca de 80 a 90% do trabalho do programador é comunicação estruturada, e a especificação é a melhor forma de comunicar o que o software deve fazer. Pra ele, especificações, não prompts e nem código, são a unidade fundamental do que viramos quando programamos com IA.

A ideia é simples na superfície e densa na prática. Em vez de prompt em prompt corrigindo a saída do agente, você escreve um documento que captura intenção, restrições e critérios de aceite. O agente lê esse contrato e executa. Você revisa contra o contrato.

A própria OpenAI publicou o Model Spec, um documento Markdown vivo que descreve os comportamentos esperados dos modelos. Como é linguagem natural, áreas como produto, jurídico, segurança e pesquisa contribuem juntas no mesmo arquivo. A especificação vira ativo compartilhado, não detalhe técnico escondido.

Quem está construindo isso

A virada não está acontecendo num lugar só. Várias frentes empurram o SDD ao mesmo tempo:

• OpenAI, com a fala de Sean Grove e o Model Spec aberto no GitHub.
• GitHub, que abriu o Spec Kit em setembro de 2025, um toolkit pra orientar agentes (Copilot, Claude Code, Gemini CLI) com especificação como contrato.
• Amazon, com o Kiro, IDE agêntico construído desde o início pra SDD, onde a spec vive ao lado do código e edições propagam dos dois lados.
• Tessl, plataforma comercial focada em manter spec e código sincronizados via agentes.
• Spec-Driven Guide, o trabalho que venho desenvolvendo em specdrivenguide.org, com foco em governança operacional do ciclo (protocolos, handoff entre sessões, disciplina de contexto).

Martin Fowler e equipe publicaram um comparativo das três principais ferramentas de SDD em produção, sinal de que o tema saiu do experimento e entrou em pauta de arquitetura.

As 5 fases do ciclo

O SDG estrutura o trabalho em cinco fases, cada uma com entrada, saída e barreira de aprovação clara.

SPEC → PLAN → CODE → TEST → END

Cada fase tem um barreira de aprovação do desenvolvedor. O dev aprova a passagem antes do agente continuar. Isso é o que separa SDD de execução automatizada cega.

Tipos de ciclo: o caminho de cada intenção

As cinco fases são a estrutura universal. O que muda é o tipo de ciclo: a intenção que entra na esteira. Cada um carrega só o contexto necessário pro trabalho, num fluxo próprio.

O escopo macro do SDG continua o mesmo em todos os ciclos: contrato antes da execução, barreira de aprovação do desenvolvedor entre fases, fechamento com backlog sincronizado. O que cada ciclo faz é expandir camadas e tarefas próprias pra consolidar o propósito específico dele.

• land: primeiro contato com um projeto, gera o contexto base (visão, stack, backlog inicial).
• feat: entrega de nova funcionalidade ponta a ponta, do contrato à validação.
• fix: correção de bug com foco em causa raiz e teste de regressão obrigatório.
• docs: produção de artefatos perenes (post, README, ADR, changelog).
• audit: varredura periódica que aponta drift e gera plano de correção.

Mesma estrutura base, expansões diferentes.

VISION → SURVEY → SCOPE → STACK → BACKLOG → END

SPEC → PLAN → CODE → TEST → END

SPEC → PLAN → CODE → TEST → END

SPEC → PLAN → WRITE → REVIEW → END

SPEC → PLAN → ACTION → REVIEW → END

Você abre a sessão com land: ao chegar num repositório novo e o agente já entende stack, convenções e estado atual. Depois disso, feat: e fix: fluem com contexto pronto, e audit: entra periodicamente pra revisar o todo.

SDG não cria burocracia. Não é cerimônia, é trilha. As fases e ciclos existem pra dar previsibilidade ao trabalho com IA, não pra encher reunião. Você adota o que faz sentido pro seu projeto e ignora o resto. Recomendação, não imposição.

O dev vira orquestrador

A maior mudança não está na ferramenta, está na função.

Quando o agente escreve o código, o que sobra pro dev é o que ele já fazia bem antes da IA, só que agora em tempo integral: pensar o problema, definir o contrato, validar o resultado. Você sai do papel de escritor de código e assume o de curador de intenção.

Já comentei sobre isso no post sobre trabalhar em par com LLM, e o ponto se fortalece com SDD. O dev orquestra três coisas:

1. A especificação, garantindo que intenção e restrições estão explícitas, não implícitas.
2. O plano, conferindo se a sequência respeita dependências, custo de contexto e impacto.
3. A entrega, validando contra o checklist da spec e a narrativa técnica do projeto.

Sequestrar código deixou de ser estratégia de carreira. Quem facilita o trabalho da IA, quem traduz negócio em contrato executável, ganha alavancagem que era impensável dois anos atrás.

Os três pilares do Spec-Driven Guide

O SDG se apoia em três princípios que se reforçam:

Spec First: nenhum código existe sem contrato prévio. Se a intenção não cabe num documento, ela não está pronta pra virar software. A spec é a SSoT do ciclo.

Context Integrity: o contexto da sessão é finito e perecível. Protocolos de handoff (tasks.md como SSoT de estado, checkpoint após cada tarefa) impedem deterioração silenciosa. Outro dev ou outro agente continua o trabalho sem perder fio.

Zero-Leak Delivery: cada entrega passa por verificação contra a spec original. Lint, regressão, checklist binário. Não é teatro de qualidade, é barreira de aprovação, e ela bloqueia commit quando algo escapa.

Segurança como preocupação primordial

Em SDD a segurança não é uma camada que você cola depois, ela aparece na spec. Antes do código existir, o contrato de intenção já declara: o que entra, o que sai, quais boundaries existem, o que precisa validação. Spec frouxa gera código frouxo, e código frouxo é onde vulnerabilidade nasce.

A regra base do SDG é bloqueiaem todo limite: nada passa sem validação explícita, nada é concatenado em queries, comandos ou paths sem sanitização. Se o ambiente está incompleto, o sistema falha rápido em vez de seguir num estado ambíguo. Esse rigor vai pra spec, vira checklist da fase TEST e é confrontado antes de qualquer commit.

Quando a IA gera código, isso fica ainda mais relevante. O agente não tem intuição pra atacar a superfície que ele mesmo criou. Quem segura essa ponta é a especificação, o ciclo audit: rodando periodicamente, e a barreira de aprovação do desenvolvedor em cada fase.

Por que isso importa agora

A diferença entre vibe coding e SDD aparece quando o projeto cresce.

Prompt solto funciona pra protótipo de fim de semana. Pra um sistema que vários times tocam, com regras de negócio que mudam toda semana, ele degrada rápido. O agente perde contexto, o código diverge da intenção, ninguém lembra mais por que aquela função existe.

Especificação resolve isso por design. O contrato fica versionado junto com o código, qualquer agente em qualquer sessão recupera o estado, e a revisão humana acontece no lugar onde decisão importa, não na correção de typo.

O mesmo pedido, dois resultados

Pra deixar concreto, imagine uma tarefa simples: criar um endpoint que lista pedidos com filtro por status.

cria um endpoint pra listar pedidos com filtro de status

app.get("/pedidos", async (req, res) => {
  const status = req.query.status;
  const pedidos = await db.query(`SELECT * FROM pedidos WHERE status = '${status}'`);
  res.json(pedidos);
});

## SPEC: GET /pedidos

**Auth:** Bearer token (usuário autenticado) **Query:** `status?`, `page=1`, `perPage=20` (máx 50) **Response 200:** `{ data: Pedido[], pagination: { page, perPage, total } }` **Erros:** 400 `INVALID_QUERY`, 401 `UNAUTHORIZED`

**Pedido (DTO):** `{ id, codigo, total, status, criadoEm }`

> Não vazar: descontos internos, observações, dados do cliente

**Verificação**

1. Status válido devolve lista filtrada e paginada
2. Status inválido devolve 400
3. Sem token devolve 401
4. `perPage` respeita o teto de 50
5. Resposta nunca vaza campo sensível

import { z as validate } from "zod";

const STATUS_VALIDOS = ["pendente", "pago", "cancelado"];
const PER_PAGE_MAX = 50;

const querySchema = validate.object({
  status: validate.enum(STATUS_VALIDOS).optional(),
  page: validate.coerce.number().int().min(1).default(1),
  perPage: validate.coerce.number().int().min(1).max(PER_PAGE_MAX).default(20),
});

app.get("/pedidos", autenticado, async (request, response) => {
  const consultaValida = querySchema.safeParse(request.query);
  if (!consultaValida.success) {
    return response.status(400).json({ error: "INVALID_QUERY" });
  }

  const { status, page, perPage } = consultaValida.data;
  const pedidosPaginados = await pedidoRepository.listar({
    status,
    page,
    perPage,
  });

  return response.status(200).json(pedidosPaginados);
});

A diferença não está no agente, está no contrato. Sem spec, o LLM otimiza pra parecer pronto. Com spec, ele otimiza pra atender ao critério.

Existe contraponto, e isso é saudável

Nem todo mundo no ecossistema concorda com a virada pra spec antes de tudo. Fabio Akita publicou em abril de 2026 o Clean Code para Agentes de IA, defendendo que o leitor primário do código mudou (agora é o LLM, não o humano), e que a adaptação certa é repensar os princípios de Clean Code, não empilhar mais camadas de processo.

A crítica é válida e ajuda a calibrar a prática. Spec frouxa ou hipertrofiada vira ruído tanto quanto código frouxo. O detalhe que vale notar é que mesmo o Akita, defendendo simplicidade, parte de uma base de processo: ele cita Uncle Bob, o Manifesto Ágil e a tradição do XP (Extreme Programming, Programação Extrema). Não está pregando ausência de método, está pregando outro método.

E é aí que SDD se encaixa pra equipe. Quando o time tem devs de níveis diferentes, sem um guia compartilhado o atrito sobe rápido: cada um interpreta a tarefa de um jeito, o agente recebe contexto inconsistente, a revisão vira retrabalho. Um processo escrito (qualquer um) reduz esse atrito por design.

Pessoas novas chegam com mapa, pessoas experientes deixam o automático visível pro time, o agente recebe spec parecida em qualquer cabeça que escreva. SDD é uma escolha entre as opções disponíveis, e o contraponto do Akita ajuda a manter o pé no chão: o objetivo é entregar software que funciona, não cumprir cerimônia.

Como começar

O caminho mais curto pra entrar em SDD:

1. Visite specdrivenguide.org e leia os protocolos de cada fase.
2. Escolha um projeto pequeno seu, de preferência um que você já queria refatorar.
3. Antes de tocar no código, escreva a spec do próximo ciclo. Uma frase de objetivo, contratos de entrada e saída, checklist de verificação.
4. Use um agente (Claude Code, Copilot, Gemini, Kiro) com a spec como contexto base.
5. Valide cada fase contra o barreira de aprovação do desenvolvedor antes de seguir.

Se quiser automatizar o ciclo, o SDG agents CLI cuida do bootstrap, dos handoffs e do versionamento. Trato isso com mais profundidade no post de portfolio do Spec-Driven Guide.

A tecnologia mudou o que escrevemos, e isso muda o que importa. Código vai continuar existindo, claro, mas o ativo principal agora é a clareza da intenção. Spec-Driven Design é o nome dessa virada.

Bons contratos e bons códigos!

Referências

• Spec-Driven Guide (specdrivenguide.org)
• The New Code, Sean Grove na OpenAI (YouTube)
• GitHub Spec Kit no GitHub Blog
• Repositório github/spec-kit
• Amazon Kiro: IDE agêntico para SDD
• Martin Fowler: comparativo Kiro, Spec Kit e Tessl
• Fabio Akita: Clean Code para Agentes de IA (contraponto)
• Post anterior: trabalhando em par com LLM (IA)