Como o Archgate transforma os Architecture Decision Records em verificações de conformidade executáveis e determinísticas — a camada de detecção do loop de governança.
As regras são o lado executável de um ADR. Onde o documento do ADR explica uma decisão a humanos e agentes de IA, a regra verifica automaticamente essa decisão contra a base de código. As regras são o motor da camada de detecção: determinísticas, gratuitas de executar e rápidas o suficiente para viver em hooks de pre-commit e na CI.
Como as regras se relacionam com os ADRs
Seção intitulada “Como as regras se relacionam com os ADRs”Um ADR que tem rules: true em seu frontmatter carrega um arquivo de regras complementar ao lado do documento. Quando você executa uma verificação, o Archgate carrega cada ADR que declara regras, executa seu arquivo complementar contra o seu código e relata quaisquer violações com o caminho do arquivo e o número da linha onde ocorrem.
Esse emparelhamento é o que torna o Archgate mais do que um linter. A decisão e sua aplicação vivem juntas: a regra nunca se desvia da intenção documentada, porque são versionadas como uma única unidade e revisadas em conjunto. Quando a skill lessons-learned propõe uma nova regra, ela o faz como parte de um ADR — a justificativa e a verificação chegam juntas.
O que uma regra pode fazer
Seção intitulada “O que uma regra pode fazer”Uma regra inspeciona a base de código e relata achados. Conceitualmente, cada regra:
- Recebe o conjunto de arquivos em escopo — restringido pelos globs
filesdo ADR, com o conjunto de arquivos alterados disponível para verificações cientes de diff. - Lê e busca nesses arquivos (glob, leitura, busca por regex entre arquivos).
- Relata achados em uma de três severidades:
- error — uma violação rígida que faz a verificação falhar e bloqueia o merge.
- warning — um problema sinalizado que é apresentado ao desenvolvedor, mas não bloqueia.
- info — um aviso puramente informativo.
A severidade é o que permite ao loop de governança ser rigoroso onde importa e consultivo no resto. Erros são o portão rígido; avisos incentivam padrões melhores sem interromper o trabalho.
Onde as regras são executadas
Seção intitulada “Onde as regras são executadas”As mesmas regras são executadas em três lugares, dando a você defesa em profundidade:
| Local | Gatilho | Papel no loop |
|---|---|---|
| Editor | Depois que um agente de IA edita código | Feedback imediato durante o desenvolvimento |
| Pre-commit | Antes de o código ser preparado para commit | Portão local rápido, restrito aos arquivos preparados |
| CI | Em pull request / push | O portão rígido que bloqueia a não conformidade |
Como a verificação é determinística e roda de forma idêntica em todo lugar, um commit local que passa e uma execução de CI que passa significam a mesma coisa — não há a lacuna do “funciona na minha máquina” na governança.
Regras vs. revisão por IA
Seção intitulada “Regras vs. revisão por IA”As regras lidam com o que uma máquina consegue verificar mecanicamente — cerca de 70–80% de uma base típica de ADR. O restante subjetivo (adequação arquitetural, julgamentos) é tratado pela skill reviewer, que aplica revisão por IA contra os mesmos ADRs. O objetivo estratégico é continuar movendo regras da coluna de revisão por IA para a coluna de regras determinísticas ao longo do tempo, o que o movimento de aprendizado do loop impulsiona. As verificações gratuitas sobem, o gasto de tokens cai.