Pacotes de ADR

Um pacote de ADR é um bundle curado de Architecture Decision Records e suas regras executáveis, projetado para uma stack, domínio ou preocupação específica. Em vez de começar a governança a partir de um arquivo em branco, você importa uma baseline opinativa e passa a capturar problemas reais imediatamente.

Os pacotes são a resposta ao problema do greenfield. O Archgate se destaca em projetos brownfield, onde padrões já existem e o archgate init junto com o @lessons-learned os capturam como ADRs. Um repositório novo não tem padrões a extrair, nem convenções a aplicar, nem ADRs iniciais óbvios. Os pacotes entregam defaults em vez de instruções, da mesma forma que rails new e create-next-app entregam conteúdo inicial opinativo em vez de uma casca vazia.

Onde os pacotes ficam

O registro oficial é o repositório público archgate/awesome-adrs no GitHub. A importação é git-native: não há banco de dados de registro e nada a publicar. Adicionar um pacote significa adicionar um diretório em um caminho.

Uma Primitiva: O Pacote

O registro tem uma única primitiva de conteúdo — o pacote — mais um índice de links da comunidade. Todo ADR vive dentro de um pacote. Não há um balde separado de “ADR avulso”: coleções temáticas como security ou testing são simplesmente pacotes com um escopo mais estreito do que stacks opinativas como typescript-strict. Elas compartilham a mesma estrutura e diferem apenas em escopo e tags.

Pacotes curados

Hospedados em archgate/awesome-adrs, revisados pelos mantenedores do Archgate e marcados com um selo Curated. Veja o catálogo curado.

Links da comunidade

Apontadores para repositórios externos compatíveis com archgate que os mantenedores não escreveram. Veja pacotes da comunidade.

Todo pacote em disco tem o mesmo formato:

packs/typescript-strict/
  archgate-pack.yaml   # pack metadata: name, version, description, tags
  README.md            # overview and ADR listing
  rules.d.ts           # ambient types for .rules.ts (triple-slash reference)
  adrs/
    TS-001-no-any.md           # ADR document
    TS-001-no-any.rules.ts     # co-located rule file
    TS-002-explicit-return-types.md
    TS-002-explicit-return-types.rules.ts

Navegando e Importando

Você pode importar um pacote inteiro ou escolher individualmente ADRs de dentro de um pacote. O caminho que você passa determina a granularidade — aponte para o diretório de um pacote para o pacote inteiro, ou para um arquivo de ADR para uma única decisão e sua regra irmã.

Pacote inteiro

# Imports every ADR in the pack
archgate adr import packs/typescript-strict

Escolher um ADR

# Imports just this ADR and its co-located .rules.ts
archgate adr import packs/security/adrs/SEC-001-no-secrets-in-code

Conjunto composto

# Pull from multiple packs in one command
archgate adr import \
  packs/typescript-strict \
  packs/security/adrs/SEC-001-no-secrets-in-code \
  packs/testing/adrs/TEST-001-colocated-tests

O caminho que você lê no README do registro é exatamente o que você digita na CLI — não há busca por slug nem etapa de tradução. A extensão .md é opcional, e toda forma aceita um sufixo @<ref> para fixar a versão (por exemplo packs/[email protected]).

1. Descubra um pacote no catálogo curado ou, em breve, no builder visual em adrs.archgate.dev.

2. Importe o pacote ou os ADRs escolhidos com archgate adr import. Os arquivos são gravados em .archgate/adrs/ com IDs renomeados para corresponder aos prefixos de domínio do seu projeto e evitar colisões.

3. Execute archgate check e veja as regras importadas capturarem problemas reais no seu código.

Sem seletor interativo na CLI

A CLI aceita caminhos exatos; ela não traz um navegador de terminal. Descoberta, busca, filtragem e composição acontecem no builder web, cuja saída é um comando archgate adr import pronto para executar, que você copia e cola.

Escolha e Componha

A maioria dos times quer um subconjunto de qualquer pacote — os três ADRs de segurança que se aplicam a eles, não todos. Escolher individualmente permite que autores de pacotes escrevam pacotes abrangentes sem penalizar consumidores que só precisam de algumas decisões. O estado final de um time é o seu pacote, montado a partir de múltiplas fontes: alguns ADRs do typescript-strict, um do security, a regra de testes com que se importam e o ADR de acessibilidade privado da empresa.

A importação também funciona contra qualquer repositório acessível por git, não apenas o registro oficial — caminhos de org/repo de terceiros, URLs de navegador coladas do GitHub, remotes SSH e git self-hosted, todos resolvem através da sua autenticação git existente.

Referência da CLI: archgate adr import A sintaxe autoritativa do comando, as regras de resolução, a fixação de ref e o manifesto de importação vivem nos docs da CLI.

Próximos Passos

Pacotes curados Os 14 pacotes revisados pelos mantenedores e seus caminhos de importação.

Pacotes da comunidade Repositórios externos compatíveis com archgate e o futuro builder.

Criando um pacote Crie seu próprio pacote: documentos de ADR pareados com arquivos de regra.

O que é um ADR? Como os ADRs funcionam tanto como documentação quanto como regras executáveis.