Desenvolvimento Guiado por Especificações

Visão Geral

Escreva uma especificação estruturada antes de escrever qualquer código. A especificação é a fonte compartilhada da verdade entre você e o engenheiro humano — ela define o que estamos construindo, por quê e como saberemos que está pronto. Código sem especificação é adivinhação.

Quando Usar

• Iniciando um novo projeto ou funcionalidade
• Requisitos são ambíguos ou incompletos
• A mudança afeta múltiplos arquivos ou módulos
• Você está prestes a tomar uma decisão arquitetural
• A tarefa levaria mais de 30 minutos para ser implementada

Quando NÃO usar: Correções de uma linha, correções de digitação ou mudanças onde os requisitos são inequívocos e autossuficientes.

O Fluxo de Trabalho Controlado

O desenvolvimento guiado por especificações tem quatro fases, precedidas por uma verificação de escopo (Fase 0) que é ativada apenas quando uma solicitação agrupa várias capacidades testáveis independentemente. Não avance para a próxima fase até que a atual seja validada.

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

Fase 0: Verificação de Escopo

A maioria das solicitações descreve uma capacidade. Se esta o fizer, pule esta fase e vá direto para Especificar — a Fase 0 existe para a exceção, não para a regra, e não impõe hierarquia a funcionalidades de capacidade única.

Detecção. Decomponha antes de especificar quando um único requisito agrupa várias capacidades testáveis independentemente:

• O requisito nomeia capacidades distintas com seus próprios consumidores ou dados (por exemplo, identidade, faturamento, notificações, relatórios)
• Critérios de aceitação se agrupam em conjuntos que poderiam ser lançados e verificados separadamente
• Uma capacidade poderia ser removida ou substituída sem reescrever os requisitos das outras

Proponha um mapa de capacidades antes de escrever qualquer especificação. Pequeno e revisável — uma tabela de módulos mais uma ordem de construção, não um plano de projeto:

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting

• IDs de módulo estáveis. Em kebab-case, escolhidos uma vez, nunca renomeados no meio da iniciativa. Especificações, planos e comandos downstream selecionam trabalho por esses IDs em vez de adivinhar qual especificação está ativa.
• Direção de dependência, sem ciclos. As setas apontam em uma direção. Se dois módulos precisam um do outro, eles são um único módulo.
• Interfaces vivem na fronteira. O mapa registra que billing depende de identity; o contrato entre eles pertence à especificação do módulo provedor (veja api-and-interface-design para projetá-lo).

O mapa é controlado como todas as fases. O humano revisa os limites do módulo, a direção da dependência e a ordem de construção antes que qualquer especificação de módulo seja escrita. Errar o mapa é caro; revisar dez linhas não é.

Em seguida, recursivamente por módulo. Execute Especificar → Planejar → Tarefas → Implementar para cada módulo na ordem de dependência. Cada módulo recebe sua própria especificação, focada no objetivo, limites e critérios de sucesso desse módulo. Salve o mapa aprovado na raiz do projeto e a especificação de cada módulo ao lado dela, nomeada pelo ID do módulo (SPEC-identity.md, SPEC-billing.md) — o mapa, não a adivinhação do nome do arquivo, é o índice do que existe.

Fase 1: Especificar

Comece com uma visão de alto nível. Faça perguntas esclarecedoras ao humano até que os requisitos sejam concretos.

Exponha as suposições imediatamente. Antes de escrever qualquer conteúdo da especificação, liste o que você está assumindo:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Não preencha silenciosamente requisitos ambíguos. O propósito inteiro da especificação é expor mal-entendidos antes que o código seja escrito — suposições são a forma mais perigosa de mal-entendido.

Escreva um documento de especificação cobrindo estas seis áreas principais:

1. Objetivo — O que estamos construindo e por quê? Quem é o usuário? Como é o sucesso?

2. Comandos — Comandos executáveis completos com flags, não apenas nomes de ferramentas.

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev
   

…