Especificar o comportamento.
Provar com testes.
Só então implementar.

01

A pergunta de partida

Agentes de código escrevem software rápido demais para os nossos processos antigos. A pergunta que este guia responde não é “a IA escreve código bom?”, e sim:

Como tornamos o desenvolvimento assistido por IA repetível, auditável e seguro — sem abrir mão de velocidade?

02

O que é Spec-Driven Development

Especificação (spec), neste guia, é um documento curto e versionado que descreve o comportamento observável que se quer de uma mudança: cenários de entrada e saída, critérios de aceitação e — tão importante quanto — os não-objetivos, aquilo que a mudança deliberadamente não fará.

Spec-Driven Development é a prática de tratar essa especificação como a fonte compartilhada da verdade sobre a intenção: humanos a escrevem e aprovam, agentes a leem para planejar e implementar, revisores a usam como régua do que foi entregue. O código diz o que o sistema faz; a spec diz o que ele deveria fazer — e é contra ela que se discute.

O que a spec não é

• Não é um documento de requisitos de 40 páginas: é curta, testável e viva.
• Não é o prompt: o prompt aponta para a spec; a spec sobrevive à conversa.
• Não substitui testes: ela define o contrato; os testes o tornam executável (seção 06).

03

Três níveis de maturidade

O modelo de três níveis abaixo vem da análise de Böckeler sobre as ferramentas de SDD existentes. Ele é útil porque separa práticas que costumam ser confundidas sob o mesmo nome.

04

O ciclo combinado SDD + TDD

Sete etapas, três portões humanos. As etapas 4–6 são o clássico RED–GREEN–REFACTOR de Kent Beck; as demais dão ao agente contexto, contrato e revisão. Nenhuma etapa é pulada — nem pelo agente, nem por pressa.

1. 1

   Descobrir

   O agente lê o código, docs e convenções relevantes. Saída: resumo do contexto e lista de dúvidas. Nenhum código é escrito.

2. 2

   Especificar

   Comportamento observável em cenários numerados + não-objetivos + critérios de aceitação. ⛔ Portão: humano aprova a spec.

3. 3

   Planejar

   Arquitetura da mudança, riscos, decisões técnicas e plano de testes. ⛔ Portão: humano aprova o plano.

4. 4

   RED

   Escrever um teste que expressa um cenário da spec e vê-lo falhar. A falha prova que o teste mede a lacuna, não a sorte.

5. 5

   GREEN

   A menor implementação que faz o teste passar. Sem generalização especulativa, sem “aproveitar para arrumar”.

6. 6

   REFACTOR

   Melhorar nomes, remover duplicação, simplificar — sem mudar comportamento. Testes verdes antes e depois.

7. 7

   Revisar

   Diff comparado à spec, testes e evidências de execução. ⛔ Portão: humano dá o veredito final.

05

Quem decide, quem executa, quem confere

A divisão de responsabilidades é o coração da segurança do processo: o agente nunca é juiz do próprio trabalho, e o humano nunca gasta tempo no que a máquina faz melhor.

Segundo a documentação da Anthropic, o Claude Code lê a base de código, edita arquivos, executa comandos e se integra ao fluxo de ferramentas do desenvolvedor — exatamente a coluna do meio. As boas práticas oficiais reforçam: dê ao agente uma forma de verificar o próprio trabalho (testes!) e corrija o rumo cedo.

06

Por que SDD não substitui TDD

A spec define o contrato; os testes tornam o contrato executável. Um sem o outro deixa uma lacuna que agentes de código exploram sem má-fé — e com consequências.

O TDD, na linhagem de Kent Beck (Test-Driven Development: By Example, 2002), acrescenta algo que a spec sozinha não dá: a prova da lacuna. Ver o teste falhar antes de implementar demonstra que o teste mede o comportamento novo — e não que passa por acidente. Com agentes, esse degrau vira o portão anti-alucinação mais barato do processo.

07

Exemplo completo: API de consulta de empresas por CNPJ

Um caso realista para produtos de dados corporativos: um endpoint de consulta cadastral por CNPJ, com limite de uso por chave de API e trilha de auditoria. Abaixo, os artefatos reais de um ciclo — spec, teste em RED, implementação mínima e checklist de evidências.

7.1 · A especificação specs/001-company-search/spec.md

# Spec 001 — Consulta de empresa por CNPJ

## Objetivo
Expor `GET /v1/empresas/{cnpj}` para consulta pontual de dados
cadastrais, com limite de uso por chave de API e trilha de
auditoria completa por requisição.

## Comportamento observável
- S1. CNPJ válido e existente → 200 com `razaoSocial`, `cnpj`
  (normalizado, somente dígitos), `situacaoCadastral`, `atualizadoEm`.
- S2. CNPJ com formato ou dígito verificador inválido → 400 com
  corpo `{ "erro": "CNPJ_INVALIDO" }`. Nenhuma consulta à base ocorre.
- S3. CNPJ válido porém inexistente → 404 com `{ "erro": "NAO_ENCONTRADO" }`.
- S4. Chave de API acima de 60 req/min → 429 com cabeçalho
  `Retry-After` em segundos. A requisição excedente não consulta a base.
- S5. Toda requisição (atendida ou rejeitada) gera exatamente um
  registro de auditoria: `requestId`, hash da chave de API, CNPJ
  normalizado, decisão (`ATENDIDO` | `REJEITADO_VALIDACAO` |
  `NAO_ENCONTRADO` | `LIMITADO`) e timestamp UTC.

## Não-objetivos
- Busca por razão social ou nome fantasia.
- Consulta em lote.
- Garantia de frescor dos dados cadastrais (spec 002 tratará disso).

## Critérios de aceitação
- [ ] S1–S5 cobertos por testes que falharam antes da implementação.
- [ ] Validação de CNPJ usa o algoritmo oficial de módulo 11.
- [ ] A chave de API nunca aparece em claro na auditoria.
- [ ] `Retry-After` calculado a partir da janela real, não valor fixo.

Repare no que faz esta spec funcionar com agentes: cenários numerados (testes e commits citam “S2”), saídas observáveis (status, corpo, cabeçalho — nada de “deve ser robusto”), e não-objetivos que impedem o agente de “aproveitar” para implementar busca por nome.

7.2 · RED — o teste que prova a lacuna tests/consultar-empresa.test.ts

import { describe, expect, it } from "vitest";
import { consultarEmpresa } from "../src/consultar-empresa";
import { contextoDeTeste } from "./apoio/contexto";

describe("S2 — CNPJ inválido", () => {
  it("responde 400, não consulta a base e audita a rejeição", async () => {
    const ctx = contextoDeTeste();

    const resposta = await consultarEmpresa("11.111.111/1111-11", ctx);

    expect(resposta.status).toBe(400);
    expect(resposta.corpo).toEqual({ erro: "CNPJ_INVALIDO" });
    expect(ctx.base.consultas).toHaveLength(0);
    expect(ctx.auditoria.registros).toHaveLength(1);
    expect(ctx.auditoria.registros[0]).toMatchObject({
      decisao: "REJEITADO_VALIDACAO",
      cnpj: "11111111111111",
    });
  });
});

FAIL  tests/consultar-empresa.test.ts
  ✗ S2 — CNPJ inválido › responde 400, não consulta a base e audita a rejeição
    Error: Failed to resolve import "../src/consultar-empresa"

7.3 · GREEN — a implementação mínima src/consultar-empresa.ts

export interface RegistroAuditoria {
  cnpj: string;
  decisao: "ATENDIDO" | "REJEITADO_VALIDACAO" | "NAO_ENCONTRADO" | "LIMITADO";
}

export interface Contexto {
  auditoria: { registrar(evento: RegistroAuditoria): void };
}

const PESOS_DV1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
const PESOS_DV2 = [6, ...PESOS_DV1];

function digitoVerificador(digitos: number[], pesos: number[]): number {
  const soma = pesos.reduce((acc, peso, i) => acc + peso * digitos[i], 0);
  const resto = soma % 11;
  return resto < 2 ? 0 : 11 - resto;
}

export function cnpjEhValido(cnpj: string): boolean {
  const digitos = [...cnpj].map(Number);
  if (digitos.length !== 14 || new Set(digitos).size === 1) return false;
  return (
    digitos[12] === digitoVerificador(digitos.slice(0, 12), PESOS_DV1) &&
    digitos[13] === digitoVerificador(digitos.slice(0, 13), PESOS_DV2)
  );
}

export async function consultarEmpresa(entrada: string, ctx: Contexto) {
  const cnpj = entrada.replace(/\D/g, "");
  if (!cnpjEhValido(cnpj)) {
    ctx.auditoria.registrar({ cnpj, decisao: "REJEITADO_VALIDACAO" });
    return { status: 400, corpo: { erro: "CNPJ_INVALIDO" } };
  }
  // S1, S3 e S4 pertencem aos próximos ciclos RED→GREEN.
  throw new Error("Cenário ainda não especificado neste ciclo (ver spec S1/S3/S4)");
}

“Mínima” não significa descuidada: o algoritmo de módulo 11 está correto e completo porque o cenário S2 o exige (critério de aceitação). Mas S1, S3 e S4 não foram implementados — cada um terá seu próprio RED primeiro. O throw explícito é honesto: o agente não finge um caminho feliz que nenhum teste pediu ainda.

7.4 · REFACTOR + evidências specs/001-company-search/evidence.md

# Evidência — Spec 001, ciclo S2

## Refatoração (comportamento inalterado)
- [ ] Testes verdes ANTES da refatoração (saída colada abaixo).
- [ ] Nomes revisados: domínio em português consistente com a spec.
- [ ] Duplicação extraída (pesos do DV declarados uma única vez).
- [ ] Testes verdes DEPOIS da refatoração (saída colada abaixo).

## Evidência de execução (colar saídas reais, nunca resumir)
- [ ] Saída do Vitest em RED (teste falhando, com a razão da falha).
- [ ] Saída do Vitest em GREEN (a suíte do ciclo passando).
- [ ] Prova de robustez: mutação manual (trocar um peso do DV)
      faz o teste falhar — o teste morde.
- [ ] Nenhuma asserção foi enfraquecida para “fazer passar”.

## Rastreabilidade
- [ ] Commits citam o cenário (ex.: "test: RED para S2 da spec 001").
- [ ] spec.md atualizada se a revisão mudou o comportamento acordado.

08

Workflow Claude Code: prompts por etapa

Nunca diga ao agente “construa a API inteira”. Um pedido vago produz um lote gigante de código sem trilha de verificação — o oposto do que este processo busca. Em vez disso, conduza o ciclo com um prompt por etapa, parando nos portões. Os prompts abaixo são copiáveis e usam o exemplo do CNPJ; adapte os nomes ao seu caso.

Leia CLAUDE.md e docs/architecture.md. Depois explore src/ e tests/
no que for relevante para consulta de empresas.

Não escreva nem altere código nesta etapa.

Devolva: (1) resumo dos pontos de entrada e convenções de teste,
(2) riscos e acoplamentos que você identificou,
(3) lista de dúvidas que eu preciso responder antes da spec.

Com base na exploração e nas minhas respostas, rascunhe
specs/001-company-search/spec.md com:
- objetivo em um parágrafo;
- cenários numerados (S1, S2, ...) com entrada e saída observáveis
  (status HTTP, corpo, cabeçalhos) — nada de adjetivos vagos;
- não-objetivos explícitos;
- critérios de aceitação verificáveis por teste automatizado;
- seção "Assunções e dúvidas" com tudo o que você assumiu.

Pare após escrever o arquivo. Eu vou revisar e aprovar a spec
antes de qualquer plano ou código.

A spec specs/001-company-search/spec.md está aprovada.

Escreva specs/001-company-search/plan.md com:
- arquitetura da mudança (módulos novos/alterados e por quê);
- decisões técnicas com alternativas descartadas
  (ex.: algoritmo de rate limiting e onde vive o estado);
- riscos e como cada um será testado;
- ordem dos ciclos RED→GREEN (um cenário por ciclo);
- specs/001-company-search/tasks.md com tarefas pequenas e
  independentes.

Não implemente nada. Pare para minha revisão do plano.

Plano aprovado. Comece pelo cenário S2 da spec.

Escreva SOMENTE o teste (Vitest/TypeScript) que expressa o S2,
seguindo as convenções de tests/. Não crie a implementação.

Rode a suíte e cole a saída completa mostrando o teste falhando.
Se o teste passar sem implementação, pare e me avise: ou o teste
está errado, ou o comportamento já existe.

O teste do S2 está em RED (saída registrada).

Implemente o MÍNIMO necessário para esse teste passar, sem
antecipar os cenários S1, S3 e S4 e sem tocar em outros arquivos
além do necessário.

Rode a suíte inteira e cole a saída completa. Se algum teste
antigo quebrar, pare e reporte antes de tentar consertar.

Com a suíte verde, refatore o que este ciclo tocou:
nomes, duplicação e estrutura — sem mudar comportamento
observável e sem alterar nenhuma asserção de teste.

Rode a suíte antes e depois; cole as duas saídas.
Liste cada refatoração feita e por quê, em uma linha cada.

Compare o diff completo deste ciclo com a spec
specs/001-company-search/spec.md:

- Cada mudança rastreia para qual cenário?
- Algum comportamento implementado que a spec não pede?
- Algum critério de aceitação sem teste correspondente?

Atualize specs/001-company-search/evidence.md com as saídas de
teste em RED e em GREEN e o checklist preenchido. Aponte
desvios encontrados em vez de corrigi-los por conta própria —
a decisão de corrigir é minha.

09

Estrutura de repositório recomendada

A estrutura abaixo mantém specs versionadas ao lado do código (spec-anchored) e dá ao agente pontos de leitura previsíveis.

.
├── CLAUDE.md                     # contexto permanente para o agente:
│                                 # comandos, convenções, o que nunca fazer
├── docs/
│   └── architecture.md           # visão de arquitetura estável
├── specs/
│   └── 001-company-search/
│       ├── spec.md               # comportamento, não-objetivos, aceitação
│       ├── plan.md               # arquitetura da mudança e riscos
│       ├── tasks.md              # tarefas pequenas, uma por ciclo
│       └── evidence.md           # saídas de teste RED/GREEN, checklist
├── src/                          # implementação
└── tests/                        # a spec executável

• CLAUDE.md é lido pelo Claude Code no início da sessão: mantenha-o curto e prescritivo (comandos de build/teste, convenções, proibições). A recomendação oficial da Anthropic é explícita: conciso e atualizado com frequência.
• Uma pasta por spec, numerada: o número vira referência em commits, PRs e conversas (“ciclo S2 da 001”).
• evidence.md é o que transforma “confia em mim” em “confere aí”: saídas reais de teste, coladas, com data.

10

Anti-padrões — e o portão que bloqueia cada um

Cada processo falha do jeito que seus incentivos permitem. Estes são os sete modos de falha que mais vemos em adoções de SDD com agentes, cada um pareado com um portão barato de implantar.

Spec vaga

“Melhore a validação de CNPJ” não é especificação — é desejo. O agente preenche as lacunas com suposições plausíveis e erradas.

Portão: cenários numerados com entrada e saída observáveis; spec sem cenário testável não passa da revisão.

Implementar antes do teste falhar

Sem o RED, ninguém sabe se o teste mede algo. Testes escritos depois tendem a fotografar a implementação, não o contrato.

Portão: o PR mostra a saída do teste falhando antes da implementação (commit ou evidence.md).

Autocertificação do agente

“Rodei tudo e passou” é narrativa, não evidência. Agentes erram com confiança — e resumos escondem o erro.

Portão: CI roda os mesmos testes de forma independente; evidências são saídas coladas, nunca parafraseadas.

Mudança gigante

Um diff de 3.000 linhas gerado em uma tarde é irrevissável na prática — a revisão vira teatro.

Portão: tasks.md fatia o trabalho; um cenário por ciclo, um ciclo por PR quando possível.

Spec desatualizada

Se o comportamento muda e a spec não, a “fonte da verdade” vira fonte de confusão — pior que não ter spec.

Portão: PR que altera comportamento observável precisa tocar a spec correspondente; deriva de spec é métrica acompanhada.

Suposições ocultas

O agente decide sozinho que “rate limit por IP serve” e a decisão só aparece em produção.

Portão: seção obrigatória “Assunções e dúvidas” na spec; o agente é instruído a parar e perguntar, não a presumir.

Teste frágil superajustado

Testes que fotografam detalhes internos (ordem de chamadas, mensagens exatas de log) quebram a cada refatoração e ensinam o time a ignorá-los.

Portão: testar o comportamento observável da spec, não a implementação; mutação (manual ou ferramenta) como prova de que o teste morde.

11

Roadmap de adoção

Não adote por decreto. A sequência abaixo constrói prova antes de construir obrigação — cada fase só começa quando a anterior mostrou números.

1. Fase 1 Piloto

   Um time voluntário, um serviço de risco moderado, 4–6 semanas. Specs completas + ciclo RED–GREEN–REFACTOR em todas as mudanças. Coleta de linha de base das métricas antes de começar.

2. Fase 2 Padronizar templates

   O que o piloto validou vira template: spec.md, plan.md, evidence.md e CLAUDE.md padrão. Prompts por etapa entram no repositório para qualquer pessoa reutilizar. Nada de processo em wiki morta — os templates vivem junto do código.

3. Fase 3 Portões no CI

   Os portões manuais viram verificações automáticas: PR sem spec referenciada não passa; suíte roda em ambiente independente do agente; mudança de comportamento sem mudança de spec é sinalizada para revisão humana.

4. Fase 4 Medir e ajustar

   Com o processo rodando, as métricas dizem onde apertar e onde afrouxar. Portão que nunca barra nada é atrito; portão que barra tudo é gargalo. Ambos merecem revisão.

As cinco métricas que importam

12

Perguntas frequentes

13

Fontes e leituras

Fontes consultadas em 17 de julho de 2026. As posições recomendadas neste guia (por exemplo, spec-anchored como padrão) são nossas; o que cada fonte afirma está resumido abaixo, junto ao link.

• GitHub Spec Kit — toolkit open source que posiciona especificações como artefatos de nível mais alto e estrutura o fluxo constitution → specify → plan → tasks.
• GitHub Blog — Spec-driven development with AI — apresentação oficial do Spec Kit e do argumento por desenvolvimento orientado a especificação com IA.
• Birgitta Böckeler (martinfowler.com) — Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl — análise de 15/10/2025: a definição de SDD ainda é fluida; origem do modelo spec-first / spec-anchored / spec-as-source usado aqui; a verificação continua essencial.
• Anthropic — Claude Code: visão geral — o que o agente faz: lê a base de código, edita arquivos, executa comandos e se integra às ferramentas do desenvolvedor.
• Anthropic — Claude Code: boas práticas — dê ao agente como verificar o próprio trabalho; explore, depois planeje, depois code; forneça contexto específico; CLAUDE.md conciso; corrija o rumo cedo.
• Kent Beck — Test-Driven Development: By Example (Addison-Wesley, 2002) — a linhagem canônica do ciclo RED–GREEN–REFACTOR que a seção 04 incorpora.