Porque os ADRs Voltaram ao Destaque
Architecture Decision Records originaram-se em 2011 pelo trabalho de Michael Nygard, estabelecendo o padrão de armazenar uma decisão por ficheiro markdown em repositórios. O MADR (Markdown Architectural Decision Records) evoluiu este formato, atingindo a versão 4.0.0 em setembro de 2024.
A mudança crítica: LLMs reduzem o tempo de produção de 30-40 minutos para 3-5 minutos, enquanto criam um benefício secundário — os ADRs tornam-se contexto para agentes IA como o Claude Code.
O Template de 7 Secções
O framework estende o template original de Nygard com três adições críticas:
- Status com datas e agendamentos de revisão
- Contexto baseado em factos e métricas, não narrativa
- Decisão começando com linguagem directa ("Adoptamos X")
- Consequências com impactos negativos obrigatoriamente listados
- Alternativas com raciocínio concreto de rejeição
- Conformidade especificando como a adesão à decisão é validada
- Data de Revisão com gatilhos para reabertura da discussão
O Prompt Master em XML
Em vez de responder a respostas interrogativas do Claude, a abordagem inverte a interacção usando estrutura XML:
<task>
Gera um ADR em formato MADR estendido...
</task>
<contexto_bruto>
[Contexto bruto da decisão com factos, números, alternativas consideradas]
</contexto_bruto>
<regras_anti_alucinacao>
Não inventes métricas. Sinaliza informações críticas em falta.
</regras_anti_alucinacao>Esta estrutura produz ADRs em primeiro rascunho em 30 segundos com 3-4 minutos de refinamento humano antes do commit.
Três Anti-padrões Destrutivos
- ADR Fantasma: documentos com campos Status desactualizados, criando autoridade falsa para decisões superadas. Prevenção: campos de Data de Revisão obrigatórios e auditorias trimestrais.
- ADR Romântico: documentos narrativos de múltiplas páginas sem articulação concreta da decisão. Prevenção: a primeira frase da Decisão deve começar com "Adoptamos X".
- ADR-CYA: documentos escritos para protecção do autor em vez de orientação do sucessor. Prevenção: voz activa, primeira pessoa do plural, regras anti-hedge nos prompts de revisão.