Architecture Decision Records (ADR): registre decisões sem criar burocracia
O código mostra como o sistema funciona, mas raramente explica por que ele tomou aquela forma. Aprenda a usar ADRs para preservar contexto, alternativas e trade-offs sem transformar arquitetura em burocracia.
software architecture
architecture decisions
documentation
best practices
Ednaldo Luiz
Nível: Intermediário
Nível:
Publicado:
Última atualização:
20 min de leitura
visualização: - visualização
Introdução
Sabe aquela decisão de arquitetura que parecia óbvia quando foi tomada?
O time escolheu PostgreSQL, colocou uma fila entre dois serviços, adotou um provedor de identidade ou decidiu manter o sistema como monólito modular.
Na época, provavelmente existiam bons motivos.
A escolha podia ter sido influenciada por um prazo apertado, pela capacidade operacional da equipe, por uma exigência regulatória ou simplesmente porque o volume ainda não justificava uma solução mais complexa.
Alguns meses depois, porém, sobra apenas a implementação.
O código mostra o que foi construído, mas não explica por que aquela opção venceu, quais alternativas foram rejeitadas e qual preço o time aceitou pagar.
Então alguém pergunta:
Por que fizemos desse jeito?
Se ninguém lembra, a resposta precisa ser reconstruída em commits, tickets antigos, mensagens no Slack e conversas com pessoas que talvez nem estejam mais na empresa.
Isso costuma levar a dois comportamentos ruins.
O primeiro é tratar a arquitetura existente como intocável:
Deve existir algum motivo. Melhor não mexer.
O segundo é alterar tudo sem conhecer o contexto:
Isso parece errado. Vamos refazer.
Nos dois casos, o time decide no escuro.
popularizou os Architecture Decision Records em 2011 justamente para preservar o raciocínio por trás de decisões arquiteturalmente significativas por meio de documentos pequenos, modulares e mantidos perto do projeto. Orientações atuais da Microsoft seguem a mesma ideia: a arquitetura de um sistema é o resultado acumulado de suas decisões, não apenas o diagrama atual.
Um Architecture Decision Record, ou ADR, registra uma decisão enquanto o contexto ainda está fresco.
Não para criar um cartório técnico ou documentar cada detalhe do código.
O objetivo é simples: evitar que decisões importantes percam o motivo que as tornou razoáveis.
TL;DR
Um ADR é um registro curto de uma decisão arquitetural relevante, incluindo o problema, os fatores que influenciaram a escolha, as alternativas avaliadas e as consequências aceitas.
Registre decisões com impacto duradouro, alto custo de reversão ou efeitos sobre estrutura, contratos, segurança, operação e atributos de qualidade.
O que um ADR realmente registra
Um Architecture Decision Record registra uma única decisão arquitetural e o raciocínio que a sustenta.
A coleção desses documentos forma o Architecture Decision Log, o histórico de decisões do sistema.
- 0000-adotar-adr.md
- 0001-usar-postgresql-gerenciado.md
- 0002-chamar-fulfillment-via-http.md
- 0003-publicar-eventos-com-outbox.md
Um ADR não precisa descrever toda a arquitetura.
Ele captura um ponto específico:
por que decidir
o que foi avaliado
o que ficou valendo
o preço aceito
Contexto
Alternativas
Decisão
Consequências
por que decidir
Contexto
→
o que foi avaliado
Alternativas
→
o que ficou valendo
Decisão
→
o preço aceito
Consequências
O template original do Nygard tem cinco campos: título, status, contexto, decisão e consequências. Cada arquivo cuida de uma decisão só, é curto, e continua no repositório mesmo depois de ser substituído.
É um ponto de partida, não um contrato. Se você bater o olho e sentir falta de owner, categoria ou escopo, pode acrescentar. Se tem um campo que ninguém preenche, pode tirar. O que precisa sobreviver é o raciocínio, não o formulário.
Uma decisão por arquivo. É isso que separa o ADR dos outros documentos que aparecem durante o desenvolvimento.
| Artefato | Pergunta principal | Papel no ciclo de vida |
|---|---|---|
| ADR | O que decidimos e por quê? | Preserva a decisão e seu contexto |
| Proposta técnica (RFC, Design Doc) | O que estamos propondo e como pode funcionar? | Explora, discute e detalha uma solução |
| Diagrama | Como o sistema está organizado hoje? | Representa estrutura, relações ou fluxos |
| Runbook | Como operar ou recuperar o sistema? | Orienta atividades operacionais |
| Postmortem | O que aconteceu no incidente e como evitar repetição? | Registra aprendizado operacional |
Um RFC pode originar um ADR. O RFC guarda a discussão mais ampla, os experimentos e os detalhes da proposta. O ADR registra o resultado depois que a escolha é concluída e aponta para esse material.
Um diagrama também pode ser atualizado como consequência da decisão. Mesmo assim, ele normalmente mostra como o sistema ficou, não todas as forças que levaram àquela forma.
O Government Digital Service britânico (GDS), que publica a orientação de arquitetura seguida pelo setor público do Reino Unido, reforça que ADR não é uma descrição completa da arquitetura. Ele deve conviver com diagramas, documentação técnica e outros artefatos, sem tentar substituí-los.
Uma forma simples de guardar essa diferença é:
A documentação de arquitetura mostra o sistema. O ADR explica uma escolha que ajudou o sistema a tomar aquela forma.
Quando uma decisão merece um ADR
O maior risco ao adotar ADRs é documentar demais.
Se cada atualização de biblioteca, nome de classe ou detalhe de implementação gerar um novo documento, o decision log rapidamente vira ruído.
A pergunta não é:
Esta decisão é técnica?
Quase todas são.
A pergunta correta é:
Esta decisão possui significado arquitetural suficiente para que seu contexto precise sobreviver?
Uma decisão é arquiteturalmente significativa quando mexe em estrutura, dependências, interfaces, atributos de qualidade ou técnicas de construção, e quando voltar atrás sai caro. Vale também quando existe mais de uma opção plausível e nenhuma orientação pronta para escolher entre elas.
Na prática, um ADR tende a valer a pena quando pelo menos uma destas condições aparece:
- Altera a estrutura do sistema: monólito modular ou microsserviços, comunicação síncrona ou assíncrona, separação de um domínio em outro serviço, arquitetura orientada a eventos.
- Afeta atributos de qualidade: disponibilidade, latência, consistência, segurança, observabilidade, recuperação de desastre, manutenibilidade.
- Cria um contrato duradouro: API pública, formato de eventos, schema persistido, estratégia de versionamento, protocolo entre times.
- Introduz uma dependência difícil de substituir: banco de dados, broker, framework principal, provedor de identidade, serviço proprietário de cloud.
- Possui alto custo de reversão: migração de dados, mudança de protocolo, alteração de topologia, contrato com fornecedor, modelo que exige reescrever vários consumidores.
- Afeta mais de um time ou sistema: autenticação corporativa, plataforma de observabilidade, convenção de eventos, estratégia comum de deploy, ownership de dados compartilhados.
- Representa uma exceção importante: às vezes o ADR não registra a adoção de um padrão, mas o motivo para não segui-lo.
Por exemplo:
Este serviço não utilizará o broker corporativo porque precisa operar em uma região onde ele ainda não está disponível.
Sem o ADR, a exceção pode parecer descuido.
Heurística prática
Daqui a um ano, alguém provavelmente perguntará “por que fizemos assim?”, e a resposta dependerá de informações que não estarão óbvias no código?
Se sim, provavelmente existe um ADR.
Algumas decisões normalmente não justificam um ADR:
- renomear uma classe;
- escolher entre duas formas equivalentes de escrever um loop;
- atualizar uma dependência de patch;
- adicionar um endpoint que segue um padrão já estabelecido;
- reorganizar um método privado;
- resolver um detalhe local e facilmente reversível.
A fronteira não será perfeita.
Tudo bem.
É melhor o time ter uma heurística clara e ajustá-la com o uso do que tentar inventar uma definição universal de “arquitetural”.
O que torna um ADR útil meses depois
Preencher um template não garante um bom ADR.
O teste é outro: daqui a seis meses, alguém vai abrir esse arquivo sem ter participado de nenhuma conversa. Essa pessoa precisa sair sabendo cinco coisas.
- Qual era o problema.
- O que estava em conflito.
- Por que uma opção ganhou.
- O que vocês aceitaram pagar por isso.
- Como perceber que a decisão deixou de valer.
Os cinco campos originais já dão conta disso. O acrescenta drivers, alternativas com prós e contras, confirmação e gatilhos de revisão. A Microsoft sugere registrar também o nível de confiança quando a decisão sai sob incerteza.
Nenhum desses campos é obrigatório. As perguntas abaixo ajudam a decidir quais valem no seu caso.
| Parte | Pergunta respondida | Erro comum |
|---|---|---|
| Título e status | Qual decisão está em discussão e qual é seu estado? | Usar títulos vagos como “Banco de dados” |
| Contexto | Que problema, fatos e restrições exigem uma decisão? | Começar defendendo a solução preferida |
| Drivers | Quais critérios têm mais peso? | Listar qualidades genéricas sem prioridade |
| Opções | Quais alternativas reais foram avaliadas? | Criar opções de fachada |
| Decisão | O que faremos e por que esta opção venceu? | Usar linguagem ambígua |
| Consequências | O que melhora, piora ou passa a exigir trabalho? | Registrar apenas benefícios |
| Confirmação | Como saberemos se a decisão foi implementada? | Fazer merge do documento e esquecer a execução |
| Gatilhos de revisão | Que mudança de contexto exige reconsideração? | Tratar a decisão como eterna |
O contexto vem antes da solução
Um contexto ruim começa assim:
Precisamos adotar Kafka para melhorar a escalabilidade.
A solução chegou antes do problema.
Um contexto melhor conta o que estava acontecendo:
O processamento síncrono de notificações aumenta a latência do checkout e propaga indisponibilidade do serviço de comunicação para a finalização de pedidos.
Agora dá para comparar Kafka, RabbitMQ, SQS ou uma tabela de jobs no banco. Talvez nenhum deles.
O contexto deve registrar fatos, restrições e suposições disponíveis naquele momento:
- volume esperado;
- meta de latência;
- prazo;
- orçamento;
- capacidade operacional;
- requisitos de segurança;
- ;
- limitações do fornecedor;
- nível de confiança das estimativas.
Isso não significa transformar o ADR em relatório de pesquisa.
Significa deixar claro sob quais condições a decisão foi razoável.
Drivers precisam ter prioridade
Driver é o critério que puxou a decisão: um requisito, uma restrição, uma meta de qualidade, um prazo. Muitas alternativas parecem boas quando todos eles têm o mesmo peso.
Por isso, registre os drivers que realmente determinaram a escolha:
- Reduzir o risco operacional
- Entrar em produção em oito semanas
- Preservar transações ACID
- Manter o custo dentro do orçamento aprovado
- Evitar dependência de tecnologia sem conhecimento no time
Essa ordem conta uma história.
Talvez a opção mais barata tenha sido rejeitada porque aumentava o risco operacional. Talvez a solução mais escalável tenha perdido porque o volume atual não justificava sua complexidade.
Uma lista sem ordem não conta nenhuma dessas histórias. “Avaliamos custo, segurança e performance” não diz qual dos três ganhou quando eles se chocaram.
Alternativas precisam ser reais
Uma opção de fachada existe apenas para fazer a escolhida parecer melhor.
- Opção A: banco gerenciado
- Opção B: construir nosso próprio banco distribuído
Isso não é comparação.
Um ADR honesto apresenta de duas a quatro opções plausíveis e inclui, quando fizer sentido, manter o estado atual.
Cada alternativa merece seu melhor argumento.
A pergunta não é:
Como provar que nossa escolha está certa?
É:
Qual opção atende melhor aos drivers dentro das restrições atuais?
Consequências registram o preço pago
Toda decisão arquitetural relevante troca uma propriedade por outra. Arquitetura é trade-off, e o ADR é onde o preço dessa troca fica escrito.
Escolher comunicação assíncrona pode melhorar isolamento de falhas, mas introduz consistência eventual, retries, idempotência e observabilidade adicional.
Escolher um serviço gerenciado pode reduzir trabalho operacional, mas aumentar custo e dependência do provedor.
Uma consequência fraca diz:
A solução aumentará a complexidade.
Uma consequência útil diz:
Os consumidores precisarão processar mensagens de forma idempotente porque a entrega poderá ocorrer mais de uma vez.
Quanto mais concreta a consequência, mais útil será o documento.
E se as consequências de um ADR são só ganho, a decisão não saiu perfeita. É que ninguém procurou o preço.
Confiança e gatilhos evitam decisões eternas
Nem toda decisão é tomada com informação completa.
Às vezes, o time precisa decidir com:
- estimativas ainda não validadas;
- benchmark limitado;
- fornecedor novo;
- carga futura incerta;
- prazo que impede uma prova de conceito maior.
Esconder essa incerteza não fortalece o ADR.
Faz o contrário.
Uma decisão pode ser aceita com confiança baixa ou moderada, desde que o documento registre as suposições e defina quando revisar.
Revisar esta decisão quando:
- o volume sustentado ultrapassar o cenário testado;
- o custo mensal exceder o limite aprovado;
- o fornecedor encerrar suporte ao recurso;
- um incidente mostrar que o RTO não está sendo atendido;
- uma nova região precisar ser suportada.
Decisão não precisa ser eterna para ser correta.
Ela precisa ser adequada ao contexto conhecido e revisável quando esse contexto mudar.
Confirmação fecha o ciclo
Um dos campos mais interessantes do MADR é Confirmation: como verificar que a implementação realmente respeita a decisão.
Num arquivo, um ADR aceito e um ADR que virou código são idênticos. A confirmação é o que separa os dois.
Ela aparece de duas formas, e as decisões que se sustentam costumam usar as duas:
- Prova de que aconteceu: o teste de restauração executado, o benchmark anexado, a revisão de segurança concluída, o Pull Request da implementação vinculado.
- Guarda que mantém verdadeiro: a regra de ArchUnit que barra a dependência proibida, o alerta que dispara quando a métrica sai da faixa, o contrato publicado que quebra o build de quem sair dele.
A primeira mostra que a decisão chegou ao sistema. A segunda evita que ela seja desfeita sem ninguém perceber, que é como uma arquitetura combinada vira outra coisa em silêncio.
Como ADR entra no fluxo do time
ADR funciona melhor quando participa do fluxo que o time já usa.
Criar outro portal, outra fila de aprovação e outra reunião obrigatória para cada decisão é a forma mais rápida de matar a prática.
Um fluxo simples pode ser:
- Identifique a decisão. O time encontra uma escolha com impacto arquitetural e define um owner. Uma pessoa conduz o registro, mas não decide sozinha.
- Escreva a proposta. O ADR nasce com status Proposed, contexto, drivers e alternativas. O documento deve começar enquanto a decisão ainda está aberta.
- Revise com quem será afetado. Abra um Pull Request e envolva os times ou especialistas necessários. O nível de revisão acompanha o risco e o raio de impacto.
- Aceite ou rejeite. Registre o resultado de forma explícita e faça merge do histórico. Um ADR rejeitado também merece existir: a próxima pessoa que cogitar a mesma ideia já sabe por que ela não vingou, sem repetir a investigação do zero.
- Implemente e confirme. Vincule issues, Pull Requests, testes e evidências. O trabalho termina quando a decisão chega ao sistema, não quando o Markdown é aprovado.
A AWS acrescenta um uso que o fluxo acima não cobre: os registros voltam depois, em code reviews e em decisões relacionadas. É o que tira o ADR da pasta e o coloca na conversa do dia a dia.
A governança acompanha o impacto
ADR não deve ser sinônimo de pedir permissão a um arquiteto.
Na prática, o escopo da revisão deveria acompanhar o raio de impacto da decisão:
O erro está nos extremos.
Sem revisão, o ADR vira justificativa individual: alguém decide sozinho e escreve o documento depois, só pra ter uma desculpa pronta caso alguém pergunte.
Com aprovação central para tudo, ele vira gargalo: toda decisão espera na fila por alguém que não vive o dia a dia daquele sistema.
O equilíbrio não vem de uma régua fixa de aprovações. Vem de conversar cedo com quem vai sentir o impacto e deixar quem está mais perto da decisão decidir.
Onde guardar
Para decisões locais de uma aplicação, a opção padrão mais simples é:
- seu-projeto/
- docs/
- adr/
- README.md
- 0000-adotar-adr.md
- 0001-usar-postgresql-gerenciado.md
- 0002-chamar-fulfillment-via-http.md
- 0003-publicar-eventos-com-outbox.md
- template.md
O README.md dessa pasta é o índice. É ele que transforma arquivos soltos em decision log, deixando o status de cada decisão visível sem abrir um registro por vez.
docs/adr/README.md
# Architecture Decision Log
| ADR | Decisão | Status |
| ---- | -------------------------------------- | ------------------ |
| 0000 | Adotar ADRs no time | Accepted |
| 0001 | Usar PostgreSQL gerenciado | Accepted |
| 0002 | Chamar Fulfillment via HTTP síncrono | Superseded by 0003 |
| 0003 | Publicar eventos de domínio com Outbox | Accepted |Markdown no mesmo repositório oferece:
- proximidade com o código;
- histórico de alterações;
- revisão por Pull Request;
- busca;
- links para commits e issues;
- atualização junto com a implementação.
Nygard, Google Cloud e GDS recomendam manter decisões próximas ao código relevante. Para decisões que afetam vários sistemas, um repositório ou índice central pode complementar os registros locais.
Uma divisão prática é:
- Decisão local de um serviço: ADR no repositório do serviço.
- Decisão transversal de plataforma: ADR no repositório arquitetural central.
- Decisão transversal implementada em vários serviços: ADR central, com links bidirecionais para os repositórios.
A fonte oficial precisa estar clara.
Copiar o mesmo ADR para Git, wiki e portal manualmente cria três versões concorrentes. Uma estratégia melhor é manter uma fonte de verdade e publicar sua visualização automaticamente onde outras pessoas precisam consultar.
A localização não é detalhe. Um estudo de action research publicado em 2024 mostrou que decisões distribuídas entre componentes e repositórios continuam difíceis de encontrar, mesmo depois da adoção de ADRs.
O estudo foi realizado em uma única empresa, portanto seus resultados não devem ser tratados como garantia universal.
Quando uma decisão muda
Seis meses depois, aquela decisão pode estar errada. Isso é normal, e não é motivo para apagá-la.
O ADR-0002 registrou que o Checkout chamaria o Fulfillment por HTTP síncrono. Meses depois, uma indisponibilidade do Fulfillment passou a derrubar o Checkout junto, e o time trocou a chamada por um evento PaymentConfirmed publicado via Transactional Outbox.
A saída não é editar o ADR-0002 até ele concordar com a decisão nova. É escrever o ADR-0003 e apontar um para o outro:
0002-chamar-fulfillment-via-http.md
# ADR-0002: Chamar Fulfillment via HTTP síncrono
* Status: Superseded
* Substituído por: ADR-00030003-publicar-eventos-com-outbox.md
# ADR-0003: Publicar eventos de domínio com Outbox
* Status: Accepted
* Substitui: ADR-0002Duas linhas em dois arquivos. Quem chegar depois enxerga a decisão antiga, a nova e a virada entre as duas.
O ADR-0002 não vira lixo quando o ADR-0003 chega. O histórico do Git tem a mudança, mas ninguém abre git log procurando decisão. O ADR-0002 é onde alguém encontra, sem saber que procura, que HTTP síncrono já foi tentado ali e o que custou descobrir que não servia.
Sem ele, daqui a um ano alguém propõe a chamada direta de novo, porque é mais simples, e ninguém tem como mostrar que o time já pagou para ver.
Nada disso proíbe editar um ADR. Uma política que costuma funcionar:
- Erro de digitação ou link quebrado: corrija direto.
- Explicação ambígua, sem mudar a decisão: esclareça por Pull Request.
- Consequência que apareceu depois: acrescente uma nota datada.
- Mudança de opção ou de direção: ADR novo.
- Decisão que nunca saiu do papel: marque como rejeitada ou abandonada, preservando o motivo.
O que não pode acontecer é mudar a decisão em silêncio e destruir a linha do tempo.
Substitua. Não apague.
Um template enxuto para começar
O melhor template não é o mais completo.
É aquele que o time consegue preencher com clareza e consultar depois.
O modelo abaixo combina a estrutura mínima de Nygard com alguns campos úteis do MADR: drivers, opções, confirmação e gatilhos de revisão. Todos os campos além de contexto, decisão e consequências podem ser simplificados quando não agregarem valor.
docs/adr/template.md
# ADR-NNNN: Título declarando a decisão
* Status: Proposed | Accepted | Rejected | Superseded
* Data: YYYY-MM-DD
* Owner: pessoa ou time
* Decisores: pessoas ou papéis envolvidos
* Substitui: ADR-NNNN, se aplicável
* Substituído por: ADR-NNNN, se aplicável
* Confiança: alta | média | baixa, se relevante
## Contexto e problema
Qual problema exige uma decisão?
Registre fatos, requisitos, restrições e suposições relevantes.
Evite defender uma solução nesta seção.
## Drivers da decisão
* Critério prioritário
* Atributo de qualidade relevante
* Restrição de prazo, custo ou operação
* Requisito de segurança ou conformidade
## Opções consideradas
### Opção A
* Vantagens:
* Desvantagens:
* Riscos:
### Opção B
* Vantagens:
* Desvantagens:
* Riscos:
### Manter o estado atual
* Vantagens:
* Desvantagens:
* Riscos:
## Decisão
Adotaremos [opção] porque [racional ligado aos drivers].
Não adotaremos [alternativas] porque [motivos relevantes].
Se a proposta inteira for rejeitada, registre aqui por que ela não avançou.
## Consequências
### Positivas
* Ganho esperado
### Negativas e riscos aceitos
* Custo, limitação ou nova responsabilidade
### Mitigações
* Ação usada para reduzir um risco aceito
## Confirmação
Como verificaremos que a decisão foi implementada e funciona?
* Pull Requests:
* Testes:
* Métricas:
* Evidências:
## Gatilhos de revisão
Que mudança de contexto exige reconsiderar esta decisão?
Prefira condições verificáveis a intenções: um limite numérico, uma suposição
que caiu, um incidente.
## Referências
* Proposta técnica (RFC, Design Doc)
* Issue
* Benchmark
* Diagrama
* Postmortem
* Documentação oficialNão torne todos os campos obrigatórios desde o primeiro dia.
Um ADR simples pode ter quarenta linhas.
Uma decisão mais sensível pode exigir benchmark, análise de segurança ou participação de vários times.
O tamanho deve acompanhar a importância e a incerteza, não a ansiedade documental.
Exemplo compacto
O exemplo abaixo é fictício, mas mostra como requisitos, capacidades do time e consequências podem aparecer sem transformar o ADR em um relatório.
0001-usar-postgresql-gerenciado.md
# ADR-0001: Usar PostgreSQL gerenciado no Checkout
* Status: Accepted
* Data: 2026-08-20
* Owner: Tech Lead do Checkout
* Decisores: Tech Lead do Checkout, SRE da plataforma e Segurança
* Confiança: média
## Contexto e problema
O Checkout guarda pedidos, pagamentos e transições de estado. Cobrar duas
vezes ou registrar um pagamento sem pedido são erros que não dá para
consertar depois, então precisamos de transação e integridade
referencial garantidas pelo banco.
O produto exige RTO de uma hora, RPO de cinco minutos e criptografia em
repouso.
Somos seis engenheiros e nenhum de nós já manteve um banco em produção.
O lançamento está previsto para oito semanas.
A projeção é de 40 mil pedidos por dia, picos de 300 por minuto em
campanha e menos de 500 GB de dados em doze meses. A confiança nesse
número é média: ele vem da estimativa de produto, não de tráfego
observado.
## Drivers da decisão
* Transação ACID e integridade referencial garantidas pelo banco.
* Fechar o RTO de uma hora sem depender de alguém acordado.
* Entrar em produção em oito semanas.
* Backup, restauração e failover que o time consiga testar.
* Ficar perto do que o time já sabe operar.
## Opções consideradas
### PostgreSQL 16 gerenciado
* Réplica em outra zona, backup contínuo e recuperação point-in-time
entregues pelo provedor.
* Custa cerca de três vezes uma máquina virtual equivalente.
* Sem superusuário e com lista fechada de extensões.
### PostgreSQL 16 autogerenciado
* Controle total, custo bruto menor, nenhuma extensão bloqueada.
* Coloca patching, replicação, upgrade de versão maior e plantão de
madrugada nas mesmas seis pessoas que estão construindo o Checkout.
### MySQL 8 gerenciado
* Atende os requisitos transacionais do Checkout sem ressalva.
* Descartado sem alegar superioridade técnica do PostgreSQL: os outros
dois serviços do time já rodam PostgreSQL, e manter dois dialetos
dobraria migrations, scripts de restauração e o que cada pessoa
precisa saber às três da manhã.
### CockroachDB gerenciado
* Sobrevive à perda de uma zona sem failover manual, escala na
horizontal sem sharding na aplicação e fala o protocolo do
PostgreSQL.
* No driver de disponibilidade, é a opção mais forte da lista.
* Ninguém no time operou o produto. Plano de execução, comportamento
sob contenção e custo por transação são diferentes o bastante para
que a primeira lição chegue durante um incidente de pagamento.
## Decisão
Usaremos PostgreSQL 16 gerenciado, com réplica em outra zona e
recuperação point-in-time.
Não operaremos o banco porque seis pessoas sem experiência de plantão em
banco não sustentam um RTO de uma hora com segurança.
Não usaremos MySQL porque a escolha faria o time manter dois dialetos
relacionais sem entregar nada ao Checkout em troca.
Não adotaremos CockroachDB agora. Ele resolve melhor um problema de
escala que ainda não temos, e o custo de aprender a operá-lo cairia
justamente nas oito semanas do lançamento. Se o gatilho de carga
disparar, é a primeira alternativa a reavaliar.
## Consequências
### Positivas
* Backup contínuo, réplica e failover ficam com o provedor.
* Restrições, chaves estrangeiras e transações moram no banco, não na
aplicação.
* O time reaproveita migrations, monitoramento e conhecimento de
plantão dos outros dois serviços.
### Negativas e riscos aceitos
* Cerca de 900 dólares por mês contra 300 de uma máquina virtual
equivalente.
* Sem superusuário: extensão fora da lista do provedor vira pedido de
suporte ou troca de plano.
* A escala é vertical até o maior tipo de instância. Depois disso, a
saída é particionar ou trocar de banco.
### Mitigações
* Não usar recurso proprietário do provedor sem registrar o motivo.
* Alertar sobre conexões, armazenamento, latência de commit e atraso da
réplica.
* Ensaiar a restauração uma vez por trimestre e anotar o tempo no
runbook.
## Confirmação
* Instância e réplica criadas por Terraform, sem ajuste no console.
* Restauração de um backup em ambiente separado, dentro de uma hora,
antes do go-live.
* Failover forçado em staging com o Checkout sob tráfego sintético.
* Alertas de capacidade e disponibilidade ligados ao canal de plantão.
## Gatilhos de revisão
* O custo passar de 1.500 dólares por mês.
* Um teste de restauração ou um incidente estourar o RTO de uma hora.
* O volume sustentado passar de 300 pedidos por minuto ou a base passar
de 500 GB.
* Uma extensão necessária não estar disponível no provedor.Repare no que o ADR não tenta fazer: não documenta todas as tabelas, não descreve migrations, não ensina a configurar o banco nem substitui o runbook de restauração.
E não define o RTO de uma hora, só obedece a ele.
Ele registra por que o PostgreSQL gerenciado foi escolhido e o que precisa continuar verdadeiro para a decisão permanecer válida.
Requisito entra no ADR como restrição que apertou a escolha, não como especificação. Se ele mudar, a mudança vem do produto, e o papel do ADR é disparar a revisão. O outro lado dessa fronteira é assunto do artigo sobre engenharia de requisitos.
Repare também na alternativa que perdeu tendo o melhor argumento técnico.
O CockroachDB atendia melhor o driver de disponibilidade e mesmo assim ficou de fora, porque a capacidade do time é uma restrição tão real quanto latência ou custo.
Quando ADR vira burocracia
ADR não é automaticamente leve só porque está em Markdown.
Um processo ruim consegue transformar até um arquivo de cinquenta linhas em sofrimento.
Cinco anti-patterns aparecem com frequência:
- Documentar tudo. O efeito visível é um log difícil de garimpar. O que mata a prática é o custo: quando toda escolha local exige um documento, escrever ADR vira imposto, e o time para de escrever até os que importam.
- Escrever depois que tudo já foi decidido. O documento retroativo racionaliza a opção escolhida e esquece as dúvidas que existiam de verdade. Comece durante a análise. Se o ADR for mesmo histórico, marque isso e declare as incertezas.
- Misturar várias decisões no mesmo documento. O ADR épico decide banco, mensageria, deploy e autenticação de uma vez. Se essas escolhas podem mudar de forma independente, elas precisam de registros separados e relacionados.
- Transformar o ADR em aprovação central. Se toda decisão espera a reunião mensal de um board, o time passa a decidir fora do processo e a documentar só para cumprir tabela.
- Aceitar sem implementar. O ADR foi aprovado, mas não tem owner, issue, Pull Request nem critério de confirmação. Isso não é uma decisão arquitetural implementada. É uma intenção arquivada.
ADR não é solução mágica
ADRs podem melhorar a transferência de contexto e tornar discussões mais explícitas, mas não corrigem sozinhos contratos ruins, ownership confuso ou decisões distribuídas entre vários sistemas.
O processo só funciona quando os registros são fáceis de encontrar, participam do fluxo de desenvolvimento e possuem diretrizes claras sobre o que documentar.
O estudo de 2024 citado anteriormente também mostrou o outro lado da moeda:
Introduzir ADRs melhorou a cultura de documentação e a transferência de conhecimento entre os times.
Também encontrou dificuldade para integrar ADRs ao trabalho diário. Isso é um bom antídoto contra o hype: o formato ajuda, mas organização e cultura continuam importando.
Comece pela próxima decisão
É tentador começar mapeando tudo que já foi decidido nos últimos dez anos.
Não faça isso. Você vai gastar semanas perguntando para quem já esqueceu, ou já saiu da empresa, e o que sair dali vai soar verdadeiro sem ser.
Comece pequeno, e comece pelo que ainda está em aberto:
- Crie o lugar. Uma pasta
docs/adre um README curto dizendo o que entra ali e como propor um registro. O time precisa saber onde escrever e onde procurar. - Fique no template mínimo. Contexto, decisão e consequências dão conta. Acrescente campo quando alguém sentir falta, não porque o modelo deste artigo tinha.
- Combine o que merece registro. Use decisões do próprio sistema como exemplo, não uma régua genérica. Essa conversa vale mais que o formato do arquivo.
- Escreva a próxima decisão difícil enquanto ela acontece. Abra o Pull Request, chame quem vai sentir o impacto, vincule a implementação. Nada de correr atrás de cinquenta escolhas antigas.
- Volte ao assunto em um mês. Campo que ninguém preencheu sai, índice desatualizado se corrige. E se nenhum ADR foi consultado nesse período, vale perguntar por quê antes de culpar o template.
O time também pode criar um ADR-0000 registrando a própria decisão de adotar ADRs: o que entra, onde fica, quais status valem e como uma decisão substitui outra. Tem a graça de a prática já nascer seguindo a própria regra.
Só não deixe o ADR sobre ADRs virar um projeto de governança de três meses.
Adotar a prática não precisa de reunião nem trimestre de planejamento.
Precisa de uma pasta, um arquivo e a próxima decisão que faria alguém perguntar:
Por que diabos fizemos assim?
É aí que a prática começa a pagar seu custo.
Antes de fechar, cinco perguntas sobre o que costuma separar um ADR útil de um arquivo esquecido:
Questão1/5
Entre as escolhas abaixo, qual mais provavelmente merece um ADR?
Conclusão
Código é excelente para mostrar como o sistema funciona.
Ele não guarda as alternativas que foram descartadas, nem as restrições da época, nem o preço que o time aceitou pagar.
E o resto do ferramental não cobre esse buraco: diagrama mostra componente, ticket acompanha trabalho, Pull Request registra alteração.
O ADR guarda o que sobra: o problema, as forças que apertavam, as alternativas que estavam na mesa, a escolha, o preço aceito e o que faria o time mudar de ideia.
Um bom ADR é pequeno, honesto e fácil de encontrar.
E não termina no Markdown. Ele passa por quem vai sentir o impacto, aponta para a implementação e é confirmado no sistema de verdade. Quando o contexto muda, outro toma o lugar sem apagar o anterior.
Esse é o ponto central:
ADR não existe para provar que o time acertou. Existe para preservar por que aquela escolha fazia sentido com as informações disponíveis.
Provavelmente existe uma decisão em aberto no seu time agora, daquelas que já apareceram em duas conversas e ainda não fecharam.
Antes de escolher a tecnologia, escreva três coisas:
- qual problema precisa ser resolvido;
- quais alternativas são realmente viáveis;
- qual consequência negativa o time aceita assumir.
Você já terá produzido a parte mais valiosa de um ADR.
Referências
A fonte original do formato de ADR e o template estruturado mais usado hoje.