Jeff Bezos tem uma frase frequentemente citada: "Se não consegues escrever um memo de seis páginas sobre uma ideia, não a entendes bem o suficiente." A Amazon proibiu PowerPoint em reuniões executivas em 2004 e substituiu por documentos escritos em prosa. O raciocínio: slides permitem que ideias mal formadas pareçam coesas; prosa não perdoa — a falta de clareza no pensamento aparece imediatamente na falta de clareza na escrita. Essa é uma perspectiva radical, e a maioria das organizações não vai tão longe. Mas o princípio subjacente é sólido: escrever força pensar. Um engenheiro que consegue escrever claramente sobre uma decisão técnica entende os trade-offs melhor do que um que só fala sobre ela.
Comunicar decisões técnicas não é soft skill periférica — é engenharia. Uma decisão de arquitetura que não é comunicada efetivamente não existe na prática: será re-questionada, reimplementada de forma inconsistente, ou ignorada. O custo real de má comunicação técnica é medido em retrabalho, decisões duplicadas, e inconsistência de implementação. Este conceito trata de três habilidades concretas: documentar decisões (ADRs), obter alinhamento antes de implementar (design docs e design reviews), e comunicar o mesmo conteúdo técnico para audiências com perspectivas diferentes.
ADRs: o artefato mínimo para preservar decisões
Architecture Decision Record (ADR) é um documento curto que captura uma decisão arquitetural significativa — junto com o contexto que a motivou e as consequências esperadas. O formato foi popularizado por Michael Nygard em 2011. A ideia central: a decisão em si tem vida curta (pode ser revisada), mas o contexto que a justificou tem vida longa e é o que evita re-debates.
# FORMATO CANÔNICO DE ADR (Nygard, 2011):
# Arquivo: docs/adr/0042-usar-postgres-em-vez-de-mongodb.md
# Convenção: número sequencial + slug descritivo
---
# ADR 0042: Usar PostgreSQL em vez de MongoDB para o serviço de catálogo
**Status:** Aceito
**Data:** 2026-03-15
**Deciders:** @alice (tech lead), @bob (backend), @carol (SRE)
**Context consulted:** @david (PM), @eve (data team)
## Contexto
O serviço de catálogo atualmente roda no MongoDB 5.x com schema flexível.
Identificamos três problemas operacionais no último trimestre:
- Query de busca por preço + categoria + disponibilidade levando 800ms P99
(índices compostos no Mongo exigem ordering específico que não atende todos os padrões)
- Schema migration de campo 'variants' causou inconsistência em 2.3% dos documentos
por ausência de validação de schema obrigatória no Mongo
- Time de dados não consegue fazer JOINs para relatórios; exportam tudo para BigQuery
manualmente toda semana
A equipe considerou: otimizar os índices do Mongo, migrar para Postgres, ou adicionar
uma camada de search (Elasticsearch).
## Decisão
Migrar o serviço de catálogo de MongoDB para PostgreSQL 16 com extensão JSONB
para campos de especificações técnicas variáveis (que justificavam o schema flexível).
## Razões
1. Query de busca composta é 10x mais rápida em Postgres com índice GiST + partial indexes
(benchmark realizado em 2026-03-10 com dataset de produção anonimizado)
2. Schema migration com ALTER TABLE + NOT NULL constraints impede inconsistência
3. JOINs diretos para relatórios eliminam o pipeline manual de exportação
4. Time já tem fluência em SQL; MongoDB requer skill adicional que ninguém tem hoje
5. JSONB resolve o caso de uso de specs variáveis sem abrir mão de SQL para o resto
## Alternativas consideradas e rejeitadas
- **Otimização de índices no Mongo:** aborda item 1 parcialmente, não resolve 2 e 3.
Paliativo; retorna aqui em 6 meses.
- **Elasticsearch para search:** resolve item 1, adiciona infra, não resolve 2 e 3.
Overengineering para o tamanho atual (50k produtos).
- **Manter Mongo + adicionar validação de schema:** ferramentas existem (mongocryptd,
JSON Schema validation), mas a equipe não tem experiência e a migração para Postgres
tem ROI melhor pelo contexto atual.
## Consequências
**Positivas esperadas:**
- Latência de busca <100ms P99 (baseado em benchmark)
- Zero inconsistência de schema após migração
- Relatórios de dados sem pipeline manual
**Negativas e riscos:**
- Migração estimada em 3 sprints (6 semanas); serviço de catálogo em feature freeze
- Se o volume de SKUs crescer >10M nos próximos 12 meses, precisaremos avaliar sharding
(documentado em ADR 0043 como próxima decisão pendente)
- Schema JSONB para specs requer disciplina de validação no código (sem garantia do DB)
## Status futuro
Rever em 12 meses (2027-03): se volume de SKUs passar de 2M ou query P99 voltar a
subir, considerar Elasticsearch como camada de search (não substituição do Postgres).
---
# O QUE FAZ UM BOM ADR:
# ✓ Contexto com fatos concretos (números, datas, evidências)
# ✓ Alternativas rejeitadas com razões explícitas
# ✓ Consequências negativas reconhecidas honestamente
# ✓ Status futuro: quando rever esta decisão?
# ✓ Curto: 1-2 páginas máximo
# O QUE TORNA UM ADR INÚTIL:
# ✗ "Decidimos usar Postgres porque é melhor" (sem contexto)
# ✗ Sem alternativas consideradas (parece que não houve análise)
# ✗ Só pontos positivos (suspeito — toda decisão tem trade-offs)
# ✗ Muito longo: se tem 10 páginas, não é ADR, é design doc
# ✗ Não tem data e deciders (não dá para rastrear o contexto de quando foi escrito)
# QUANDO CRIAR UM ADR:
# - Qualquer decisão que seria debatida se um novo engenheiro questionasse
# - Escolha de tecnologia ou framework com impacto em mais de um serviço
# - Decisão de arquitetura que afeta estrutura de dados, protocolos ou APIs
# - Mudança de abordagem que reverterá uma decisão anterior
# QUANDO NÃO CRIAR:
# - Decisões triviais e óbvias dado o contexto (não documentar "usamos HTTP/2")
# - Detalhes de implementação que são facilmente reversíveis
# - Padrões já estabelecidos na organização (referir à documentação existente)
# ONDE ARMAZENAR:
# Opção 1: /docs/adr/ no repositório principal — próximo ao código, versionado com git
# Opção 2: Wiki (Confluence, Notion) — mais acessível para não-engenheiros, mas desconectado do código
# Opção 3: GitHub/GitLab Discussions ou Issues — linkável, com thread de discussão preservada
# Recomendação: /docs/adr/ no repo para ADRs técnicos; Wiki para decisões com impacto amploDesign docs e RFCs: obtendo alinhamento antes de implementar
ADR captura uma decisão já tomada. Design doc serve para obter alinhamento antes de tomar a decisão — é o artefato de discussão, não de registro. O objetivo de um design doc não é impressionar; é chegar a decisões de forma eficiente e com as pessoas certas informadas.
# ESTRUTURA DE UM DESIGN DOC EFICAZ:
## [TÍTULO] Sistema de notificações multi-canal — redesign para 10M usuários
**Autor:** @alice
**Status:** Em revisão
**Última atualização:** 2026-04-01
**Revisores:** @bob (backend), @carol (SRE), @david (PM)
**Decisão esperada até:** 2026-04-10
---
### TL;DR (Executive Summary — 3-5 linhas)
O sistema atual de notificações falha 12% das entregas para usuários com dispositivos
Android >= 13 devido a mudança de comportamento do FCM. Propomos migrar a arquitetura
de fire-and-forget para filas com retry, adicionando workers por canal. Estimativa:
6 semanas de implementação; custo incremental de $400/mês em infra.
### Contexto e problema
[2-3 parágrafos descrevendo O QUE está acontecendo e POR QUE é um problema.
Números concretos. Evidências. Sem solução ainda.]
### Objetivos
- Reduzir taxa de falha de notificação de 12% para <1%
- Suportar 10M usuários ativos sem escala horizontal manual
- SLO: 95% das notificações entregues em <30s após trigger
### Não-objetivos (explícitos)
- Não redesenhar a UI de preferências de notificação (escopo separado)
- Não suportar notificações ricas (imagem, ações) neste ciclo
### Design proposto
[A carne do doc. Diagrama de arquitetura. Decisões técnicas chave.
Fluxo de dados. APIs afetadas. Schema changes. Estimativa de tráfego.]
### Alternativas consideradas
[CADA alternativa com: o que é, por que foi rejeitada neste contexto.
Esta seção mostra que houve análise — não é só defender a solução favorita.]
Alt 1: Usar serviço gerenciado (Firebase, OneSignal)
- Prós: zero ops, integração rápida
- Contras: custo a $0.001/notif = $300k/ano em escala; lock-in; sem controle de retry
- Rejeitado: custo proibitivo e perda de controle de SLO
Alt 2: Manter arquitetura atual + fix FCM issue
- Prós: menos risco, menor escopo
- Contras: aborda apenas 1 dos 3 problemas identificados; retorna aqui em 6 meses
- Rejeitado: dívida técnica acumulada justifica refactor agora
### Riscos e mitigações
[Honesto sobre o que pode dar errado. Para cada risco: probabilidade estimada,
impacto, e plano de mitigação.]
### Plano de implementação e rollout
[Fases. Estratégia de migração. Feature flags. Rollback plan.]
### Métricas de sucesso
[Como saberemos que funcionou? Quais dashboards monitorar?]
### Perguntas em aberto
[Decisões que ainda precisam de input. NÃO fingir que tudo está resolvido.]
- Q1: Qual o SLA de retry para notificações críticas (ex: alertas de segurança)?
Impacto: afeta design do DLQ e o número de retentativas.
- Q2: Precisamos de exactly-once delivery ou at-least-once é aceitável?
---
# DIFERENÇA ADR vs DESIGN DOC vs RFC:
# ADR: captura decisão já tomada. Permanente, curto, no repositório.
# "Decidimos X porque Y. As alternativas Z e W foram rejeitadas porque [...]"
# Design doc: proposta para obter alinhamento. Temporário, médio, pode ser deletado
# após a decisão ser tomada e convertida em ADR.
# "Proponho X. Por favor revise e dê feedback até dia D."
# RFC (Request for Comments): design doc mais formal, geralmente para mudanças
# de maior impacto ou que afetam múltiplas equipes. Tem número sequencial,
# processo de aprovação, e shelf life mais longo.
# Usado por: Rust lang (RFC process), Python (PEP), IETF (internet standards).
# GOOGLE-STYLE DESIGN DOC:
# Google tem um formato interno não-público mas bem descrito na literatura:
# - TL;DR obrigatório no topo
# - Goals e Non-Goals sempre separados
# - "Considered designs" com análise honesta
# - Comentários inline como thread de discussão
# - Status explícito (Draft → In Review → Approved → Implemented → Deprecated)
# O mais importante: o doc é distribuído para leitura ANTES da reunião.
# A reunião é para RESOLVER perguntas em aberto, não para apresentar o doc.
# AMAZON 6-PAGER:
# Bezos baniu PowerPoint; toda proposta é memo de 6 páginas em prosa.
# Começo de toda reunião executiva: 20-30 min de leitura em silêncio.
# Estrutura obrigatória: situação atual → complicações → pergunta → resposta → justificativa.
# O formato força clareza de raciocínio — é impossível esconder pensamento vago em prosa.
# Nem toda empresa precisa ser tão formal, mas o princípio (escrever antes de falar) é universalmente válido.Design reviews que chegam em decisões
A maioria dos design reviews termina com uma lista de ações, sem nenhuma decisão tomada. A próxima semana tem outro review, a mesma lista. O problema é estrutural: sem clareza sobre o propósito e o processo, reviews viram sessões de apresentação unilateral.
# ANATOMIA DE UM DESIGN REVIEW EFICAZ:
# PRÉ-REVIEW (a semana antes):
# 1. Design doc enviado com 48-72h de antecedência. NÃO apresentar no dia.
# 2. Revisores leram o doc e adicionaram comentários antes da reunião.
# 3. O apresentador leu todos os comentários e preparou respostas.
# Resultado: a reunião resolve perguntas abertas, não apresenta o design.
# ESTRUTURA DE 60 MINUTOS:
# 00-05: Setup — qual é o objetivo desta reunião?
# "Precisamos tomar decisão sobre X. Tenho 3 opções. Quero sair daqui com uma escolhida."
# (Não: "vou apresentar meu design e vocês dão feedback")
#
# 05-15: Context — o problema e as constraints
# Apresentar fatos, não soluções ainda. Garantir que todos têm o mesmo entendimento.
# "Alguém discorda do problema como eu formulei?"
#
# 15-35: Proposta e alternativas
# Apresentar a proposta recomendada. Depois apresentar alternativas.
# Para CADA alternativa: por que foi descartada, não apenas o que é.
# "Alguém vê trade-off que não considerei?"
#
# 35-50: Discussão estruturada
# Abordar as perguntas em aberto do design doc.
# Facilitador garante que cada pergunta tem resposta ou decisão explícita.
# "Sobre Q1 (SLA de retry), qual é a posição de vocês?"
#
# 50-60: Decisão e próximos passos
# "Baseado na discussão, a decisão é: [X]. Quem discorda?"
# Documentar a decisão e as razões no design doc antes de encerrar.
# Próximos passos: quem faz o quê, até quando.
# TÉCNICAS DE FACILITAÇÃO:
# 1. "Parking lot" para tangentes:
# Quando a discussão sair do escopo: "Boa questão — anoto no parking lot para
# discutir depois. Agora precisamos decidir X."
# 2. Explícito sobre tipos de feedback:
# "Estou buscando feedback sobre o design geral, não sobre detalhes de implementação."
# "Estou buscando identificar riscos que não vi."
# 3. Separar "discordo" de "não entendo":
# "Você está discordando da decisão ou precisa de mais contexto?"
# Muito "discordância" é na verdade falta de contexto.
# 4. Pré-mortem:
# "Imaginem que é 6 meses depois e este sistema falhou. O que deu errado?"
# Faz o grupo pensar proativamente em riscos em vez de defender a proposta.
# 5. Decisão explícita vs "let's discuss more":
# Ao final: "Precisamos decidir agora ou podemos aguardar mais informação?"
# Se aguardar: "O que exatamente precisamos saber, e quem descobre até quando?"
# Evitar reuniões que terminam sem decisão quando a decisão ERA possível.
# RED FLAGS EM DESIGN REVIEWS:
# - Apresentador não enviou o doc antes da reunião
# - Mais de 8 pessoas (poucos tomam decisões em grupos grandes)
# - Reunião termina com "vamos agendar mais uma reunião"
# - Ninguém pergunta sobre as alternativas rejeitadas
# - Feedback apenas positivo (significa que ninguém realmente analisou)
# - "Decisão" por consensus sem que ninguém defendeu uma posição específica
# DISAGREEMENT E COMMIT:
# Nem toda decisão terá consenso. Formas de avançar mesmo com discordância:
#
# Forma 1 — "Disagree and commit" (Amazon LP):
# Você discorda, mas entende o raciocínio dos outros. Você vai apoiar a implementação.
# Explicitar: "Eu acho que X é melhor, mas vou apoiar a implementação de Y."
# Útil quando: você não tem dados para provar que está certo, ou quando o custo de
# não decidir é maior que o custo de errar.
#
# Forma 2 — Escalação estruturada:
# Quando a discordância é sobre valores ou princípios (não fatos), e o custo de
# errar é muito alto. Escalar para quem tem a autoridade de decidir.
# Útil quando: a decisão afeta muito mais do que o scope original.
#
# Forma 3 — Time-boxed experiment:
# "Implemente em feature branch por 2 semanas. Medimos. Decidimos com dados."
# Útil quando: ambas as opções são razoáveis e podem ser testadas empiricamente.Comunicando para diferentes audiências
A mesma decisão técnica precisa ser comunicada de formas completamente diferentes para engenheiros implementando, PMs planejando, e liderança aprovando. O erro mais comum: usar o mesmo framing para todas as audiências.
# EXEMPLO: comunicar a decisão de adotar Kafka para o pipeline de eventos
# ════════════════════════════════════════
# PARA ENGENHEIROS (tech lead, backend):
# ════════════════════════════════════════
# Contexto: implementação, trade-offs técnicos, decisões de design
#
# "Vamos migrar o pipeline de eventos de HTTP síncrono para Kafka.
#
# Por quê agora: nosso current setup (POST síncrono para cada consumidor)
# não aguenta 50k eventos/s sem throttling agressivo nos produtores.
# Com Kafka, produtores publicam para um tópico; consumidores leem
# no próprio ritmo (backpressure natural).
#
# Trade-offs que precisamos decidir juntos:
# - Particionamento: por user_id (ordering por usuário) ou por event_type
# (paralelismo maior)? Impacta design de consumer groups.
# - Retention: 7 dias é o suficiente para replay? Se processamento cair
# por mais de 7 dias, perdemos eventos — aceitável?
# - Exactly-once vs at-least-once: precisa de idempotency key no consumidor.
# Impacta ~20% do código dos consumers existentes.
#
# Riscos que precisam de mitigação antes do go-live:
# - Consumer lag monitoring: sem alertas em lag >N segundos, não detectamos
# problema até o usuário reclamar.
# - Kafka cluster ops: nenhum de nós tem experiência operando Kafka.
# Proposta: usar MSK (Kafka gerenciado na AWS) na primeira fase.
#
# RFC com design detalhado: [link]. Revisão até sexta."
# ════════════════════════════════════════
# PARA O PM (Product Manager):
# ════════════════════════════════════════
# Contexto: impacto no produto, timeline, riscos para o usuário
#
# "Vamos modernizar como processamos eventos de produto (cliques, compras,
# atualizações de status) de uma forma que elimina o problema de 'notificações
# atrasadas' que os usuários reportam quando há pico de tráfego.
#
# O que muda para o produto:
# - Notificações de status de pedido: hoje atraso de 2-8 min em pico,
# depois da mudança: <30s em 99% dos casos.
# - Analytics de comportamento: dados mais frescos para o time de dados
# (hoje: batch diário; depois: streaming quase real-time).
#
# Timeline: 8 semanas. Feature freeze para o serviço de notificações nas
# primeiras 4 semanas. Nenhum impacto para os usuários durante a migração
# (estratégia de rollout gradual).
#
# Risco principal: se algo der errado na migração, algumas notificações podem
# ter atraso maior do que o atual durante o período de rollout. Janela de risco:
# 1 semana. Plano de rollback pronto.
#
# Não há impacto em features planejadas para Q2 — a migração corre em paralelo."
# ════════════════════════════════════════
# PARA A LIDERANÇA EXECUTIVA (CTO, VP Eng):
# ════════════════════════════════════════
# Contexto: decisão de negócio, risco, ROI, alinhamento estratégico
#
# "Proposta: migrar infraestrutura de eventos para Kafka gerenciado (AWS MSK).
#
# Problema de negócio: 23% dos tickets de suporte no último trimestre foram
# sobre 'notificações atrasadas ou perdidas'. Correlação direta com os picos
# de tráfego às 19h-21h. A arquitetura atual não escala para o crescimento
# projetado de 3x em usuários nos próximos 18 meses sem degradação progressiva.
#
# A decisão:
# Kafka é o padrão da indústria para streaming de eventos em escala.
# Alternativa avaliada: Reduzir funcionalidades para caber na infraestrutura atual.
# Descartada: impacto negativo na experiência do usuário e retorno ao mesmo
# problema em 6-9 meses.
#
# Custo e prazo:
# - Custo incremental: ~$1,800/mês em MSK (Kafka gerenciado). Dentro do budget de infra Q2.
# - Prazo: 8 semanas para migração completa. 2 engenheiros alocados.
#
# Risco e mitigação:
# - Risco técnico: baixo. Usaremos serviço gerenciado (MSK) na fase 1,
# eliminando a necessidade de expertise em ops de Kafka.
# - Risco de negócio: baixo. Rollout gradual com capacidade de rollback em <1h.
#
# O que precisamos de você: aprovação do budget incremental de $1,800/mês."
# ════════════════════════════════════════
# PRINCÍPIOS DE ADAPTAÇÃO POR AUDIÊNCIA:
# ════════════════════════════════════════
# Engenheiros: quer profundidade técnica, trade-offs, decisões de design pendentes.
# Formato: doc técnico, diagrama, código de exemplo, RFC.
# O que NÃO incluir: business case (já é implícito); timeline detalhado (varia).
#
# PMs: quer impacto no produto, timeline, o que muda para o usuário.
# Formato: texto curto, bullets, datas concretas.
# O que NÃO incluir: detalhes técnicos de implementação; alternativas rejeitadas.
#
# Executivos: quer decisão de negócio, risco quantificado, custo, alinhamento estratégico.
# Formato: BLUF (Bottom Line Up Front) — conclusão primeiro, evidência depois.
# O que NÃO incluir: detalhes técnicos; justificativas de implementação.
# O que NUNCA omitir: os riscos reais (executivos tomam decisões melhores com risco honesto).
#
# A regra de ouro: use o nível de detalhe que a audiência PRECISA para DECIDIR.
# Mais detalhe que o necessário não demonstra competência — demonstra falta de julgamento.Apresentando trade-offs de forma convincente
# O ERRO MAIS COMUM: apresentar apenas o lado positivo da solução proposta.
# Isso não funciona com engenheiros seniores — parece que não houve análise real.
# A forma de ser convincente é apresentar os trade-offs honestamente e mostrar
# POR QUE, dado o contexto específico, a opção proposta é a melhor.
# FRAMEWORK: "Dado o contexto C, dado o objetivo G, a opção A é melhor que B porque X.
# Se o contexto mudar para C', reavalie."
# EXEMPLO DE TRADE-OFF BEM APRESENTADO:
# "A questão é: banco SQL (Postgres) vs NoSQL (DynamoDB) para o serviço de perfil.
#
# Contexto que importa:
# - 5M usuários hoje; projeção de 15M em 12 meses
# - Acesso quase sempre por user_id (sem queries ad-hoc complexas)
# - Time tem 3 engineers com fluência em SQL; nenhum com DynamoDB
# - Budget de infra: $2k/mês
#
# Análise:
#
# DynamoDB ganha em:
# - Escala horizontal automática (15M users não é um problema)
# - Latência consistente em qualquer escala
# - Zero ops de DB (gerenciado)
#
# Postgres ganha em:
# - Time já conhece (menor risco de erro operacional)
# - Custo previsível ($200/mês para esse workload vs RCU/WCU variable)
# - Flexível para queries que ainda não sabemos que vamos precisar
# - Transações ACID para atualizações multi-campo
#
# Decisão recomendada: Postgres agora, reavaliar a 10M usuários.
#
# Por quê: o gargalo atual NÃO é escala horizontal — é custo de operação e
# risco de erro. Um Postgres bem dimensionado aguenta 15M usuários com leitura
# por chave sem problema. Se em 12 meses o padrão de acesso mudar para incluir
# queries complexas que o DynamoDB não suporta, teremos dado errado com o NoSQL.
# Se a escala superar o Postgres, teremos dados sobre o padrão de acesso real
# para fazer a migração certa.
#
# Ponto de reavaliação explícito: quando atingirmos 10M usuários OU quando o
# custo de Postgres superar $1k/mês (requer escalonamento significativo)."
# TÉCNICAS ESPECÍFICAS:
# 1. "Rejection table" — documentar por que alternativas foram rejeitadas:
# | Opção | Por que considerada | Por que rejeitada neste contexto |
# |-------------|-------------------------|-------------------------------------|
# | DynamoDB | Escala horizontal | Custo variável, curva de aprendizado|
# | MongoDB | Schema flexível | Problemas com JOINs para relatórios |
# | Postgres | SQL, ACID, familiaridade| (escolha) |
# 2. Quantificar o custo de cada opção (não só benefício):
# Postgres: $200/mês, 0 horas de treinamento, 2 semanas de migração
# DynamoDB: $150-400/mês variable, 2-3 semanas treinamento, 4 semanas de migração
# MongoDB: $180/mês, 1 semana treinamento, 3 semanas de migração
# 3. Definir explicitamente o critério de decisão ANTES de recomendar:
# "O critério prioritário é: menor risco de erro nos próximos 6 meses.
# Dado esse critério, Postgres vence."
# Se a audiência discordar do critério, o debate é sobre o critério — não sobre a solução.
# 4. Identificar quem discordará e por quê:
# Antecipe: "O time de dados vai preferir DynamoDB por suporte a Streams. Mas esse
# caso de uso (perfil do usuário) não é o workload principal deles — é caso separado."
# Preparar resposta específica para a objeção mais provável = credibilidade.
# 5. "Decision dial" — onde no espectro essa decisão cai:
# Não é binário. Para consistência vs disponibilidade:
# ←— CP (consistência forte) ————————————— AP (disponibilidade) —→
# [transação financeira] [contador de likes]
# Mostrar onde a decisão atual se encaixa nesse dial e por quê.Escrita técnica que obtém resultado
# OS PRINCÍPIOS QUE DIFERENCIAM ESCRITA TÉCNICA EFICAZ:
# 1. BLUF — Bottom Line Up Front
# O erro mais comum: construir o argumento e revelar a conclusão no final.
# Engineers e executivos leem doc de forma não-linear — se a conclusão está no final,
# a maioria não lê o suficiente para chegar lá.
#
# Errado:
# "Analisamos opções A, B e C. A tem as seguintes vantagens [...].
# B tem [...]. C tem [...]. Portanto, recomendamos B."
#
# Certo (BLUF):
# "Recomendamos a opção B. Razões: (1) menor custo operacional, (2) menor risco
# de migração, (3) melhor fit com o padrão de acesso atual.
# Alternativas A e C foram avaliadas e rejeitadas pelos seguintes motivos: [...]"
# 2. Uma ideia por parágrafo; primeira frase é a tese
# Cada parágrafo deve poder ser lido isoladamente pela primeira frase.
# "A decisão de usar Redis para rate limiting simplifica a operação." (tese)
# [Parágrafo desenvolve com evidência e contexto]
# "A alternativa com banco relacional requer schema migration e não oferece TTL nativo." (tese)
# 3. Números concretos, não adjetivos vagos
# Errado: "O sistema atual é lento e não escala"
# Certo: "P99 de latência atual: 1200ms. Com volume projetado para Q3, seria 3400ms."
#
# Errado: "A migração vai ser rápida"
# Certo: "A migração leva 3 sprints (6 semanas) com 2 engenheiros alocados."
# 4. "Non-goals" explícitos — o que deliberadamente não está no escopo
# Previne que o escopo expanda ad infinitum durante o review.
# "Não-objetivo: suporte a notificações em tempo real (<1s). Esse requisito, se surgir,
# requer WebSockets — escopo separado."
# 5. Perguntas abertas com responsável e data
# Errado: "Ainda precisamos decidir sobre o mecanismo de retry."
# Certo:
# Q1: Quantas tentativas de retry para notificações críticas?
# → Responsável: @alice verificar com PM até 2026-04-05
# → Impacto: muda design do DLQ se >3 tentativas
# 6. Seção "riscos" honesta
# Nenhuma proposta é sem risco. Omitir riscos é um erro estratégico:
# a) A audiência vai identificar os riscos e perder confiança na análise
# b) Se o risco se materializar, não haverá plano de mitigação
#
# Formato: Risco → Probabilidade → Impacto → Mitigação
# "Risco: consumer lag não monitorado causa perda silenciosa de eventos.
# Prob: média (sem alertas hoje). Impacto: alto (dados de analytics incorretos).
# Mitigação: dashboard + alerta de lag >30s antes do go-live."
# 7. Consistência de terminologia
# Decidir os termos antes de escrever e usá-los consistentemente.
# "evento" vs "mensagem" vs "payload" — escolher um, usar sempre.
# Inconsistência de terminologia em docs técnicos confunde e gera debates desnecessários.
# SOBRE TAMANHO:
# Design doc: 3-6 páginas (com diagramas). Mais que isso → está faltando estrutura.
# ADR: 1-2 páginas. Mais que isso → está virando design doc.
# Update de status: 1 parágrafo. Se precisar de mais → reunião é necessária.
# Slack/email técnico: sem formatação excessiva; bullets só para listas reais.
# A regra de Bezos (6-pager) é um máximo, não um alvo — se 3 páginas bastam, 3 páginas.Arquitetura de documentação técnica
TIPOS DE DOCUMENTAÇÃO E SEUS PROPÓSITOS:
┌─────────────────────────────────────────────────────────────────────┐
│ TIPO │ PROPÓSITO │ AUDIÊNCIA │ VIDA ÚTIL │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ ADR │ Registrar decisão │ Eng (futuro) │ Permanente │
│ │ já tomada │ │ │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ Design Doc │ Obter alinhamento │ Eng + PM │ Médio prazo │
│ / RFC │ antes de decidir │ │ (até decisão) │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ Runbook │ Operar o sistema │ Eng (on-call) │ Permanente │
│ │ em produção │ │ (atualizado) │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ Post-mortem │ Aprender com falha │ Eng + lideran.│ Permanente │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ Diagrama de │ Entender o sistema │ Eng (onboard) │ Permanente │
│ arquitetura │ como um todo │ │ (atualizado) │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ README │ Iniciar com o │ Eng (onboard) │ Permanente │
│ │ repositório │ │ │
├────────────────┼────────────────────┼───────────────┼───────────────┤
│ Changelog │ O que mudou e por │ Dev + usuário │ Permanente │
│ │ quê em cada versão │ │ │
└─────────────────────────────────────────────────────────────────────┘
HIERARQUIA DE DECISÕES:
(do mais estratégico ao mais tático)
L1: Princípios de engenharia da organização
(ex: "preferimos sistemas simples que precisamos entender sobre abstrações complexas")
Formato: wiki, 1-2 páginas, revisado anualmente
Mudança: liderança técnica + votação do time
L2: Padrões técnicos da organização
(ex: "usamos Postgres como banco primário, Redis para cache")
Formato: wiki + ADR explicando por que o padrão existe
Mudança: RFC + aprovação de tech leads
L3: Decisões arquiteturais por domínio
(ex: "o serviço de pagamentos usa idempotency keys em todos os endpoints")
Formato: ADR no repositório do serviço
Mudança: ADR novo que supersede o anterior
L4: Decisões de implementação
(ex: "usar Caffeine em vez de Guava Cache")
Formato: comentário no código ou PR description
Mudança: PR com justificativa
ONDE DOCUMENTAÇÃO FALHA:
- Não existe (a decisão foi verbal e se perdeu)
- Existe mas está desatualizada (mais perigoso que não existir)
- Existe mas ninguém sabe onde encontrar
- Existe mas não tem contexto (só o "o quê", não o "por quê")
COMO MANTER DOCUMENTAÇÃO ATUALIZADA:
- ADRs nunca são editados; são supersedidos por ADRs novos
- Design docs marcados como "Deprecated" quando a decisão mudou
- Runbooks e diagramas: incluir "última revisão" e data no topo
- Review periódico: todo trimestre, verificar se os top 10 docs ainda estão corretos
- Ownership claro: cada doc tem um "owner" que é responsável por mantê-lo válido
Engenheiros seniores frequentemente subestimam o valor de documentar o que foi rejeitado e por quê. O design doc do que foi escolhido tem valor óbvio. Mas o registro das alternativas descartadas — com o contexto específico que as tornou inadequadas naquele momento — é o que previne retrabalho mais valioso. Seis meses depois, com um novo engenheiro no time, a decisão vai ser questionada. Se a resposta for "decidimos assim porque sim", o debate recomeça do zero. Se a resposta for "veja o ADR 0042 — consideramos DynamoDB, mas o custo operacional não compensava dado nosso volume atual; reavalie quando atingirmos 10M usuários", o debate começa do ponto onde parou. Documentar o que foi rejeitado é um ato de respeito pelo tempo futuro do time.
Decisões de engenharia
O instinto errado é criar ADR para tudo — isso leva a "ADR inflation" onde o documento existe mas ninguém lê porque há centenas. O instinto oposto (não criar nenhum) deixa o time re-debatendo as mesmas decisões. O critério correto: criar ADR quando um engenheiro novo ou futuro poderia razoavelmente questionar a decisão e quando o contexto que motivou a decisão não é óbvio pelo código.
Critério prático: se você pode responder "por que foi assim?" em uma frase sem perder contexto importante, não precisa de ADR. Se a resposta completa envolve contexto de negócio, constraints de momento, ou trade-offs não-óbvios, crie o ADR. Decisões de escolha de tecnologia (banco, framework, linguagem), decisões de arquitetura (sync vs async, monolito vs micro), e decisões que revertem padrões estabelecidos sempre justificam ADR. Preferências de style de código, nomes de variáveis, e detalhes de implementação não justificam.
O tamanho de um design review impacta diretamente a qualidade das decisões. Acima de 8 pessoas, o review vira apresentação: pessoas são tímidas em grupos grandes, dominadores falam mais, e a dinâmica de grupo inibe crítica honesta. Abaixo de 3, falta diversidade de perspectivas e pontos cegos não são identificados.
Quem convidar: quem vai implementar (precisam de clareza técnica), quem será afetado (precisam de chance de input antes de ser impactados), e quem tem a autoridade de aprovar (decisão precisa deles). Não convidar: quem vai executar sem influência no design, quem tem interesse mas não conhecimento técnico relevante (incluí-los em um update separado depois). A regra das "duas pizzas" (Amazon) é heurística razoável: se precisa de mais de duas pizzas para alimentar o grupo, o grupo é grande demais. Para reviews de alta stakes, convidar também alguém de fora da equipe como "advogado do diabo" — alguém sem viés pelo design proposto.
Mudanças arquiteturais que não são bem comunicadas geram shadow implementations (alguém implementou do jeito antigo sem saber que mudou) e resistência passiva (time executa mas não entende o porquê e não aplica o espírito da mudança). A comunicação não termina quando o design doc é aprovado.
Processo eficaz: aprovação do design doc → ADR criado com decisão → sessão de 30 min com o time para walkthrough (não para re-discutir a decisão, mas para garantir que todos entendem as implicações práticas) → README ou wiki atualizado com o novo padrão → PR review reforçando o novo padrão nos primeiros meses. Para mudanças maiores: "architecture office hours" — hora semanal aberta para perguntas enquanto o time se adapta. A adoção de um novo padrão é completa quando o time o aplica corretamente sem precisar ser lembrado, não quando o ADR foi aprovado.
Post-mortem é um tipo especial de documento de decisão: documenta as decisões que levaram à falha e as decisões que vão prevenir recorrência. O princípio fundamental: blameless — o objetivo é entender o sistema, não punir indivíduos. Sistemas que punem indivíduos por falhas treinam o time a esconder problemas.
Estrutura eficaz: timeline detalhada do incidente (o que aconteceu, quando, quem detectou), análise de causa-raiz com "5 whys" (não parar no primeiro "por quê"), impacto quantificado (usuários afetados, duração, custo estimado), e ação corretiva com responsável e prazo. O que diferencia um bom post-mortem de um ruim: os action items são concretos, mensuráveis, e têm owner e deadline. "Melhorar o monitoramento" não é ação; "adicionar alerta para consumer lag >30s em todos os tópicos Kafka até 2026-05-01, owner @alice" é ação. Post-mortems sem ações concretas são relatos históricos, não instrumentos de melhoria.
Perguntas de entrevista
Como você convence um time que resiste a uma mudança técnica que você acredita ser necessária?
Resistência a mudança técnica raramente é irracional — geralmente é falta de contexto, preocupação legítima com risco, ou experiência passada com mudanças mal executadas. O caminho para superar resistência não é forçar, é entender a resistência e endereçá-la.
Passo 1 — Entender a resistência real: "Qual é o principal receio?" pode revelar que a resistência não é sobre a mudança em si, mas sobre timing (sprint já cheio), sobre capacidade (ninguém sabe a nova tecnologia), ou sobre experiência passada ("já tentamos isso antes e não funcionou"). Endereçar a resistência real é mais eficaz que repetir os argumentos da proposta.
Passo 2 — Dados, não argumentos: em vez de debater quem está certo, proponha um experimento pequeno com métricas claras. "Vamos implementar em uma feature branch por duas semanas e medir X, Y, Z. Se os dados suportarem, prosseguimos. Caso contrário, descartamos." Isso transforma a discussão de "minha opinião vs sua opinião" para "o que os dados dizem".
Passo 3 — Custo da inação: apresentar explicitamente o custo de não mudar é tão importante quanto apresentar os benefícios da mudança. "Se não fizermos isso, qual é o cenário em 6 meses?" Frequentemente a inação tem custo mais visível do que a mudança quando explicitado.
Passo 4 — Reduzir o risco percebido: a resistência muitas vezes é sobre risco, não sobre a decisão em si. Propor um rollout gradual, com feature flag, com rollback plan claro, muda a percepção de "salto no escuro" para "mudança gerenciada".
Passo 5 — Incluir o time no design: se as pessoas que resistem participam do processo de design, elas têm ownership parcial da solução. Isso não é manipulação — é reconhecimento de que o time vai implementar a mudança, e a implementação é melhor quando os implementadores acreditam nela.
Quando não funciona: se após todo esse processo ainda há resistência forte, há duas possibilidades. (a) Eles estão certos e você não percebeu — reconsidere genuinamente. (b) A decisão precisa ser escalada para quem tem autoridade. Documentar o raciocínio, documentar a resistência e os argumentos, escalar com contexto completo. "Disagree and commit" só funciona para a pessoa que discorda, não para quem propõe — você não pode ordenar alguém a "concordar e comprometer".
Você precisa apresentar uma proposta técnica complexa para um CTO sem background técnico aprofundado em 10 minutos. Como você estrutura?
Dez minutos com um executivo é um formato muito específico que exige uma estrutura completamente diferente de um design review técnico. O erro mais comum é tentar encaixar o conteúdo técnico completo em 10 minutos — isso garante que a pessoa não vai tomar a decisão que você precisa.
Estrutura para 10 minutos com executivo:
Minutos 0-2: O problema em termos de negócio. Não tecnologia — impacto no produto, no custo, ou no usuário. "23% dos tickets de suporte são sobre notificações atrasadas. Isso custa X horas do time de suporte por semana e tem NPS impacto de -8 pontos no segmento afetado." Os executivos tomam decisões sobre negócio, não sobre tecnologia. Se você começa com a solução técnica, perdeu a atenção.
Minutos 2-4: A solução em uma frase. "A solução é modernizar como processamos eventos, usando uma fila em vez de processamento direto. Isso elimina os atrasos." Sem jargão técnico não-necessário. Se a pessoa perguntar "o que é fila?", explique em analogia: "como uma fila de banco — cada mensagem espera na ordem certa em vez de todo mundo tentando ao mesmo tempo".
Minutos 4-6: Os números. Custo, tempo, risco em termos quantificados. "Custo incremental: R$X/mês. Tempo de implementação: Y semanas. Risco principal: Z, mitigado por W." Executivos tomam decisões com números. Números vagos ("não vai ser muito caro") criam incerteza; números concretos criam confiança.
Minutos 6-8: Alternativas consideradas. Uma frase por alternativa e por que foi descartada. Isso demonstra que houve análise e que não é a primeira ideia que surgiu. "Avaliamos também [X], mas [razão concisa]. E [Y], mas [razão concisa]. Dado o contexto, [proposta] tem o melhor ROI."
Minutos 8-10: A decisão que você precisa. Seja específico sobre o que precisa. "Precisamos de aprovação para alocar 2 engenheiros por 8 semanas e R$X/mês em infraestrutura adicional." Se terminar sem pedir a decisão específica, você desperdiçou os 10 minutos.
O que preparar para perguntas: executivos frequentemente perguntam sobre risco, custo total, alternativas descartadas, e o que acontece se der errado. Prepare respostas de uma frase para cada uma. Se uma pergunta for muito técnica para responder em uma frase, "posso mandar o documento técnico detalhado?" é resposta válida.
Como você documenta uma decisão técnica que você sabe que está errada mas que a liderança insistiu?
Esta é uma das situações mais delicadas na carreira de um engenheiro sênior, e a forma como você lida com ela diz muito sobre seu julgamento profissional.
Primeiro: certifique-se de que tentou genuinamente. "Liderança insistiu" pode significar: (a) você não apresentou os riscos de forma clara o suficiente, (b) eles têm contexto que você não tem (pressão de negócio, restrição legal, compromisso com cliente), ou (c) genuinamente priorizaram diferente de você. Antes de assumir que a decisão está errada, verifique se você articulou os riscos de forma que a audiência pudesse entender.
Se após isso a decisão ainda parece errada: documente honestamente. O ADR deve incluir suas preocupações, não apenas a decisão. "Contexto: a decisão foi tomada sob pressão de prazo [contexto]. A alternativa A foi considerada preferível tecnicamente pelo time de engenharia, mas foi descartada por [razão de negócio]." Isso não é insubordinação — é registro fiel da realidade. Um ADR que omite a discordância real é um documento incompleto.
O que colocar explicitamente no ADR: quais riscos técnicos foram levantados, quais foram aceitos conscientemente pela liderança, e quais são os critérios de reavaliação. "Este ADR será reavaliado se [condição específica] ocorrer." Se o risco se materializar, o ADR documenta que foi antecipado — isso protege o time e cria accountability na decisão.
O que não fazer: (a) implementar da forma que você considera certa sem comunicar — isso é sabotagem e quebra confiança; (b) fingir concordância sem documentar a discordância — isso é desonesto e o prejudica se o risco se materializar; (c) envenenar o poço no time ("a liderança mandou fazer essa besteira") — isso mina a autoridade e cria disfunção.
Após a decisão: "disagree and commit" com fidelidade. Se você concordou em implementar a decisão (mesmo discordando), implementar bem é sua responsabilidade profissional. Isso não significa que você não pode continuar fazendo o caso para reverter — mas de forma estruturada, com dados, via canais adequados.
Quando a situação é inaceitável: se a decisão viola princípios éticos, cria risco de segurança real para usuários, ou está fora dos limites legais — essas são situações que justificam escalação mais forte, até fora da cadeia de comando normal. Riscos técnicos de performance ou dívida técnica não são nessa categoria.
Qual é a diferença entre um design doc, um RFC e um ADR? Quando usar cada um?
Os três são artefatos de decisão técnica, mas têm propósitos distintos, audiências diferentes e ciclos de vida diferentes. Confundi-los é um sinal de processo imaturo.
Design doc (ou proposta técnica): o artefato do processo de chegar a uma decisão. Criado antes da decisão ser tomada. Conteúdo: problema, proposta, alternativas, trade-offs, perguntas abertas. Destinatário: o grupo que tomará a decisão (engenheiros + PM + tech lead). Duração: temporário — pode ser arquivado ou marcado como "implemented" após a decisão. Formato: flexível; geralmente 2-6 páginas. Analogia: é a discussão antes da votação.
ADR (Architecture Decision Record): o registro permanente de uma decisão já tomada. Criado após a decisão. Conteúdo: contexto, decisão, razões, alternativas rejeitadas, consequências esperadas. Destinatário: engenheiros futuros que precisam entender por que o sistema é como é. Duração: permanente — nunca editado, apenas supersedido por novo ADR. Formato: padrão (Nygard ou similar); 1-2 páginas máximo. Analogia: é a ata da votação, mais o raciocínio completo.
RFC (Request for Comments): um design doc mais formal, geralmente para mudanças com impacto amplo (múltiplos times, API pública, decisão organizacional). Tem número sequencial, processo de revisão estruturado (período de comentários, aprovação formal), e é preservado como registro histórico. Usado por: projetos open-source (Rust RFC, Python PEP, IETF), organizações grandes com múltiplos times. Para a maioria das decisões dentro de uma equipe, o design doc é suficiente — RFC é overhead desnecessário.
Quando usar cada um:
Design doc: sempre que uma decisão técnica significativa precisa de alinhamento antes de implementar. "Significativa" = mais de 1 sprint de implementação OU afeta mais de 1 serviço OU envolve trade-offs não-óbvios.
ADR: depois que o design doc resultou em uma decisão. Qualquer decisão que um engenheiro novo poderia questionar. Não substituir o design doc com ADR — são complementares.
RFC: quando a mudança afeta múltiplos times ou tem impacto organizacional, e quando é necessário um processo formal de comentários com prazo definido.
Erro comum: usar ADR como substituto de design doc (criar o ADR sem o processo de review) — a decisão parece ter sido tomada sem análise. Ou usar design doc como substituto de ADR (o doc existe mas a decisão final não está registrada de forma durável).
Como você conduz um design review quando o autor da proposta é mais sênior do que você?
Esta situação é comum e desafiadora: você tem preocupações legítimas sobre uma proposta de alguém com mais senioridade, posição ou influência. A dinâmica de poder pode silenciar feedback válido — o que é prejudicial para o time e para o sistema que será construído.
Prepare-se com antecedência e por escrito. Comentários escritos no design doc antes da reunião são mais fáceis de dar (e receber) do que feedback verbal em público. Escrever "não entendi a justificativa para X, pode elaborar?" é menos ameaçador que perguntar o mesmo em voz alta com todos olhando. Além disso, comentários escritos ficam registrados — o autor pode responder em privado e chegam na reunião com o contexto resolvido.
Use perguntas, não afirmações. "Que acontece se Y?" é mais fácil de ouvir do que "Isso vai falhar quando Y". A pergunta convida à reflexão; a afirmação cria defensividade. Para questões técnicas que você tem razão mas a pessoa sênior pode discordar: "Ajuda-me a entender por que [X] foi escolhido em vez de [Y] — minha preocupação é [Z], mas pode ser que eu não tenha o contexto completo."
Focar em riscos, não em preferências. "Prefiro a abordagem B" é mais fácil de ignorar do que "Minha preocupação é que a abordagem A falha quando o volume triplica — testei com benchmark e [número]". Risco com evidência é mais difícil de desconsiderar do que preferência pessoal. Se não tem evidência, diga "isso me preocupa porque [razão], mas não tenho dado para provar — vale a pena investigar?"
Separe o que é técnico do que é preferência. Nas preocupações técnicas com evidência, seja direto. Em preferências de style ou abordagem sem impacto significativo, deixe passar — não toda batalha precisa ser travada. O capital político de discordar é limitado; use-o nas questões que realmente importam para o produto.
Se sua preocupação for ignorada: documentá-la no design doc como "pergunta em aberto" ou "risco levantado" é legítimo mesmo que não seja o caminho escolhido. Se o risco se materializar, o registro existe. Se não se materializar, você aprendeu algo. Não guardar rancor de qualquer jeito — fazer bom julgamento significa estar disposto a errar.
O que não fazer: silenciar-se completamente (você tem responsabilidade de levantar riscos reais, independente de quem fez a proposta); ou antagonizar publicamente de forma que o debate vire sobre pessoas, não sobre a decisão técnica. Em ambos os casos, o produto sofre.
Exercícios práticos
Escolha uma decisão técnica recente que você tomou ou participou — pode ser escolha de biblioteca, padrão de código, arquitetura de um serviço pequeno. Escreva um ADR completo seguindo o formato: título + status + data + deciders, contexto (com fatos concretos, não vagos), decisão, razões (por que esta opção, não as outras), alternativas consideradas e rejeitadas (mínimo 2), consequências (positivas E negativas), e ponto de reavaliação futuro.
Critério: o ADR pode ser lido por alguém sem contexto prévio e essa pessoa entende por que a decisão foi tomada. As alternativas rejeitadas têm razões concretas (não apenas "é pior"). As consequências negativas são honestas, não minimizadas. O ponto de reavaliação é específico (condição concreta, não "quando necessário"). Bonus: compartilhe com alguém do seu time que participou da decisão e verifique se eles concordam que o ADR captura fielmente o raciocínio que tiveram.
Escolha uma decisão técnica (pode ser a do exercício 1 ou outra). Escreva três versões do comunicado da mesma decisão: (a) para o engenheiro que vai implementar — foco em trade-offs técnicos, design detalhado, perguntas abertas; (b) para o PM — foco em impacto no produto, timeline, o que muda para o usuário; (c) para a liderança executiva — foco em decisão de negócio, custo, risco quantificado, o que você precisa da liderança. Cada versão deve ter no máximo 1 página.
Critério: cada versão usa vocabulário apropriado para a audiência (sem jargão técnico para PM/executivo; com profundidade técnica suficiente para engenheiros). As três versões são consistentes entre si — contam a mesma história com nível de detalhe diferente. A versão executiva começa com a conclusão (BLUF). A versão para engenheiros inclui trade-offs e questões abertas. Bonus: peça para alguém de cada perfil ler "sua" versão e verificar se eles conseguem tomar a ação que você precisa deles.
Proponha um design review para uma proposta técnica real (pode ser algo do seu backlog). Prepare: (a) design doc distribuído 48h antes; (b) agenda explícita com objetivo da reunião ("sair com X decidido"); (c) lista de perguntas em aberto que precisam de resposta; (d) pelo menos 2 alternativas rejeitadas documentadas; (e) pré-mortem: "imagine que o sistema falhou em 6 meses — o que deu errado?" Execute o review (ou simule com um colega). Documente: quais decisões foram tomadas? Quais perguntas ficaram abertas? Quem é responsável pelo quê?
Critério: o design doc foi distribuído antes (não apresentado na reunião). A reunião termina com pelo menos uma decisão explícita (não "vamos discutir mais"). Cada pergunta em aberto tem responsável e prazo. O pré-mortem identificou pelo menos um risco que não estava no doc original. Bonus: compare o design doc antes e depois do review — que perguntas foram levantadas que não estavam no original? Isso mede a efetividade do review.
Documente um incidente técnico real (ou simule com um cenário hipotético: serviço de cache ficou offline por 2h durante pico de tráfego, causando latência de 5x e X usuários afetados). Escreva um post-mortem completo: timeline detalhada, análise de causa raiz com 5 whys (cada "por quê?" deve levar a outro mais profundo), impacto quantificado, e ações corretivas com owner e prazo. Garantir que o documento é blameless — sem nomear culpados, focando em falhas de processo ou sistema.
Critério: a análise de causa raiz chega a causas sistêmicas (não "o engenheiro cometeu um erro" — chegar a "não havia alerta automático para detectar o erro antes do impacto"). Os action items são concretos: cada um tem responsável nomeado, prazo específico, e como saberemos que foi completado. O documento pode ser lido por alguém não-técnico e essa pessoa entende o impacto. Bonus: apresente o post-mortem para o time e peça que identifiquem ações adicionais que você não viu — a discussão adicional após o post-mortem escrito é frequentemente onde o maior aprendizado acontece.
Escolha um serviço ou sistema que você conhece bem. Faça um inventário das decisões arquiteturais significativas: escolha de banco, framework, padrão de comunicação (sync/async), estratégia de autenticação, modelo de dados principal, estratégia de deploy. Para cada decisão: está documentada em ADR? Se sim, o ADR ainda reflete a realidade? Se não, escreva um ADR retroativo que captura o contexto provável (você pode inferir o contexto pelo código e pelo histórico de git/PR). Identifique decisões que deveriam ser reavaliadas com o contexto atual.
Critério: inventário com pelo menos 5 decisões significativas identificadas. Para cada uma: existe ADR? O ADR está atualizado? Se não existe, você consegue escrever um retroativo com as informações disponíveis (código, git log, PRs, Slack history)? Identificar pelo menos 1 decisão que deveria ser reavaliada hoje dado que o contexto mudou desde que foi tomada. Bonus: compare o inventário com algum colega que trabalha no mesmo sistema — há decisões que você não sabia que foram deliberadas? Isso revela o gap de documentação do sistema.
Referências
- article Nygard, M. — Documenting Architecture Decisions
- book Hohpe, G. — The Software Architect Elevator
- article Vogels, W. — Working Backwards (Amazon's PR/FAQ)
- article Google — How Google Does Design Docs
- book McConnell, S. — Software Estimation: Demystifying the Black Art
- article Atlassian — Incident Management and Blameless Post-mortems
- article Kleppmann, M. — Writing a Technical Design Document
- book Minto, B. — The Pyramid Principle
- article SRE Book — Postmortem Culture: Learning from Failure
- article Thoughtworks Technology Radar — Architecture Decision Records
- book Richards, M. & Ford, N. — Fundamentals of Software Architecture
- article Winters, T. et al. — Software Engineering at Google (Culture chapter)