Design docs C1: complete design documents

Nível: C1

Objetivo

Escrever design docs C1 completos com context, goals, non-goals, proposal, alternatives, risks, rollout e monitoring. O foco é um documento que liderança aprova em 30 minutos e engenharia executa sem precisar de outra reunião.

Explicação

Um design doc C1 não é um RFC informal: é um documento que precisa ser aprovado antes da execução e que sobrevive à transição de autor. Estrutura canônica:

1. Context (1 parágrafo)

Onde estamos e por que este doc existe agora. `We are scaling the search service to handle 10x traffic in Q4; this doc proposes the new caching layer.` Context é o que justifica o doc; sem ele, a audiência lê a proposta sem entender o problema.

2. Goals e non-goals

Goals são o que precisa ser verdade depois. `p99 latency under 200 ms; cache hit rate above 80%.` Non-goals são o que está fora de escopo. `We are not changing the payment provider; we are not migrating the read replica in this doc.` C1 separa os dois; sem non-goals, a review gasta tempo em opções fora de escopo.

3. Proposal (a parte principal)

A proposta descreve a arquitetura, o data flow, e os componentes. `We propose a Redis cache in front of the database, with cache-aside reads and explicit invalidation on write.` A proposta tem diagrama (caixas em alto nível), data flow (uma frase por etapa), e decisões chave com trade-off (escolha + alternativa rejeitada).

4. Alternatives considered

Pelo menos duas alternativas, cada uma com trade-off e razão de rejeição. `Alternative B: read replica. Trade-off: needs two sprints. Rejected because the timeline does not support it.` Alternatives considered é o que transforma propaganda em design; sem isso, a proposta vira imposição.

5. Risks e mitigations

Lista nomeada de riscos com impacto em prazo/métrica + mitigação. `Risk: cache invalidation bug. Mitigation: 1% canary for 24 hours before each stage.` Sem mitigation, risco vira objeção.

6. Rollout plan

Estágios com prazos e métricas de saída. `Day 1: 1% canary, watch error rate for 24h. Day 2: 10% if green. Day 5: 100% if green.` Rollout plan é o compromisso operacional; sem ele, o doc não fecha.

7. Monitoring e success metrics

Métricas que vão dizer se o design está funcionando. `p99 latency, cache hit rate, error rate, queue depth; alert at p99 > 250 ms for 5 minutes.` Monitoring fecha o doc: o que vai ser medido depois do rollout.

Exemplos

Erros comuns

• Pular o context: a audiência lê a proposta sem entender o problema; a review gasta tempo re-derivando o porquê.
• Misturar goals com non-goals: 'we will do X' sem 'we will not do Y' deixa a review aberta a feature creep.
• Proposal sem diagrama: 'vamos usar Redis' não é proposal; diagrama + data flow + decisões é.
• Alternatives sem trade-off: 'consideramos B' sem dizer por que rejeitamos é propaganda.
• Risks sem mitigation: 'pode falhar' é óbvio; 'se falhar, mitigamos com X' é engenharia.
• Rollout sem métrica de saída: 'subimos em 5 dias' é vago; '1% -> 10% -> 100% se error rate < 1%' é comprometimento.

Prática guiada

Reescreva cada bloco abaixo no padrão C1 de design doc.

1. Context: troque 'we need a new cache' por 'scaling to 10x in Q4; this doc proposes X'.
2. Goals + non-goals: liste os dois separadamente.
3. Proposal: inclua diagrama de alto nível + data flow + decisões chave com trade-off.
4. Alternatives: pelo menos duas, com trade-off + razão de rejeição.
5. Risks + mitigation: lista nomeada com impacto e plano.
6. Rollout: estágios com métrica de saída.
7. Monitoring: métricas e alertas.

Resumo

O design doc C1 tem sete blocos: context, goals, non-goals, proposal, alternatives, risks + mitigation, rollout, monitoring. Cada bloco tem função própria; sem nenhum deles, o doc perde maturidade. O resultado é um documento que liderança aprova em 30 minutos e engenharia executa sem precisar de outra reunião.

História: Design docs C1: complete design documents

Nível: C1

História em inglês

Writing the caching design doc for the team

On Wednesday, I had to write the design doc for the new caching layer before the architecture review. I opened with context: we are scaling the search service to handle 10x traffic in Q4; this doc proposes the new caching layer. I listed goals and non-goals: goals, p99 under 200 ms; non-goals, we are not changing the payment provider. I described the proposal: Redis cache in front of the database, cache-aside reads, explicit invalidation on write. I listed alternatives: alternative B, read replica; rejected because it needs two sprints. I added risks and rollout: risk, cache invalidation bug; mitigation, 1% canary for 24 hours; rollout, 1% on day 1, 10% on day 2, 100% on day 5. The architecture review approved the doc in 30 minutes; the team started the work the next sprint.

Tradução linha por linha

Notas de vocabulário

• we are scaling the search service to 10x = context: número + prazo.
• goals vs non-goals = separação canônica que delimita a review.
• Redis cache-aside, explicit invalidation = proposal com decisão chave + invalidação.
• alternative B, read replica; rejected because ... = alternatives com razão de rejeição.
• 1% canary for 24 hours = risk com mitigation explícita.
• approved in 30 minutes = sinal de design doc C1: liderança lê e aprova rápido.

Perguntas de compreensão

1. Por que começar com context em C1?
2. O que torna alternatives C1 útil?
3. O que diferencia um rollout C1?

Prática com a história

1. Escreva o context C1 para um design doc de migração de banco.
2. Escreva alternatives C1 com trade-off e razão de rejeição.
3. Escreva um rollout C1 com métrica de saída.