Criando um Pacote

Um pacote é um diretório de Architecture Decision Records e suas regras executáveis, descrito por um pequeno arquivo de metadados. Você pode construir um pacote para o repositório privado do seu próprio time, ou submetê-lo ao registro oficial para ganhar um selo Curated. A estrutura é idêntica de qualquer forma.

Anatomia de um Pacote

Todo pacote segue o mesmo layout. A ideia-chave é que cada ADR é um par: um documento Markdown que humanos e agentes de IA leem, e um arquivo .rules.ts colocalizado que máquinas executam.

packs/my-pack/
  archgate-pack.yaml         # pack metadata (required)
  README.md                  # overview and ADR listing (required)
  rules.d.ts                 # ambient types for .rules.ts (required)
  adrs/
    ADR-001-my-decision.md         # ADR document (at least one)
    ADR-001-my-decision.rules.ts   # corresponding rule file

archgate-pack.yaml

Metadados do pacote — name, version, description, maintainers e tags. Isto é autoritativo; o caminho do diretório é apenas um endereço.

Documentos de ADR

Markdown com frontmatter YAML, uma decisão cada. Eles explicam por que uma escolha foi feita e quais trade-offs decorrem dela.

Arquivos de regra

Um .rules.ts colocalizado por ADR que transforma a decisão em uma verificação automatizada que o archgate check pode executar.

rules.d.ts

Definições de tipo ambientes para que seus arquivos de regra tenham type safety completo contra a API de regras.

1. Metadados do Pacote

Crie archgate-pack.yaml na raiz do pacote:

name: my-pack
version: 0.1.0
description: Short description of what this pack covers.
maintainers:
  - github: your-github-username
tags:
  - language:typescript
  - concern:security

As tags usam a convenção <axis>:<value> (language:, runtime:, framework:, tool:, concern:, domain:, stack:). Elas direcionam a filtragem no builder web, de modo que o diretório nunca precisa ser reorganizado quando um pacote abrange duas categorias.

2. Documentos de ADR

Cada ADR é um arquivo Markdown em adrs/ com frontmatter YAML:

---
id: ADR-001
title: My Decision
domain: architecture
rules: true
files: ["**/*.ts"]
---

Após o frontmatter, inclua estas seções, nesta ordem: ## Context, ## Decision, ## Do's and Don'ts e ## Consequences. Defina rules: true quando o ADR vier acompanhado de um arquivo de regra pareado, e use files para delimitar a quais caminhos a regra se aplica.

Referência do schema de ADR O schema completo de frontmatter, os domínios e as convenções de autoria de ADR estão documentados nos docs da CLI.

3. Arquivos de Regra

Pareie cada ADR que carrega regra com um arquivo <adr-id>-<slug>.rules.ts no mesmo diretório adrs/. Todo arquivo de regra deve:

1. Começar com uma referência triple-slash aos tipos ambientes: /// <reference path="../rules.d.ts" />
2. Exportar um objeto default validado com satisfies RuleSet
3. Usar apenas a API RuleContext — glob(), grep(), grepFiles(), readFile(), readJSON() e report.violation() / report.warning() / report.info()
4. Ser async

Aqui está a regra pareada com o ADR SEC-001-no-secrets-in-code no pacote curado security, resumida:

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-secrets-in-code": {
      description:
        "Source files must not contain hardcoded secrets, API keys, or tokens",
      async check(ctx) {
        const sourceGlob = "**/*.{ts,tsx,js,jsx}";
        const matches = await ctx.grepFiles(
          /API_KEY\s*=\s*["'][^"']{8,}["']/u,
          sourceGlob,
        );
        for (const m of matches) {
          if (m.file.includes(".env.example")) continue;
          ctx.report.violation({
            message: "Possible hardcoded API key — do not hardcode secrets.",
            file: m.file,
            line: m.line,
            fix: "Move the secret to an environment variable and read it via `process.env`.",
          });
        }
      },
    },
  },
} satisfies RuleSet;

Reutilize o sandbox de regras

As regras rodam no sandbox de análise estática do Archgate, que já rejeita APIs inseguras. Mantenha as verificações determinísticas e livres de efeitos colaterais — leia o workspace, reporte os achados, retorne.

O arquivo rules.d.ts fornece tipos ambientes para RuleSet, RuleContext, GrepMatch, a API report e PackageJson. Copie-o de qualquer pacote curado para que seu editor e o validador concordem sobre o contrato.

Referência da API de regras Cada método do RuleContext, a API report e os níveis de severidade estão documentados de forma autoritativa nos docs da CLI.

4. README

Escreva um README.md que nomeie o pacote, dê uma descrição de uma linha, liste os ADRs incluídos em uma tabela (ID e título), e mostre o comando de início rápido archgate adr import packs/<name>. É isto que renderiza na página de detalhes do pacote no builder.

Submetendo um Pacote Curado

Para ter seu pacote hospedado no registro com um selo Curated:

1. Faça um fork do archgate/awesome-adrs e crie packs/my-pack/ com os arquivos acima.

2. Valide localmente — todo .rules.ts deve compilar sem erros, e o archgate-pack.yaml e a estrutura de arquivos de regra devem passar na validação de CI.

3. Abra um pull request usando o template de PR de pacote curado. Um mantenedor revisa e aprova.

Depois de mergeado, o pacote é importável por qualquer pessoa com archgate adr import packs/my-pack.

Mantendo o selo

Um selo Curated pode ser revogado se as regras de um pacote quebrarem após mudanças upstream e o mantenedor não responder em 30 dias. Pacotes abandonados por mais de 6 meses podem ser arquivados. Mantenha suas regras verdes.

Pacotes Privados e de Terceiros

Você não precisa submeter ao registro oficial. A mesma estrutura funciona em qualquer repositório git, e os consumidores a importam com a URL git ou a forma <org>/<repo>/<path> — sem etapa de publicação necessária. O conjunto de ADRs do próprio time é apenas um pacote em um caminho do repositório.

Links da comunidade Indexe um pacote externo como um link da comunidade em vez de hospedá-lo.

Catálogo curado Veja pacotes prontos para inspirar a estrutura e o tom do seu.