Implementação Incremental

Visão Geral

Construa em fatias verticais finas — implemente uma parte, teste-a, verifique-a e, em seguida, expanda. Evite implementar um recurso inteiro de uma vez. Cada incremento deve deixar o sistema em um estado funcional e testável. Esta é a disciplina de execução que torna recursos grandes gerenciáveis.

Quando Usar

• Implementando qualquer alteração em vários arquivos
• Construindo um novo recurso a partir de um detalhamento de tarefas
• Refatorando código existente
• Sempre que você for tentado a escrever mais de ~100 linhas antes de testar

Quando NÃO usar: Alterações em um único arquivo e em uma única função, onde o escopo já é mínimo.

O Ciclo de Incremento

┌──────────────────────────────────────┐
│                                      │
│   Implement ──→ Test ──→ Verify ──┐  │
│       ▲                           │  │
│       └───── Commit ◄─────────────┘  │
│              │                       │
│              ▼                       │
│          Next slice                  │
│                                      │
└──────────────────────────────────────┘

Para cada fatia:

1. Implemente a menor peça completa de funcionalidade
2. Teste — execute a suíte de testes (ou escreva um teste se nenhum existir)
3. Verifique — confirme se a fatia funciona como esperado (testes passam, compilação bem-sucedida, verificação manual)
4. Commit — salve seu progresso com uma mensagem descritiva (veja git-workflow-and-versioning para orientação sobre commits atômicos)
5. Passe para a próxima fatia — continue, não reinicie

Estratégias de Fatiamento

Fatias Verticais (Preferencial)

Construa um caminho completo através da pilha:

Slice 1: Create a task (DB + API + basic UI)
    → Tests pass, user can create a task via the UI

Slice 2: List tasks (query + API + UI)
    → Tests pass, user can see their tasks

Slice 3: Edit a task (update + API + UI)
    → Tests pass, user can modify tasks

Slice 4: Delete a task (delete + API + UI + confirmation)
    → Tests pass, full CRUD complete

Cada fatia entrega funcionalidade ponta a ponta funcionando.

Fatiamento Baseado em Contrato (Contract-First)

Quando backend e frontend precisam se desenvolver em paralelo:

Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
Slice 1a: Implement backend against the contract + API tests
Slice 1b: Implement frontend against mock data matching the contract
Slice 2: Integrate and test end-to-end

Fatiamento Baseado em Risco (Risk-First)

Aborde a parte mais arriscada ou incerta primeiro:

Slice 1: Prove the WebSocket connection works (highest risk)
Slice 2: Build real-time task updates on the proven connection
Slice 3: Add offline support and reconnection

Se a Fatia 1 falhar, você a descobrirá antes de investir nas Fatias 2 e 3.

Regras de Implementação

Regra 0: Simplicidade em Primeiro Lugar

Antes de escrever qualquer código, pergunte: "Qual é a coisa mais simples que pode funcionar?"

Após escrever o código, revise-o com base nestas verificações:

• Isso pode ser feito em menos linhas?
• Essas abstrações justificam sua complexidade?
• Um engenheiro sênior olharia para isso e diria "por que você não fez simplesmente..."?
• Estou construindo para requisitos futuros hipotéticos ou para a tarefa atual?

SIMPLICITY CHECK:
✗ Generic EventBus with middleware pipeline for one notification
✓ Simple function call

✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities

✗ Config-driven form builder for three forms
✓ Three form components

Três linhas de código semelhantes são melhores do que uma abstração prematura. Implemente a versão ingênua e obviamente correta primeiro. Otimize apenas depois que a correção for comprovada com testes.

Regra 0.5: Disciplina de Escopo

Toque apenas no que a tarefa exige.

NÃO:

• "Limpar" código adjacente à sua alteração
• Refatorar importações em arquivos que você não está modificando
• Remover comentários que você não entende completamente
• Adicionar recursos que não estão na especificação porque "parecem úteis"
• Modernizar a sintaxe em arquivos que você está apenas lendo

Se você notar algo que vale a pena melhorar fora do escopo da sua tarefa, anote — não corrija:

NOTICED BUT NOT TOUCHING:
- src/utils/format.ts has an unused import (unrelated to this task)
- The auth middleware could use better error messages (separate task)
→ Want me to create tasks for these?

Regra 1: Uma Coisa de Cada Vez

Cada incremento altera uma coisa lógica. Não misture preocupações:

Ruim: Um commit que adiciona um novo componente, refatora um existente e atualiza a configuração de build.

Bom: Três commits separados — um para cada alteração.

Regra 2: Mantenha Compilável

…