Architecture Decision Records: registre decisões técnicas antes de esquecê-las

1. O Problema: Por que decisões técnicas são esquecidas?

Você já se deparou com um trecho de código que usa uma biblioteca obscura e pensou: "Por que alguém escolheu isso?" Se a resposta não estiver em nenhum lugar documentado, você acabou de encontrar o problema que os Architecture Decision Records (ADRs) resolvem.

A armadilha da documentação informal é traiçoeira. Decisões importantes são tomadas em e-mails enterrados, conversas de chat perdidas ou reuniões que ninguém gravou. Três meses depois, o time original já mudou, e ninguém sabe por que o PostgreSQL foi escolhido em vez do MySQL, ou por que aquela arquitetura de microsserviços foi adotada.

O custo disso é alto: retrabalho, retomada de contexto demorada e decisões inconsistentes. Considere este caso real: uma equipe decidiu usar MongoDB para um módulo de relatórios porque "precisava de flexibilidade". Seis meses depois, um novo desenvolvedor sugeriu migrar para PostgreSQL, sem saber que a decisão original havia sido tomada após testes de performance com dados não estruturados. O resultado? Uma semana de discussão para redescobrir o que já se sabia.

2. O que é um Architecture Decision Record (ADR)?

Um ADR é um documento conciso que captura uma decisão arquitetural importante, seu contexto e suas consequências. O conceito foi popularizado por Michael Nygard em 2011, no artigo "Documenting Architecture Decisions". A estrutura canônica é simples:

  • Título: Número sequencial e nome descritivo
  • Contexto: O problema ou força motriz que exige uma decisão
  • Decisão: A escolha feita e sua justificativa
  • Consequências: Impactos positivos e negativos esperados

Diferente de documentação técnica tradicional (diagramas UML, especificações funcionais), o ADR foca no porquê — não no como. Enquanto um README explica como usar uma API, um ADR explica por que aquela API foi desenhada daquela forma.

3. O Ciclo de Vida de um ADR

Criação

Um ADR deve ser criado sempre que uma decisão arquitetural significativa for tomada. Isso inclui escolha de tecnologias, definição de padrões de comunicação entre serviços, decisões de banco de dados, etc. Idealmente, quem propõe a decisão escreve o ADR.

Revisão

ADRs devem passar por code review como qualquer outra mudança no código. Isso garante que o raciocínio seja validado pelo time e que não haja pontos cegos. Ferramentas como GitHub pull requests funcionam perfeitamente para isso.

Evolução

Decisões não são eternas. Um ADR pode ser substituído (superseded) por outro quando o contexto muda. A prática de versionamento permite rastrear toda a linha do tempo das decisões. Por exemplo:

ADR-0001: Escolha do banco de dados relacional
ADR-0002: Migração para banco NoSQL (substitui ADR-0001)

4. Template Prático e Exemplo Real

Template mínimo funcional

# ADR-[NÚMERO]: [TÍTULO DESCRITIVO]

## Contexto
[Descreva o problema, as forças em jogo e as alternativas consideradas]

## Decisão
[Descreva a decisão tomada e por que ela foi escolhida]

## Consequências
[Impactos positivos e negativos esperados]

Exemplo completo: Escolha entre SQLite e PostgreSQL para cache local

# ADR-0004: Escolha do SQLite como cache local para o módulo de relatórios

## Contexto
O módulo de relatórios precisa armazenar dados intermediários durante processamento noturno. 
Requisitos: baixa latência, sem dependência de rede, dados temporários (expurgo automático após 24h).
Alternativas consideradas: PostgreSQL (já usado em produção), Redis, SQLite.

## Decisão
Optamos pelo SQLite pelos seguintes motivos:
- Ausência de dependência de rede (dados locais)
- Overhead mínimo de configuração
- Perfil de uso compatível com acesso single-writer
- Expurgo automático via VACUUM programado

Redis foi descartado por exigir servidor separado. PostgreSQL por adicionar latência de rede desnecessária.

## Consequências
Positivas: redução de latência em 40%, simplificação de deploy, menor custo operacional.
Negativas: perda de dados em falha de nó (aceitável por serem temporários), limitação a 1 escritor concorrente.

5. Onde Armazenar e Versionar ADRs

A prática recomendada é armazenar ADRs no mesmo repositório do código, em uma estrutura de pastas padronizada:

/docs/adr/
├── 0001-escolha-do-banco-de-dados.md
├── 0002-padrao-de-comunicacao-entre-servicos.md
├── 0003-arquitetura-de-microsservicos.md
└── 0004-sqlite-para-cache-local.md

A nomeação segue o padrão [NÚMERO]-[TÍTULO-EM-PT-BR].md, garantindo ordenação cronológica e legibilidade.

Ferramentas como o ADR Tools (Node.js) automatizam a criação e o gerenciamento. Mas o essencial é usar Git para versionamento — cada ADR vira um commit, e o histórico fica rastreável.

6. Integração com a Cultura do Time

Introduzir ADRs sem criar burocracia é o maior desafio. Algumas estratégias práticas:

  • Comece pequeno: exija ADRs apenas para decisões com impacto em mais de um módulo
  • Use rituais existentes: inclua ADRs no template de pull request
  • Retrospectivas de decisões: a cada trimestre, revise ADRs antigos para ver se ainda fazem sentido
  • Onboarding: novos membros do time leem ADRs como parte do treinamento

Métricas de sucesso incluem redução de retrabalho (menos "vamos refazer porque ninguém lembra por que foi feito assim") e onboarding mais rápido (novos devs entendem o racional em horas, não semanas).

7. Armadilhas Comuns e Como Evitá-las

ADRs muito longos ou muito curtos

Um ADR não é um artigo acadêmico. Mantenha entre 200-500 palavras. Se precisar de mais detalhes, crie um documento complementar.

Decisões óbvias que não precisam de registro

Nem toda escolha merece um ADR. Decisões como "vamos usar tabs em vez de espaços" são melhor tratadas em guias de estilo. ADRs são para decisões arquiteturais com impacto duradouro.

O risco de documentar demais e parar de evoluir

Documentação excessiva pode paralisar. Lembre-se: ADRs são vivos. Se uma decisão se mostrar errada, crie um novo ADR que a substitua. O objetivo não é ter razão, é ter registro.

ADRs são ferramentas poderosas para preservar a memória técnica de um projeto. Eles transformam decisões implícitas em conhecimento explícito, reduzem o custo de onboarding e evitam que o time repita os mesmos erros. Comece hoje com um ADR simples — seu "eu" do futuro agradecerá.

Referências