Spec-Driven Development — Escreva Specs que a IA Executa

Como escrever especificações estruturadas que guiam agentes de IA para gerar código correto. Métodos Ralph, CLAUDE.md, templates práticos e exemplos reais.

Spec-Driven Development (SDD) é a prática de escrever especificações detalhadas antes de pedir código à IA. Em vez de "crie uma API de usuários", você escreve um documento que define endpoints, schemas, validações, erros, testes e constraints — e a IA implementa a spec.

A diferença entre um dev que usa IA e um dev que domina IA está na qualidade das specs.

A Filosofia SDD (2026/2027)

Para dominar o SDD, você precisa mudar sua mentalidade sobre como o software é construído. Duas analogias de Geoffrey Huntley definem este novo paradigma:

1. A Roda de Oleiro (Pottery Wheel)

No desenvolvimento tradicional, construímos software como um muro de tijolos (Jenga style): se um tijolo está torto, você tenta consertar aquele tijolo sem derrubar o resto.

Com IA, o software é argila na roda de oleiro. Se o resultado não está bom, você não tenta consertar o código manualmente. Você "joga a argila de volta na roda": ajusta a especificação, melhora o prompt e roda o loop de novo. O código é descartável; a especificação é o ativo permanente.

2. Contexto como um Array (malloc)

Pense no context window da IA como uma memória RAM finita. Cada vez que você envia um arquivo desnecessário ou uma conversa longa, você está "fragmentando" essa memória.

Malloc: No início de cada tarefa, você "aloca" o contexto enviando apenas a spec e os arquivos estritamente necessários.
Tarefa Única: Execute apenas uma tarefa por loop para evitar que o agente "esqueça" o objetivo original (context rot).

O método "Ralph" (Geoffrey Huntley)

O método mais documentado de SDD com agentes de código:

Estrutura do projeto

project/
├── specs/                    # Especificações (fonte de verdade)
│   ├── auth.md               # Spec de autenticação
│   ├── users-crud.md         # Spec de CRUD de usuários
│   └── billing.md            # Spec de cobrança
├── AGENT.md                  # Como buildar/testar (atualizado pelo agente)
├── fix_plan.md               # Tracker de implementação (atualizado pelo agente)
├── PROMPT.md                 # Prompt principal do agente
├── src/
└── tests/

O loop

# Loop Ralph: uma tarefa por iteração
while :; do
  cat PROMPT.md | claude-code
done

Regras do loop:

Uma tarefa por iteração — não sobrecarregue o context window
Specs lidas a cada iteração — o agente re-consulta as specs a cada loop
fix_plan.md atualizado pelo agente — rastreia o que foi feito
Commits após testes passarem — o git é o checkpoint
fix_plan.md regenerado periodicamente — specs mudam, plano se adapta

PROMPT.md (template)

## Objective
Implement the authentication module described in specs/auth.md.

## Current State
- Database schema exists in src/db/schema.ts
- User model defined in src/models/user.ts
- No auth endpoints yet

## Constraints
- Use JWT with 15min expiry for access tokens
- Use bcrypt cost 12 for password hashing
- All endpoints must have input validation
- Write tests before implementation

## Process
1. Read specs/auth.md
2. Update fix_plan.md with remaining tasks
3. Pick the next unchecked task
4. Write tests for it
5. Implement until tests pass
6. Commit with conventional message
7. Mark task as done in fix_plan.md

fix_plan.md (template)

# Fix Plan — Auth Module

## Pending
- [ ] POST /register — endpoint de cadastro
- [ ] POST /login — endpoint de login com JWT
- [ ] POST /refresh — renovação de token
- [ ] Middleware de autenticação
- [ ] Testes de integração

## In Progress
- [ ] GET /me — perfil do usuário autenticado

## Done
- [x] Schema de usuários no banco
- [x] Hash de senha com bcrypt

Como escrever uma spec efetiva

Template de spec

# Spec: [Nome do Módulo]

## Objetivo
[1-2 frases: o que esta spec define]

## Contexto
[Por que isso existe, qual problema resolve]

## Endpoints / Funções / Componentes

### [Nome do endpoint/função]
- **Método**: GET/POST/PUT/DELETE
- **Path**: /api/resource
- **Input**: { field: type, ... }
- **Output**: { field: type, ... }
- **Validações**:
  - Campo X é obrigatório
  - Campo Y deve ser único
- **Erros**:
  - 400: validação falhou
  - 401: não autenticado
  - 404: recurso não encontrado
- **Edge cases**:
  - O que acontece se o recurso já existe?
  - O que acontece com input vazio?

## Testes esperados
- [ ] Retorna 201 com dados válidos
- [ ] Retorna 400 com campo obrigatório faltando
- [ ] Retorna 409 se recurso duplicado
- [ ] Retorna 401 sem token de autenticação

## Constraints
- Performance: resposta < 200ms
- Segurança: rate limiting de 100 req/min
- Compatibilidade: API v1, backward compatible

Regras de ouro

Seja específico sobre formatos — ISO 8601 não "data formatada"
Liste edge cases explicitamente — a IA não adivinha cenários raros
Inclua exemplos de input/output — a IA aprende melhor com exemplos
Defina erros por código HTTP — não "retorna erro"
Especifique testes na spec — se você não diz o que testar, a IA não testa
Mantenha < 200 linhas por spec — specs longas consomem context window
Versione as specs — mudanças de spec devem triggerar re-implementação

CLAUDE.md como living spec

O CLAUDE.md funciona como uma spec global do projeto — regras que o Claude Code lê em toda sessão.

Hierarquia de configuração (Claude Code)

1. Managed policy   → /Library/Application Support/ClaudeCode/CLAUDE.md (org-wide)
2. Project CLAUDE.md → ./CLAUDE.md (equipe)
3. User CLAUDE.md   → ~/.claude/CLAUDE.md (pessoal)
4. Local CLAUDE.md  → ./CLAUDE.local.md (gitignored)
5. Rules            → .claude/rules/*.md (path-scoped)
6. Skills           → .claude/skills/ (demand-loaded)
7. Hooks            → .claude/settings.json (shell commands)

CLAUDE.md efetivo (template)

# Project: [Nome]

## Stack
- TypeScript, Next.js 16, React 19, Tailwind CSS v4
- Go 1.23 backend (Gin), MongoDB, Redis

## Conventions
- 2-space indent, single quotes, trailing commas
- Components in PascalCase, files in kebab-case
- Always use <Link> for internal navigation

## Commands
- pnpm dev: start dev server
- pnpm lint:fix: fix lint errors
- pnpm build: production build

## Rules
- NEVER use Jest — always Vitest
- NEVER commit without running lint:fix
- ALWAYS update sitemap.ts when adding routes
- ALWAYS create opengraph-image.tsx for new landing pages

## After every code change:
1. pnpm lint:fix
2. pnpm format
3. git commit with Conventional Commits

Regras path-scoped (`.claude/rules/`)

# .claude/rules/backend.md
---
paths:
  - "backend/**"
  - "*.go"
---
Use Go 1.23 conventions. Run `go fmt` before committing.
Never use deprecated MongoDB driver v1 APIs.

Erros comuns

Erro	Consequência	Correção
Spec vaga ("crie uma API")	IA inventa comportamento	Liste endpoints, schemas, erros
Muitas specs em uma sessão	Context window sobrecarregado	Uma spec por loop
Specs sem testes	IA gera código sem validação	Liste testes esperados na spec
Specs mutáveis sem re-validação	Código diverge da spec	Regenere fix_plan.md após mudar spec
Sem fix_plan.md	IA repete tarefas ou pula etapas	Tracker obrigatório