Início Rápido

Name: Archgate CLI
Author: Archgate

1. Instalar o Archgate

Se você ainda não instalou a CLI, instale-a globalmente via npm:

npm install -g archgate

Veja a página de Instalação para detalhes de plataforma e solução de problemas.

2. Inicializar seu projeto

Navegue até a raiz do seu projeto e execute o comando init:

cd my-project
archgate init

Isso cria o diretório .archgate/ com a seguinte estrutura:

.archgate/
  adrs/
    ARCH-001-example.md          # Example ADR
    ARCH-001-example.rules.ts    # Example rules file
  lint/
    archgate.config.ts           # Archgate configuration

Os arquivos gerados fornecem um exemplo funcional para você construir a partir dele.

3. Editar o ADR de exemplo

Abra .archgate/adrs/ARCH-001-example.md. Todo ADR começa com um frontmatter YAML que define sua identidade:

---
id: ARCH-001
title: Example Decision
domain: architecture
rules: true
files: ["src/**/*.ts"]
---

id — Identificador único. A convenção é ARCH-NNN, mas qualquer string funciona.
title — Nome legível para a decisão.
domain — Agrupa ADRs relacionados (architecture, backend, frontend, data ou general).
rules — Defina como true se este ADR possui um arquivo complementar .rules.ts com verificações automatizadas.
files — Padrões glob opcionais que definem o escopo de quais arquivos as regras se aplicam.

Abaixo do frontmatter, escreva a decisão em markdown. O Archgate não impõe uma estrutura específica de seções, mas as seções recomendadas são: Context, Decision, Do’s and Don’ts, Consequences, Compliance e References.

4. Adicionar um arquivo de regras complementar

Crie um arquivo .rules.ts ao lado do seu ADR com o mesmo prefixo de nome. As regras são escritas em TypeScript usando a função defineRules:

import { defineRules } from "archgate/rules";

export default defineRules({
  "no-console-error": {
    description: "Use logError() instead of console.error()",
    async check(ctx) {
      for (const file of ctx.scopedFiles) {
        const matches = await ctx.grep(file, /console\.error\(/);
        for (const match of matches) {
          ctx.report.violation({
            message: "Use logError() instead of console.error()",
            file: match.file,
            line: match.line,
            fix: "Import logError from your helpers and use it instead",
          });
        }
      }
    },
  },
});

Cada regra possui uma chave única, uma descrição e uma função assíncrona check. Dentro de check, você tem acesso a:

ctx.scopedFiles — Arquivos que correspondem aos padrões glob do campo files do ADR.
ctx.grep(file, pattern) — Pesquisa um arquivo por correspondências de regex, retornando caminhos de arquivos e números de linha.
ctx.report.violation() — Reporta uma violação com mensagem, caminho do arquivo, número da linha e sugestão opcional de correção.

5. Executar verificações

Execute o verificador de conformidade contra sua base de código:

archgate check

O Archgate carrega cada ADR com rules: true, executa seu arquivo de regras complementar e imprime os resultados. O código de saída indica o resultado:

Código de saída	Significado
0	Todas as regras passaram. Nenhuma violação encontrada.
1	Uma ou mais violações detectadas.
2	Erro interno (ex.: ADR ou regra malformada).

Para verificar apenas arquivos staged (útil em pre-commit hooks ou CI):

archgate check --staged

E agora?

Agora que você tem uma configuração funcionando, aprofunde-se:

Entenda os conceitos:

ADRs — O que são Architecture Decision Records e como o Archgate os utiliza.
Regras — Como arquivos complementares .rules.ts transformam decisões em verificações automatizadas.
Domínios — Como domínios agrupam ADRs relacionados e definem o escopo de correspondência de arquivos.

Escreva os seus:

Escrevendo ADRs — Aprenda o formato completo de ADR e as melhores práticas para escrever decisões eficazes.
Escrevendo Regras — Explore a API de regras, padrões avançados e como testar suas regras.
Padrões Comuns de Regras — Padrões prontos para copiar e colar para verificações de dependências, convenções de nomenclatura e mais.

Integre ao seu fluxo de trabalho:

Integração com CI — Conecte archgate check ao GitHub Actions, GitLab CI ou qualquer pipeline.
Pre-commit Hooks — Execute verificações localmente antes de cada commit.
Plugin Claude Code — Dê aos agentes de IA um fluxo completo de governança com habilidades baseadas em papéis.
Integração com Cursor — Use o Archgate com o Cursor IDE para desenvolvimento assistido por IA.