Todo time tem essa reunião: alguém pergunta "por que a gente usa fila aqui em vez de chamada direta?", e a resposta é um silêncio constrangido seguido de "acho que o pessoal que saiu decidiu isso". A decisão existe, o contexto evaporou, e agora ninguém sabe se ela ainda vale ou se é só inércia.

Architecture Decision Records existem para matar essa cena. O formato foi proposto por Michael Nygard num post que virou referência (Documenting Architecture Decisions) e é deliberadamente simples: uma página por decisão, guardada junto do código.

A anatomia de um ADR

• Título e status: "ADR-007: Fila de eventos para processamento de pedidos" + status (proposto, aceito, substituído por ADR-015).
• Contexto: o que era verdade quando decidimos: volume, prazo, restrições, o que sabíamos e o que não sabíamos.
• Decisão: o que escolhemos, em uma frase direta.
• Alternativas consideradas: o que foi descartado e por quê. A seção mais valiosa: evita rediscutir o rejeitado a cada seis meses.
• Consequências: o que ganhamos, o que aceitamos pagar, o que passa a ser mais difícil. Toda decisão de arquitetura é um trade-off; o ADR é onde ele fica explícito.

Vinte minutos para escrever. Anos de "por quê?" respondidos.

Por que funciona (quando funciona)

• O contexto sobrevive às pessoas: quem chega no onboarding lê a história das decisões em vez de arqueologia de código.
• Decisões melhores no presente: escrever contexto e alternativas força clareza. Muita decisão frágil morre no próprio processo de escrita, antes de custar caro.
• Revisão honesta no futuro: quando o contexto mudar ("agora temos 100x o volume"), o ADR diz exatamente quais premissas venceram o prazo de validade. Supersede-se com um novo ADR, mantendo a trilha.
• Menos guerra de opinião: a discussão migra de "eu acho" para alternativas comparadas por critérios. E o que foi decidido, está decidido, até que o contexto mude de verdade.

As regras que separam ADR vivo de cemitério de documentos

1. Perto do código: uma pasta docs/adr/ no repositório, revisada por PR como tudo. Wiki distante é onde documentação vai morrer.
2. Só decisões com custo de reversão: escolha de banco, padrão de integração, estratégia de autenticação. Nome de variável não é ADR; é guia de estilo automatizado.
3. Curto ou não será lido: uma página. Se precisa de dez, o anexo é outro documento; o ADR é o resumo executivo da decisão.
4. Imutável depois de aceito: mudou de ideia? Novo ADR que substitui o antigo. A história completa é o ativo; editar o passado a destrói.
5. Parte do ritual, não evento: a regra do time vira "decisão de arquitetura sem ADR não entra". Como tudo em maturidade, o valor está na constância.

Como começar (hoje, sem cerimônia)

Não tente documentar o passado inteiro: comece pela próxima decisão. Depois, nos momentos de dúvida ("por que isso é assim?"), escreva o ADR retroativo daquela decisão específica, com o contexto que ainda for recuperável. Em seis meses, as decisões que importam estão registradas, e o custo foi imperceptível.

Um modelo pronto para copiar está no repositório de templates de ADR mantido pela comunidade (adr.github.io).

O efeito colateral que ninguém espera

Times que adotam ADR relatam algo curioso: as reuniões de arquitetura melhoram. Saber que a decisão vira documento com alternativas e consequências muda o tom da conversa: menos retórica, mais critério. A escrita disciplina o pensamento, e o pensamento disciplinado decide melhor.

Instalar essa prática (o template, o ritual e os primeiros ADRs feitos junto) é parte do nosso serviço de Consultoria e Treinamento em TI.

Qual decisão do seu sistema ninguém sabe mais por que existe? Conte para a IA da Rabelo Digital, aqui no canto da tela, e ela ajuda a reconstruir o ADR retroativo. Sem formulário, sem espera.

---

Leia também

• Code Review que ensina e não trava
• Como elevar a maturidade técnica do seu time