name: designing-before-building description: Use ao iniciar uma funcionalidade, corrigir um bug não trivial ou prestes a escrever código de implementação — antes que qualquer código exista. Sintomas de que você precisa disso: 'é simples, vou só codificar', pegar no editor antes de um design ser aprovado, ou uma ideia que ainda não virou especificação e plano.
Projetar Antes de Construir
Visão Geral
O trabalho flui por cinco estágios, em ordem: Brainstorm → Spec → Plano → Executar → Registrar. Nenhuma implementação começa antes que um design seja articulado e aprovado. A tarefa mais simples é onde suposições não examinadas custam mais caro.
Violar a letra desta regra é violar o seu espírito. "Vou projetar enquanto codifico" não é projetar.
Os Cinco Estágios
- Brainstorm. Explore intenção, restrições e critérios de sucesso. Faça uma pergunta de cada vez. Proponha de 2 a 3 abordagens com trade-offs e uma recomendação. Converja para um design e obtenha aprovação explícita. Nenhum código aqui.
- Spec. Escreva o design aprovado em um documento datado. A especificação é o contrato do que será construído.
- Plano. Decomponha a especificação em um plano de implementação ordenado e revisável antes de tocar no código.
- Executar. Implemente de acordo com o plano, com pontos de verificação de revisão.
- Registrar. Destile o que foi construído e por quê em um registro de decisão (veja
recording-decisions).
Decomponha grandes esforços. Se uma solicitação abranger vários subsistemas independentes, pare e decomponha antes de refinar os detalhes. Cada subprojeto executa seu próprio ciclo, construído em ordem de dependência.
Quando NÃO usar
Edições genuinamente triviais e reversíveis (um erro de digitação, uma linha de log, um valor de configuração) vão direto para Executar. O teste: um palpite errado aqui custaria mais do que a etapa de design? Se sim, projete primeiro.
Racionalizações Comuns
| Desculpa | Realidade |
|---|---|
| "Isso é simples demais para precisar de design" | Tarefas simples escondem suposições. Algumas frases de design são baratas; uma reescrita não é. |
| "Vou projetar enquanto faço" | Código escrito antes do design estar pronto é código reescrito. Design é um ato separado. |
| "O usuário me disse o que construir, isso É o design" | Um pedido afirma o quê, não como. O como é o design. |
| "Explorar o código primeiro me dirá a abordagem" | Exploração informa o design; não substitui a aprovação de um. |
| "Estamos com pressa" | Pressa é exatamente quando design pulado produz trabalho descartável. |
Bandeiras Vermelhas — PARE
- Abrir o editor antes de existir um design aprovado
- "Deixa eu fazer um protótipo rapidinho" (um protótipo sem especificação é escopo não revisado)
- Começar uma mudança em vários arquivos sem plano
- Tratar o pedido de uma linha do usuário como uma especificação pronta
Tudo isso significa: pare, projete, obtenha aprovação, depois construa.
Fundamentação completa: Artigo I da constituição, incluído em engineering-constitution/references/engineering-constitution.md.