Como documentar decisões técnicas com IA: ADRs que envelhecem bem (e o Claude que escreve com você)

Sexta à tarde. Você troca o broker de fila do projeto, alguém pergunta "por que não SQS?" e a resposta honesta é: "porque na época o Lucas tinha medo do custo, acho." Seis meses depois ninguém lembra mais. Aí vem a auditoria, vem o sucessor do Lucas, vem o agente de IA tentando refatorar e tropeçando na mesma decisão.

ADR — Architecture Decision Record — resolve isso há mais de uma década. Documento curto, uma decisão por arquivo, fica no repositório do lado do código. O problema nunca foi o conceito. Foi a dor de escrever. Em time pequeno, ninguém senta meia hora pra redigir um documento estruturado depois de uma decisão que já tomou.

Neste tutorial você vai sair com um template de ADR em 7 seções que envelhece bem, um prompt mestre em XML para o Claude extrair a decisão sem te interrogar e três anti-padrões que matam ADR em produção. A primeira versão sai em 4 minutos. Você gasta os próximos 10 ajustando.

TL;DR

• O que é: fluxo Claude + template estruturado para gerar ADRs sem dor.
• Stack/Modelos: Claude (Web, API ou Claude Code), Markdown, pasta docs/adr/ no repo.
• Custo/Acesso: funciona no plano gratuito da Anthropic; em produção, ~1k tokens de saída por ADR.
• Template referência: MADR 4.0.0, superset do clássico de Michael Nygard.

Por que ADR voltou ao radar (e por que IA muda a equação)

ADR não é moda. Nasceu em 2011, num post do Michael Nygard chamado "Documenting Architecture Decisions". A ideia é boba e poderosa: cada decisão arquitetural significativa vira um arquivo .md no repositório, com Status, Contexto, Decisão e Consequências. Imutável. Versionado. Reviewable como código.

O formato evoluiu pra MADR — Markdown Architectural Decision Records — que em setembro de 2024 chegou na versão 4.0.0. Microsoft adotou no Azure Well-Architected Framework. AWS publicou guia prescritivo próprio. Não é mais "técnica de arquiteto velho". É baseline.

O que mudou de uns dois anos pra cá é o custo de produzir.

Escrever ADR à mão sempre levou de 30 a 40 minutos. Você precisa lembrar o contexto, listar alternativas, articular consequências. Com LLM no meio, esse tempo cai para 3 a 5 minutos. E tem um bônus que ninguém esperava: o ADR vira contexto pro próprio agente. Claude Code, Cursor, Copilot — todos leem docs/adr/ antes de propor mudança. Você documenta uma vez, colhe duas: para humanos no PR e para a IA no próximo prompt.

A regra que o pessoal do adolfi.dev resumiu bem é: "Always create an ADR when changes are made to the codebase that affect the overall architecture". Vira instrução permanente do agente, não tarefa esquecida no Notion.

Pré-requisitos

Antes de continuar, garanta:

• [ ] Acesso ao Claude (Web, API ou Claude Code via claude CLI).
• [ ] Pasta docs/adr/ no repositório, com um README.md explicando o processo.
• [ ] Uma decisão recente real para usar de cobaia — vale escolha de banco, fila, framework, padrão de auth, qualquer coisa não-trivial.
• [ ] 10 minutos pra revisar o que a IA devolve. Não é "fire and forget".

Se você não tem docs/adr/ ainda, cria agora com um 0000-record-architecture-decisions.md registrando que vocês decidiram usar ADR. Sim, o primeiro ADR é sobre adotar ADR. É a piada interna do formato e funciona.

O template em 7 seções que envelhece bem

O Nygard original tem 4 campos: Status, Context, Decision, Consequences. Funciona. Mas três anos cuidando de ADRs em produção mostram que faltam três coisas que decidem se o documento vai sobreviver à passagem do tempo:

1. Alternatives — sem o que foi rejeitado, ninguém entende a decisão.
2. Compliance — como o time vai validar que a decisão está sendo seguida.
3. Review Date — quando o debate pode ser reaberto sem culpa.

O template fica assim:

# ADR-NNNN: <título curto e descritivo>

## Status

Accepted — 2026-05-27
Revisão prevista: 2026-11-27
Substitui: ADR-0007

## Context

Por que essa decisão existe. Qual problema, restrições técnicas, restrições
de negócio, prazo, time. Nada de prosa motivacional — fato e número.

## Decision

A escolha. Uma sentença direta no começo ("Vamos usar X"), depois 1-2
parágrafos explicando o porquê em termos verificáveis.

## Consequences

### Positivas
- Bullet com benefício concreto e mensurável.

### Negativas
- Bullet com custo, dívida ou limitação assumida.
- Sim, sempre tem negativa. Se não tem, você não pensou.

## Alternatives

### Opção B: <nome>
- Por que foi descartada (motivo concreto, não "não se encaixou").

### Opção C: <nome>
- Por que foi descartada.

## Compliance

Como o time valida que essa decisão está sendo seguida. Linter, teste,
revisão de PR, métrica. Algo automatizável ou ritual claro.

## Review Date

2026-11-27 — gatilhos para reabrir antes: <condições>.

Por que cada campo importa:

• Status com data — Accepted — 2026-05-27 é diferente de Accepted. Status muda; sem data, vira fóssil.
• Revisão prevista — força ritmo. Decisão sem data de revisão é decisão eterna por inércia.
• Consequências negativas obrigatórias — o TechTarget elenca como prática essencial. Sem ônus listado, você não pensou no trade-off — só vendeu a escolha.
• Compliance — o calcanhar de Aquiles do ADR. "Vamos usar Postgres" sem dizer como o time evita um Mongo aparecer em três meses é só intenção.

O prompt mestre em XML que extrai a decisão

A pegadinha de pedir ADR pro Claude solto é o interrogatório. Você digita "me ajuda a escrever um ADR sobre fila" e ele responde com 12 perguntas. Aí você desiste.

A solução é inverter: você dá o contexto bruto e pede pro Claude inferir, perguntando só o que for genuinamente ambíguo. XML estrutura isso melhor do que prompt em prosa porque o Claude foi treinado para tratar tags como blocos semânticos.

<task>
Gere um ADR no formato MADR estendido (7 seções) sobre a decisão descrita
abaixo. Escreva em português técnico, frases curtas, sem floreio.
</task>

<contexto_bruto>
Estamos trocando o broker de fila do projeto. Hoje rodamos RabbitMQ em
container no mesmo cluster da app. Volume médio de 80k mensagens/dia,
picos de 500k. Time de 4 devs, ninguém com expertise em ops de mensageria.
Custo atual: ~R$ 200/mês de infra. Decisão tomada hoje em call: vamos pra
AWS SQS. Motivos: tirar peso de ops, billing por uso, integração nativa
com Lambda que já usamos. Considerei também Google Pub/Sub (descartado
por estarmos full AWS) e SNS+SQS combinado (descartado por complexidade
desnecessária pro nosso fan-out atual de 1:1).
</contexto_bruto>

<formato_saida>
- Markdown puro, pronto pra commitar em docs/adr/.
- Numere como ADR-NNNN (peça pro usuário o próximo número se não souber).
- Status: Accepted, com data de hoje e revisão em 6 meses.
- Seções obrigatórias: Status, Context, Decision, Consequences (positivas
  e negativas, mínimo 3 cada), Alternatives (com razão concreta de
  rejeição), Compliance (mecanismo verificável), Review Date.
- Sem prosa vendedora. Toda afirmação deve ser verificável ou ter número.
</formato_saida>

<regras_anti_alucinacao>
- Se faltar informação crítica (ex: SLA, custo estimado, owner), liste
  no final em <perguntas_abertas>. Não invente número.
- Não cite ferramenta que não foi mencionada no contexto_bruto.
- Não escreva "considerar no futuro" — ADR documenta o presente.
</regras_anti_alucinacao>

Rode esse prompt no Claude Web, na API ou direto no claude CLI dentro do repo. O bloco <contexto_bruto> é a única parte que muda entre ADRs. Mantenha as outras tags constantes — vira o seu "estilo de casa".

A primeira versão chega em 30 segundos. Você gasta 3 a 4 minutos lendo, ajustando dois números, removendo um adjetivo. Comita.

Quando o Claude responder com <perguntas_abertas>, leve a sério. Se ele perguntou, é porque o contexto bruto tinha buraco — e o ADR não pode sair com buraco.

Três anti-padrões que matam ADR

A pesquisa de anti-padrões em decisão arquitetural é vasta. Mark Richards e Neal Ford catalogaram vários no "Fundamentals of Software Architecture". Três aparecem em todo time que tenta adotar ADR e desiste.

1. ADR fantasma

Status diz Accepted — 2023-08-14. Estamos em 2026. A decisão foi superada em 2024 e ninguém atualizou o arquivo. Pior: o novo dev lê o ADR, acredita, e implementa em cima de premissa morta.

Como evitar: campo Review Date no template + ritual trimestral de varrer ADRs vencidos. Em time pequeno, vira tarefa de 30 minutos no início do quarter. Quem cuidou daquela área levanta a mão, atualiza status para Superseded ou Deprecated, cria o ADR substituto referenciando o antigo.

2. ADR-romance

Quatro páginas de divagação. Três parágrafos de história do projeto. Um glossário no meio. Nenhuma decisão concreta articulável em uma sentença.

Esse padrão aparece principalmente quando a IA é usada solta, sem template restritivo. O modelo gosta de escrever bonito. Você precisa cortar.

Como evitar: regra dura no prompt — "a primeira sentença da seção Decision precisa começar com 'Vamos usar X'". Se não couber assim, a decisão não está madura o suficiente pra virar ADR. Volta pra discussão.

3. ADR-CYA (Covering Your Assets)

O anti-pattern catalogado por Richards e Ford: documento escrito pra blindar o autor de culpa futura, não pra ajudar quem vai herdar o sistema. Aparece como excesso de "considerando" e "dependendo de", zero compromisso.

A IA acentua isso se você não cortar. Modelos são treinados pra ser hedge-friendly. Eles adoram "pode-se considerar", "uma abordagem possível seria". Em ADR isso é veneno.

Como evitar: no prompt, regra explícita — "use voz ativa, primeira pessoa do plural, sem hedge". E na review humana: se a frase pode ser apagada sem mudar a decisão, apaga.

FAQ

Preciso de ADR para CRUD?

Não. ADR é para decisão arquiteturalmente significativa — aquela que é cara de reverter ou afeta múltiplos módulos. Escolha de framework, padrão de auth, estratégia de cache, modelo de tenancy, broker de mensageria. Endpoint REST novo não vira ADR.

Como integrar com PR review?

Convenção simples: PR que toca decisão arquitetural significativa precisa referenciar um ADR existente ou criar um novo na mesma branch. Quem revisa o PR revisa o ADR junto. O TechTarget cobre essa prática como uma das oito essenciais. Linter custom em CI ajuda — se PR mexe em config/queue.php e não tem ADR vinculado, falha.

Monorepo: um ADR global ou por serviço?

Por serviço, com pasta services/<nome>/docs/adr/. Decisões transversais (auth compartilhada, observabilidade, padrão de schema) vão em docs/adr/ na raiz. Numeração independente por pasta.

E o Claude alucina decisão que não existe?

Por isso a tag <regras_anti_alucinacao> no prompt mestre. Se você não passa número de custo, ele não inventa — vai pra <perguntas_abertas>. Sempre revise antes de comitar. O fluxo IA não substitui a leitura humana, ele só elimina a dor de começar do zero.

Fechando

ADR é uma daquelas práticas que todo dev sênior recomenda e poucos times mantêm. O motivo nunca foi o conceito — era o custo de escrever. Com Claude no fluxo, a primeira versão sai em 4 minutos, o template em 7 seções dá esqueleto que envelhece bem e os três anti-padrões viram checklist de revisão.

O próximo passo natural é integrar isso ao ciclo de PR e deixar o Claude Code ler docs/adr/ antes de propor mudanças — aí o ADR para de ser documento parado e vira contexto operacional. Esse tipo de fluxo prático é o que rola toda semana na Beer and Code, a melhor comunidade de AI engineering em português, com grupo no WhatsApp aberto pra quem está construindo IA em produção.

Decisão que não está escrita é decisão que vai ser refeita. Comece pelo primeiro ADR hoje. Os outros vêm.