O que são os Architecture Decision Records (ADRs) no Archgate — documentos legíveis por humanos combinados com regras verificáveis por máquina — e como eles impulsionam o lado da prevenção do loop de governança.
Um Architecture Decision Record (ADR) é um documento curto que captura uma única decisão arquitetural junto com seu contexto e suas consequências. Os ADRs respondem a duas perguntas: por que essa decisão foi tomada e quais são seus compromissos? A prática é bem estabelecida — equipes documentam há muito tempo decisões como “usamos Hono no backend” ou “rotas de API devem validar a entrada na fronteira”.
Tradicionalmente, os ADRs são passivos. Os desenvolvedores os leem (às vezes) e os seguem (com sorte). A percepção central do Archgate é que um ADR não deveria apenas descrever uma regra — ele deveria aplicá-la.
Duas expressões de uma decisão
Seção intitulada “Duas expressões de uma decisão”Todo ADR no Archgate tem duas expressões:
- Um documento legível por humanos — Markdown com frontmatter YAML, escrito de forma que tanto desenvolvedores quanto agentes de IA entendam a intenção, o contexto e a justificativa.
- Regras verificáveis por máquina — um arquivo complementar opcional que verifica a conformidade automaticamente.
Quando um agente de IA trabalha em um projeto governado pelo Archgate, ambas as expressões atuam ao mesmo tempo:
- O agente lê o documento do ADR como contexto, moldando o que ele gera — isto é prevenção.
- As regras automatizadas validam a saída, capturando o que o agente deixou passar — isto é detecção.
O que existe dentro de um ADR
Seção intitulada “O que existe dentro de um ADR”Cada documento de ADR segue uma estrutura consistente para que humanos e agentes sempre saibam onde procurar:
- Frontmatter — metadados legíveis por máquina: um
idúnico (comoBE-003), umtitle, umdomain, se ele temrulese globsfilesopcionais que delimitam quais arquivos suas regras verificam. - Contexto — o problema que motivou a decisão e as alternativas que foram consideradas e rejeitadas.
- Decisão — a decisão em si, declarada de forma prescritiva. É a seção a que os agentes de IA prestam mais atenção ao decidir como escrever código.
- Faça e Não Faça — orientação concreta e verificável que funciona como uma lista de verificação de referência rápida para desenvolvedores e agentes.
- Consequências — os resultados positivos, os compromissos aceitos e os riscos (cada um com uma mitigação).
- Conformidade e Aplicação — como a decisão é aplicada, tanto por regras automatizadas quanto por revisão manual.
- Referências — links para ADRs relacionados e fontes externas.
Os ADRs são agrupados em domínios (backend, frontend, data, architecture, general, além de qualquer domínio personalizado que um projeto registre). O domínio determina o prefixo do ID — um ADR de backend é BE-001, um ADR de arquitetura é ARCH-001 — e permite que a skill reviewer e o archgate review-context restrinjam os briefings de ADR apenas aos domínios que uma alteração toca.
Como os ADRs chegam ao seu agente de IA
Seção intitulada “Como os ADRs chegam ao seu agente de IA”Os plugins de editor carregam os ADRs aplicáveis no seu agente automaticamente antes de cada tarefa de codificação — sem copiar e colar decisões nos prompts. O plugin pergunta à CLI quais ADRs se aplicam aos arquivos sendo alterados, recebe briefings condensados (a Decisão e o Faça e Não Faça de cada um) e o agente escreve código respeitando essas restrições. O loop de governança explica como isso se encaixa de ponta a ponta.
Começando a partir de decisões comprovadas
Seção intitulada “Começando a partir de decisões comprovadas”Você não precisa escrever cada ADR do zero. O registro de packs de ADR fornece coleções de ADRs curadas e testadas — rigor de TypeScript, padrões de testes, baselines de segurança e mais — que você importa e adapta ao seu projeto.