Desenvolvimento Guiado por Especificação

Visão Geral

Escreva uma especificação estruturada antes de escrever qualquer código. A especificação é a fonte de verdade compartilhada 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ção tem quatro fases. 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 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
   

3. Estrutura do Projeto — Onde o código fonte reside, onde os testes vão, onde a documentação pertence.

   src/           → Application source code
   src/components → React components
   src/lib        → Shared utilities
   tests/         → Unit and integration tests
   e2e/           → End-to-end tests
   docs/          → Documentation
   

4. Estilo de Código — Um trecho de código real mostrando seu estilo vale mais que três parágrafos descrevendo-o. Inclua convenções de nomenclatura, regras de formatação e exemplos de saída boa.

5. Estratégia de Testes — Qual framework, onde os testes residem, expectativas de cobertura, quais níveis de teste para quais preocupações.

6. Limites — Sistema de três níveis:

   • Sempre fazer: Executar testes antes de commits, seguir convenções de nomenclatura, validar entradas
   • Perguntar primeiro: Mudanças no esquema do banco de dados, adicionar dependências, mudar configuração de CI
   • Nunca fazer: Commitar segredos, editar diretórios de fornecedores, remover testes falhos sem aprovação

Modelo de especificação:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Reformule instruções como critérios de sucesso. Ao receber requisitos vagos, traduza-os em condições concretas:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

Isso permite que você itere, tente novamente e resolva problemas em direção a um objetivo claro, em vez de adivinhar o que "mais rápido" significa.

Fase 2: Planejar

Com a especificação validada, gere um plano de implementação técnica:

1. Identifique os principais componentes e suas dependências
2. Determine a ordem de implementação (o que deve ser construído primeiro)
3. Anote riscos e estratégias de mitigação
4. Identifique o que pode ser construído em paralelo vs. o que deve ser sequencial

…