Template Design Doc

Design docs de engenharia: como descrever como

Um design doc de engenharia (também "tech spec") descreve como uma mudança não trivial será construída. Se o PRD diz o que e por que, o design doc diz como — e, mais importante, por que esse como e não outro. O formato se popularizou dentro do Google, onde todo engenheiro sênior escreve e revisa design docs como parte do ofício. A indústria absorveu o padrão via escritos públicos de Will Larson (Staff Engineer) e Camille Fournier (The Manager's Path) e por blogs de Stripe, GitHub e Twitter.

Um design doc típico contém: contexto (estado atual do sistema), goals e non-goals, proposta de design (arquitetura, modelo de dados, APIs, diagramas de sequência), alternativas consideradas com trade-offs explícitos, plano de migração para dados e tráfego legados, estratégia de rollback se a mudança explodir em produção, open questions e uma lista de aprovadores cujo sign-off é necessário. O tamanho varia entre três e dez páginas para features típicas e pode ir bem além em projetos fundacionais.

PRD vs design doc vs ADR vs RFC

Os quatro formatos se sobrepõem e geram confusão. PRD é para stakeholders e responde o que/por que. Design doc é para engenheiros e responde como. RFC (Request for Comments) é o estágio de proposta: convida ao debate antes do consenso. ADR (Architecture Decision Record) é um artefato de decisão única — curto, imutável, captura contexto, decisão e consequências de uma escolha. Muitos times usam RFC para propor, design doc para o plano aprovado e ADRs como registro histórico das decisões dentro dele.

Cultura de revisão e o papel do tech lead

O tech lead costuma escrever a primeira versão, mas o valor está na revisão. Times distribuídos revisam de forma assíncrona via comentários no documento; uma reunião só acontece se os comentários ficarem em impasse. A Etsy popularizou os blameless post-mortems como padrão complementar: quando uma indisponibilidade acontece, você relê o design doc para entender qual premissa quebrou. Notação visual costuma usar o modelo C4 (Simon Brown — Context, Container, Component, Code) para diagramas de arquitetura em camadas.

Anti-padrões para evitar

Docs solution-first (sem problem statement), sem alternativas exploradas (o leitor não consegue julgar a escolha), sem trade-offs (toda decisão é apresentada como obviamente certa), sem plano de migração (impacto operacional ignorado), sem rollback (sem plano B) e o doc "muro de texto" sem diagramas. Ferramentas: Google Docs (legado), Notion, Confluence, GitHub wiki, ADR logs dedicados como adr-tools. A ThoughtWorks publica o Tech Radar como prática complementar para acompanhar quais tecnologias um doc pode assumir com segurança.

Perguntas frequentes

Quando design doc é obrigatório? Para qualquer mudança não trivial — novo serviço, novo data store, API breaking change, código sensível à segurança, qualquer coisa que cruze fronteira de time. Refactor rotineiro e bug fix não precisam.

Qual a diferença para um ADR? Um ADR registra uma decisão, imutável, geralmente uma página. Um design doc agrupa várias decisões e evolui até o projeto ir para produção. Um design doc pode produzir vários ADRs como subprodutos.

Qual o tamanho? Três a dez páginas para features típicas. Mais em projetos fundacionais. Se passou de vinte, divida em doc principal + apêndices.

Quem aprova? Os revisores que a cultura do seu time define — geralmente o tech lead mais um ou dois seniores de times vizinhos cujos sistemas você toca. Revisores operacionais (SRE, segurança) entram quando relevante.