Guia ensina a escrever documentos de design que realmente ajudam

Por que escrever um documento de design

Michael Lynch, que escreveu design docs na Google, na Microsoft e em empresas próprias, argumenta que um bom documento de design pode poupar anos de desenvolvimento: ele força o autor a pensar nas decisões importantes antes de implementar a solução errada e é a melhor forma de coordenar decisões entre colegas e times parceiros. Como bons exemplos públicos são raros - ele diz nunca ter visto um design doc público de alta qualidade -, Lynch escreveu um do zero, baseado num aplicativo web real que está construindo, criando-o antes de escrever qualquer código.

Quando vale a pena

Quanto mais complexo ou arriscado o projeto, mais valioso o documento. Perguntas-guia: várias pessoas vão coordenar o trabalho? O projeto levará mais de três meses de desenvolvimento em tempo integral? Rodará em produção por anos? Exige colaboração entre times? Requisitos são ambíguos? Há riscos catastróficos evitáveis na fase de design, como falhas de segurança ou riscos legais? Uma resposta afirmativa já justifica o esforço; duas ou mais o tornam quase certo.

O investimento não tem regra universal: pode ser uma página única ou um documento de 50 páginas com aprovação de cinco times. Depende de metas, riscos, prazos e cultura da equipe - às vezes, o investimento certo é zero.

O que merece entrar no documento

O critério central de Lynch é simples: qual é a penalidade por errar? Decisões permanentes pertencem ao documento; as triviais, não. Se você constrói uma aplicação web em C++ e descobre 200 mil linhas depois que Ruby on Rails seria melhor, está preso - uma reescrita do zero nunca funcionaria. Já escolher entre mostrar 100 artigos de uma vez ou 25 por vez com botão "carregar mais" não importa: corrigir depois leva algumas horas, e não vale gastar ciclos de revisão discutindo isso.

Detalhar tudo equivaleria a escrever a implementação na fase de design, o que derrota o propósito do documento.

Anatomia do documento

Lynch apresenta seções comuns, das quais o autor deve escolher um subconjunto adequado:

Título e metadados: um nome curto e evocativo (como "RecencyBank" para uma camada de cache) e contexto básico - autor, data, URL canônica, quem aprovou e quando.
Objetivo e histórico: uma frase simples explicando o propósito na primeira página, seguida do contexto - por que o time assumiu o projeto, qual problema resolve, houve tentativas anteriores. O documento precisa fazer sentido sem explicação oral prévia.
Metas e não-metas: as metas devem expressar impacto, não detalhes internos - "minimizar interrupções em deploys" é melhor que "adicionar Kubernetes aos servidores". As não-metas evitam que leitores presumam escopo errado.
Cenários e diagramas: retratos do sistema pronto em uso e desenhos que mostram fluxo de dados, componentes e protocolos. Lynch recomenda ferramentas editáveis como Excalidraw, draw.io e Google Drawings, ou linguagens como Mermaid, D2 e Graphviz - e menciona ter boa experiência usando um LLM para gerar código de diagramas. Evite fotografar quadros brancos: o rascunho fica congelado.
Glossário: define termos internos, pensando em novatos e times externos - embora usar termos reconhecíveis inline seja melhor ainda.
Restrições, SLOs e monitoramento: restrições de orçamento ou infraestrutura dão contexto às escolhas. SLOs traduzem metas vagas como "desempenho no mobile" em números objetivos - por exemplo, latência mediana de requisições HTTP em até 200ms. SLAs são SLOs com penalidade financeira, incomuns internamente. O monitoramento define como detectar falhas em produção.
Cronograma e interfaces: marcos que entregam artefatos úteis - começar com uma interface usando dados fictícios revela mal-entendidos com clientes cedo. As interfaces descrevem UI (esboços simples), APIs e formatos de arquivo, com exemplos em Go de como substituir uma dependência direta por uma interface cacheável.
Dependências: linguagem, bibliotecas e infraestrutura têm grande impacto na manutenção de longo prazo. Priorize pensar nas difíceis de trocar - linguagens e armazenamento -, não em serviços substituíveis em uma tarde.
Segurança, privacidade e aspectos legais: considerar ameaças, superfície de ataque e limites de confiança; mesmo que as ameaças pareçam remotas, documentar o raciocínio pode levar revisores a apontar riscos ignorados. Privacidade trata de dados sensíveis, retenção e acesso. Em domínios regulados, a seção legal garante conformidade - inclusive definir licença de código aberto.
Logs e issues abertas/resolvidas: registrar eventos críticos facilita investigação de bugs e incidentes. A seção de issues abertas documenta problemas não resolvidos com opções e próximos passos; ao resolver, move-se a discussão para issues resolvidas, preservando o histórico.
Alternativas consideradas: antecipa a pergunta "por que não fizeram X?". Lynch considera exagero documentar toda ideia rejeitada; bastam poucas linhas sobre alternativas fortes e por que não serviram.

Revisão

O documento só cumpre seu papel quando circula. O texto encerra apontando para técnicas de obter feedback útil que fazem o projeto avançar, em vez de estagnar em discussões confusas - conteúdo prometido para um texto complementar. O artigo é trecho do livro "Refactoring English: Effective Writing for Software Developers", de Lynch.