Architecture Decision Records (ADR): O Guia Completo

Todo sistema de software é moldado por centenas de decisões. PostgreSQL ao invés de MongoDB. REST ao invés de GraphQL. Monolito ao invés de microsserviços. Orientado a eventos ao invés de request-response. Cada escolha restringe escolhas futuras, e juntas elas definem a arquitetura.

O problema é que decisões são invisíveis. O código mostra o que foi construído, não por que foi construído daquela forma. Seis meses depois de escolher PostgreSQL, ninguém lembra se a equipe considerou DynamoDB, quais eram os requisitos de performance, ou por que consistência eventual era inaceitável. A decisão está embutida no código, mas o raciocínio se perdeu.

Architecture Decision Records (ADRs) resolvem isso capturando cada decisão significativa em um documento curto e estruturado. São uma das práticas de documentação de maior alavancagem em engenharia de software -- simples de adotar, baratas de manter e inestimáveis quando você precisa delas.

Este guia cobre tudo desde o básico até práticas avançadas: o que são ADRs, como escrevê-las, templates que você pode adotar hoje, armadilhas comuns e como integrar ADRs ao seu fluxo de trabalho com ferramentas modernas.

O Que é um Architecture Decision Record?

Um Architecture Decision Record é um documento curto que captura uma única decisão arquitetural. A ênfase está em única e curto:

• Única: Um ADR, uma decisão. "Usar PostgreSQL para o serviço de pedidos" é um ADR. "Definir toda a estratégia de banco de dados" é um documento de design, não um ADR.
• Curto: Um ADR deve caber em uma página. Se for mais longo, você provavelmente está documentando múltiplas decisões ou incluindo detalhes demais de implementação.

O conceito foi popularizado por Michael Nygard em um post de blog de 2011. Desde então, ADRs foram adotados por organizações que vão de startups a governos. O UK Government Digital Service, Spotify e inúmeras equipes de engenharia usam ADRs como prática padrão.

O Que os ADRs Capturam

Todo ADR responde quatro perguntas fundamentais:

1. Qual era o contexto? Que situação ou problema motivou esta decisão?
2. O que decidimos? Qual é a escolha arquitetural específica que fizemos?
3. Quais alternativas consideramos? Quais outras opções estavam na mesa?
4. Quais são as consequências? Quais trade-offs, riscos e implicações vêm com esta decisão?

Só isso. Quatro perguntas. Um ADR bem escrito pode responder todas as quatro em menos de uma página.

O Que ADRs Não São

• Não são documentos de design. ADRs não descrevem como algo é implementado. Eles descrevem por que uma abordagem particular foi escolhida.
• Não são RFCs. RFCs (Request for Comments) são propostas para discussão. ADRs documentam decisões concluídas (embora um ADR possa começar como proposta e transicionar para aceito).
• Não são atas de reunião. ADRs capturam o resultado, não a discussão que levou a ele.
• Não são documentação abrangente. ADRs complementam diagramas de arquitetura, specs de API e runbooks. Não os substituem.

O Template Padrão de ADR

Múltiplos templates de ADR existem, mas a maioria são variações da mesma estrutura central. Aqui está um template prático que equilibra completude com brevidade:

# ADR-NNNN: [Título Curto Descrevendo a Decisão]

## Status

[Proposto | Aceito | Descontinuado | Substituído pelo ADR-XXXX]

## Data

[AAAA-MM-DD]

## Contexto

[Descreva a situação. Qual problema estamos resolvendo? Quais restrições
existem? Quais forças estão em jogo? Seja específico -- inclua números,
prazos, capacidades da equipe e requisitos técnicos onde relevante.]

## Decisão

[Declare a decisão de forma clara e concisa. Use voz ativa:
"Usaremos X" não "X deveria ser considerado."]

## Alternativas Consideradas

### [Alternativa 1]
- Prós: ...
- Contras: ...
- Por que rejeitada: ...

### [Alternativa 2]
- Prós: ...
- Contras: ...
- Por que rejeitada: ...

## Consequências

### Positivas
- [O que se torna mais fácil ou melhor]

### Negativas
- [O que se torna mais difícil ou pior]

### Riscos
- [O que pode dar errado]

## Decisões Relacionadas

- [Links para ADRs relacionados]

Detalhando Cada Seção

Status rastreia o ciclo de vida de uma decisão. O fluxo típico é: Proposto -> Aceito. Se as circunstâncias mudam, um ADR se torna Descontinuado ou Substituído por um ADR mais novo. Importante: você nunca deve excluir ADRs -- mesmo decisões rejeitadas são valiosas porque previnem equipes futuras de reconsiderar opções que já foram avaliadas.

Data estabelece quando a decisão foi tomada. Isso fornece contexto temporal: "Escolhemos esta tecnologia em 2024 quando nossa escala era X. Agora que nossa escala é 10X, devemos revisitar."

Contexto é a seção mais importante. Uma seção de contexto bem escrita dá aos leitores futuros informação suficiente para entender por que esta decisão fazia sentido na época, mesmo que as circunstâncias tenham mudado desde então. Inclua números específicos ("processamos 50K pedidos por dia"), restrições ("deve estar em conformidade com PCI-DSS") e fatores da equipe ("três engenheiros têm experiência com PostgreSQL, nenhum tem experiência com MongoDB").

Decisão deve ser inequívoca. "Usaremos PostgreSQL 16 como o armazenamento principal de dados para o serviço de pedidos" é bom. "Provavelmente devemos considerar um banco de dados relacional" não é um ADR -- é uma sugestão.

Alternativas Consideradas é a seção que mais economiza tempo a longo prazo. Quando um novo engenheiro pergunta "por que não usamos MongoDB?", a resposta está aqui. Quando a equipe revisita a decisão um ano depois, pode ver o que foi avaliado e por que foi rejeitado. Sem esta seção, equipes religam os mesmos debates infinitamente.

Consequências é sobre honestidade intelectual. Toda decisão tem trade-offs. Reconhecer as desvantagens constrói confiança e ajuda equipes futuras a entender quando circunstâncias podem justificar revisitar a decisão.

Um Exemplo Completo de ADR

Aqui está um ADR realista que demonstra o template na prática:

# ADR-0023: Usar Apache Kafka para Comunicação Entre Serviços

## Status

Aceito

## Data

2025-11-15

## Contexto

Nossa plataforma cresceu de 3 microsserviços para 12 no último ano.
Serviços atualmente se comunicam de forma síncrona via chamadas HTTP REST.
Isso cria vários problemas:

- Falhas em cascata: quando o serviço de inventário está fora,
  o serviço de pedidos não consegue processar pedidos, mesmo que
  verificações de inventário pudessem ser eventuais.
- Acoplamento forte: serviços precisam conhecer os contratos de API
  e endpoints uns dos outros.
- Gargalos de performance: algumas operações disparam cadeias de 4-5
  chamadas síncronas, adicionando latência.

Processamos aproximadamente 100K eventos por dia. Esperamos que isso
cresça para 500K em 12 meses. A equipe tem 8 engenheiros backend,
2 dos quais têm experiência prévia com Kafka.

## Decisão

Adotaremos Apache Kafka como o mecanismo principal para comunicação
assíncrona entre serviços. HTTP síncrono permanecerá para padrões
request/response onde o chamador precisa de um resultado imediato
(ex.: verificações de autenticação).

Usaremos Confluent Cloud como o provedor gerenciado de Kafka para
minimizar a sobrecarga operacional.

## Alternativas Consideradas

### RabbitMQ
- Prós: Mais simples de operar, curva de aprendizado menor, suporta
  múltiplos padrões de mensageria (pub/sub, ponto-a-ponto, roteamento).
- Contras: Menos adequado para padrões de event sourcing que planejamos
  adotar. Capacidades mais fracas de replay/rewind. O momento da
  comunidade mudou para Kafka para arquiteturas orientadas a eventos.
- Por que rejeitado: Antecipamos a necessidade de replay de eventos
  para auditoria e debugging. A arquitetura baseada em log do Kafka
  é mais adequada.

### AWS SQS + SNS
- Prós: Totalmente gerenciado, sem infraestrutura para manter,
  integração estreita com AWS.
- Contras: Vendor lock-in com AWS. Garantias limitadas de ordenação
  de mensagens. Sem processamento de stream integrado (precisaria de
  Kinesis ou Lambda). Custo por mensagem mais alto no nosso volume
  projetado.
- Por que rejeitado: Queremos evitar aprofundar o lock-in com AWS,
  e precisamos de entrega ordenada de mensagens para eventos financeiros.

### Manter HTTP Síncrono (com circuit breakers)
- Prós: Sem nova infraestrutura. Equipe já familiarizada. Circuit
  breakers tratam falhas em cascata.
- Contras: Não resolve acoplamento forte. Latência ainda se acumula
  nas cadeias de chamadas. Circuit breakers são um paliativo, não uma
  solução para o problema fundamental de acoplamento.
- Por que rejeitado: Trata sintomas, não causa raiz.

## Consequências

### Positivas
- Serviços se tornam desacoplados: produtores não precisam conhecer
  consumidores.
- Falhas em cascata eliminadas para workflows assíncronos.
- Replay de eventos habilita capacidades poderosas de debugging e
  auditoria.
- Base para padrões de event sourcing em serviços futuros.

### Negativas
- Complexidade operacional aumenta (cluster Kafka, schema registry,
  gestão de consumer groups). Mitigado pelo uso do Confluent Cloud.
- Equipe precisa de treinamento em conceitos e padrões do Kafka.
- Consistência eventual substitui consistência forte para fluxos
  assíncronos. Alguns workflows precisam de redesign.
- Debugging de fluxos async distribuídos é mais difícil que rastrear
  chamadas HTTP síncronas. Precisaremos de rastreamento distribuído
  (ver ADR-0024).

### Riscos
- Se o volume de mensagens exceder os tiers de preço do Confluent
  Cloud, custos podem aumentar significativamente. Monitorar e
  configurar alertas.
- Evolução de schema entre serviços requer disciplina. Planejar
  adoção de Avro com schema registry.

## Decisões Relacionadas

- ADR-0024: Adotar OpenTelemetry para Rastreamento Distribuído
- ADR-0018: Contratos de Comunicação entre Serviços (substituído por este ADR)

Este ADR tem cerca de 400 palavras. Levou talvez 20 minutos para escrever. Vai economizar horas de reuniões nos próximos anos.

Quando Escrever um ADR

Nem toda escolha técnica precisa de um ADR. Escolher entre duas bibliotecas JSON não justifica um. Mas algumas decisões definitivamente justificam.

Escreva um ADR Quando:

• A decisão afeta a estrutura do sistema. Qualquer coisa que mude como serviços se comunicam, onde dados residem ou como componentes são organizados.
• A decisão é cara de reverter. Escolher um banco de dados, um sistema de mensageria ou uma plataforma de deployment. Se desfazer esta decisão leva mais de uma sprint, documente por que você a tomou.
• Múltiplas opções viáveis existem. Se a escolha é óbvia, não precisa de ADR. Se você debateu entre três opções, capture o raciocínio.
• A decisão cruza fronteiras de equipes. Qualquer escolha arquitetural que afeta outras equipes deve ser documentada para que elas entendam o racional.
• O você do futuro pode questionar a escolha. Se há qualquer chance de que alguém (incluindo o você do futuro) pergunte "por que fizemos isso?", escreva agora.

Pule o ADR Quando:

• A escolha segue um padrão estabelecido da equipe (ex.: "sempre usamos Go para serviços backend" não precisa de um novo ADR para cada serviço)
• A decisão é trivialmente reversível (renomear uma variável, escolher um formatador de código)
• A decisão é puramente cosmética (estilo de código, convenções de nomenclatura -- pertencem a um guia de estilo)

Ciclo de Vida e Governança de ADRs

O Ciclo de Vida

ADRs têm um ciclo de vida natural:

1. Rascunho/Proposto: Alguém identifica uma decisão que precisa ser tomada e escreve um rascunho de ADR. A equipe discute.
2. Aceito: A equipe concorda com a decisão. O status do ADR muda para Aceito.
3. Ativo: A decisão está em vigor. O ADR serve como documentação de referência.
4. Substituído: Uma nova decisão substitui esta. O ADR antigo recebe o status "Substituído pelo ADR-XXXX". O novo ADR referencia o antigo.
5. Descontinuado: A decisão não é mais relevante (talvez o sistema ao qual se aplicava foi descomissionado).

Importante: nunca exclua ADRs. Mesmo os descontinuados ou substituídos são valiosos. Eles formam uma linha do tempo da evolução arquitetural.

Numeração

Use números sequenciais: ADR-0001, ADR-0002, etc. O número fornece ordenação cronológica e torna ADRs fáceis de referenciar em conversas: "como decidido no ADR-42."

Algumas equipes usam numeração baseada em data (ADR-2026-03-27-kafka) mas números sequenciais são mais simples e mais amplamente usados.

Cadência de Revisão

Defina um lembrete trimestral para revisar seus ADRs:

• Alguma decisão aceita não é mais válida?
• Restrições mudaram que invalidam premissas?
• Existem decisões que a equipe tomou informalmente que deveriam ser capturadas?

Esta revisão previne deterioração dos ADRs e mantém a coleção atual.

Onde Armazenar ADRs

As abordagens mais comuns, em ordem de recomendação:

No Repositório de Código

Armazene ADRs em docs/adr/ ou docs/decisions/ dentro do seu repositório. Esta é a abordagem mais popular e com razão:

• ADRs são versionados ao lado do código que descrevem
• Aparecem em pull requests e code reviews
• Não podem ser órfãos em uma wiki que ninguém visita
• São descobríveis via grep ou busca

Convenção: um arquivo markdown por ADR, nomeado com o número e um slug:

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

Em uma Ferramenta Dedicada de Arquitetura

Ferramentas como o Archyl fornecem gestão de ADR integrada com capacidades adicionais:

• Vincular ADRs diretamente a elementos do modelo C4 (containers, componentes, relacionamentos)
• Buscar e filtrar ADRs em todos os projetos
• Rastrear status e ciclo de vida dos ADRs
• Conectar ADRs a regras de conformidade que aplicam a decisão

A principal vantagem de uma ferramenta de arquitetura é o contexto. Quando um desenvolvedor olha o container PostgreSQL em um diagrama C4, pode clicar para ver o ADR que explica por que PostgreSQL foi escolhido. A decisão e a arquitetura estão conectadas, não isoladas.

Em uma Wiki (Não Recomendado)

Wikis (Confluence, Notion, etc.) são onde ADRs vão para serem esquecidos. São desconectadas do código, difíceis de descobrir e raramente mantidas. Se você precisa usar uma wiki, pelo menos faça referências cruzadas dos ADRs a partir do repositório de código.

Integrando ADRs ao Seu Fluxo de Trabalho

Faça ADRs Parte dos Pull Requests

Para mudanças arquiteturais significativas, exija um ADR como parte do pull request. Adicione uma seção ao seu template de PR:

## Impacto na Arquitetura

- [ ] Sem mudanças arquiteturais
- [ ] ADR criado/atualizado: [link]

Isso normaliza a criação de ADRs e garante que decisões sejam documentadas quando são tomadas, não semanas depois quando o contexto se dissipou.

Use ADRs em Revisões de Arquitetura

Durante revisões de arquitetura ou discussões de design, referencie ADRs existentes. "Antes de redesenhar isso, vamos verificar o que o ADR-15 diz sobre por que escolhemos essa abordagem." Isso dá visibilidade aos ADRs e reforça o hábito de documentar decisões.

Conecte ADRs a Diagramas de Arquitetura

É aqui que ADRs se tornam verdadeiramente poderosos. Quando um ADR é vinculado a um elemento específico no seu modelo C4, isso cria um grafo de conhecimento navegável:

• Clique no container Kafka no seu diagrama de Container -> veja o ADR-0023 explicando por que Kafka foi escolhido
• Clique no banco de dados PostgreSQL -> veja o ADR-0001 explicando a seleção do banco de dados
• Clique no API Gateway -> veja o ADR-0012 explicando por que Kong foi escolhido ao invés de roteamento customizado

No Archyl, você pode vincular ADRs a qualquer elemento C4 -- sistemas, containers, componentes ou relacionamentos. Essa conexão significa que decisões arquiteturais não são documentos flutuantes; estão ancoradas nas partes específicas da arquitetura que afetam.

Automatize o Que Puder

Várias ferramentas podem reduzir a fricção da gestão de ADRs:

• adr-tools (por Nat Pryce): Uma ferramenta de linha de comando para criar e gerenciar ADRs em um repositório. Execute adr new "Use Kafka for messaging" para gerar um novo ADR a partir de um template.
• Log4brains: Gera um site pesquisável e navegável a partir dos seus arquivos markdown de ADR.
• Archyl: Gerencia ADRs com vinculação a elementos C4, rastreamento de status e busca entre projetos.

Práticas Avançadas de ADR

ADRs Leves (LADRs)

Algumas equipes acham até o template padrão pesado demais. Um ADR Leve é apenas três frases:

No contexto de [situação],
decidimos [decisão],
para alcançar [objetivo],
aceitando [trade-off].

Exemplo:

No contexto de necessitar comunicação entre serviços que tolere
indisponibilidade de serviços, decidimos usar Apache Kafka via
Confluent Cloud, para alcançar desacoplamento de serviços e
capacidade de replay de eventos, aceitando complexidade operacional
aumentada e consistência eventual.

Este formato funciona bem para decisões que são importantes o suficiente para documentar mas não justificam um ADR completo.

Decision Logs

Um decision log é um documento único que lista todos os ADRs em ordem cronológica com resumos de uma linha. Serve como índice:

Isso dá uma visão rápida de todas as decisões sem abrir arquivos individuais de ADR.

ADRs para Decisões Não Técnicas

ADRs não se limitam a escolhas tecnológicas. Equipes os usam para:

• Decisões de processo: "Faremos pair programming para código crítico de segurança"
• Decisões organizacionais: "A equipe de plataforma é responsável por todos os containers de infraestrutura"
• Decisões de fornecedor: "Usaremos Datadog para monitoramento ao invés de construir internamente"

Se a decisão é significativa e reversível-mas-custosa, um ADR é apropriado independentemente de ser estritamente "arquitetural."

Armadilhas Comuns

Escrever ADRs Depois do Fato

O melhor momento para escrever um ADR é durante o processo de tomada de decisão. Escrever um semanas depois significa que você esqueceu as nuances, as alternativas consideradas e as restrições que existiam. Faça da escrita de ADR parte do processo de decisão, não uma reflexão tardia.

Torná-los Muito Longos

Se seu ADR excede uma página, você provavelmente está documentando múltiplas decisões (separe-as) ou incluindo detalhes de implementação (guarde para um doc de design). A disciplina da brevidade força clareza.

Não Documentar Alternativas Rejeitadas

A seção "Alternativas Consideradas" é a parte mais valiosa de um ADR a longo prazo. Sem ela, engenheiros futuros proporão as mesmas alternativas, sem saber que já foram avaliadas e rejeitadas. Sempre explique o que você não escolheu e por quê.

Abandonar a Prática

Um ou dois ADRs não fornecem muito valor. Cinquenta ADRs acumulados ao longo de dois anos se tornam uma base de conhecimento inestimável. A tentação de parar de escrever ADRs quando as coisas ficam corridas é forte. Resista. Os 15 minutos que você gasta escrevendo um ADR pouparão horas de reuniões depois.

Não Revisar ou Atualizar Status

Uma coleção de ADRs onde metade das decisões estão desatualizadas é enganosa. Agende revisões trimestrais. Marque decisões substituídas. Mantenha a coleção confiável.

Por Que ADRs São Ainda Mais Importantes na Era da IA

À medida que agentes de IA se tornam participantes ativos no desenvolvimento de software, ADRs ganham nova importância. Um agente de IA escrevendo código pode ler seus ADRs e entender:

• Por que certas tecnologias foram escolhidas (e devem continuar sendo usadas)
• Quais alternativas foram rejeitadas (e não devem ser re-propostas)
• Quais restrições existem (requisitos de conformidade, thresholds de performance)
• Quais trade-offs foram aceitos (consistência eventual, dependências de fornecedores)

Através do MCP server do Archyl, agentes de IA como Claude Code podem acessar seus ADRs antes de fazer sugestões arquiteturais. Ao invés de propor MongoDB para um serviço onde você já documentou por que PostgreSQL foi escolhido, o agente respeita a decisão existente -- ou sinaliza explicitamente quando acha que a decisão deveria ser revisitada.

Isso torna ADRs não apenas documentação para humanos, mas guardrails para IA.

Começando Hoje

Se sua equipe ainda não usa ADRs, comece com estes três passos:

1. Escolha uma decisão recente. Pense em uma escolha arquitetural que sua equipe debateu no último mês. Escreva um ADR usando o template acima. Deve levar 15-20 minutos.

2. Armazene no seu repo. Crie um diretório docs/adr/ e adicione o arquivo. Inclua-o no seu próximo pull request para que a equipe veja.

3. Torne um hábito. Adicione um checkbox de "Impacto na Arquitetura" ao seu template de PR. Discuta ADRs na sua próxima reunião de arquitetura. A prática ganha momento assim que a equipe percebe o valor.

Da próxima vez que alguém perguntar "por que fizemos dessa forma?" -- e vai perguntar -- você terá a resposta.

Explore mais sobre documentação de arquitetura: O Que é o Modelo C4? | Melhores Práticas de ADR | Descoberta de Arquitetura com IA. Ou experimente o Archyl gratuitamente para gerenciar ADRs vinculados diretamente ao seu modelo C4.