Adotando o Archgate em um Repo Existente

Adotar o Archgate em um projeto existente não significa reescrevê-lo. A governança é aditiva: você versiona um diretório .archgate/ de Architecture Decision Records (ADRs), e a partir daí cada verificação, execução de CI e sessão de IA lê esses ADRs como fonte da verdade. Este guia percorre o caminho de adoção, de um repositório limpo até a governança aplicada.

A sintaxe da CLI referenciada aqui está documentada de forma autoritativa em cli.archgate.dev. Esta página foca na jornada de adoção e em onde cada ferramenta se encaixa.

O caminho de adoção

1. Inicialize o esqueleto de governança com archgate init.

2. Escreva seus primeiros ADRs. Codifique as convenções que sua base de código já segue. A skill onboard automatiza isso explorando o repositório por você.

3. Verifique se os ADRs e regras passam contra seu código atual com archgate check.

4. Aplique continuamente. Conecte as verificações ao CI e aos pre-commit hooks.

5. Evolua. Estenda a governança ao longo do tempo com as skills lessons-learned e adr-author.

Passo 1: Inicializar

Execute archgate init na raiz do repositório. Ele cria o diretório .archgate/ contendo adrs/ (seus ADRs e os arquivos de regras .rules.ts companheiros) e lint/, e detecta seus editores para que possa oferecer a configuração do plugin correspondente.

archgate init

O fluxo de init semeia um ADR de exemplo como placeholder (GEN-001-example.md) para que você veja o formato. Você o substituirá por ADRs reais no próximo passo. Veja o guia de primeiros passos da CLI para cada flag do init e o layout exato de diretórios.

Nota

Versione o diretório .archgate/ no controle de versão. Ele é o contrato compartilhado e revisável da sua equipe. ADRs são documentos legíveis por humanos e regras verificáveis por máquina em um só lugar.

Passo 2: Escrever seus primeiros ADRs

Você tem dois caminhos para o seu conjunto inicial de ADRs. A maioria das equipes que adotam o Archgate em uma base de código madura usa a skill guiada onboard, que descobre as convenções automaticamente em vez de pedir que você escreva tudo à mão.

Guiado (skill onboard)

A skill onboard é o caminho recomendado para um repositório existente. Disponível dentro dos plugins de editor do Archgate (Claude Code, Cursor, VS Code e outros), ela faz o onboarding de um projeto na governança de ponta a ponta:

1. Pré-verificação. Confirma que a CLI do Archgate está instalada.

2. Inicialização. Executa archgate init se .archgate/adrs/ ainda não existir, e remove o ADR de exemplo placeholder.

3. Avaliação de maturidade. Classifica o repositório como greenfield, estágio inicial ou maduro a partir dos arquivos de manifesto, contagem de arquivos-fonte e histórico recente do git.

4. Descoberta. Para repositórios maduros e em estágio inicial, sub-agentes de exploração paralelos leem a configuração do seu toolchain, os padrões do código-fonte (tratamento de erros, imports, nomenclatura) e a documentação para extrair as convenções que você já segue, sem que você precise descrevê-las.

5. Entrevista. Faz no máximo três perguntas direcionadas para preencher lacunas que a exploração não conseguiu (domínios de governança prioritários, áreas legadas ou especificações externas).

6. Proposta de backlog. Apresenta uma lista priorizada de 6 a 8 ADRs nos domínios relevantes (arquitetura, backend, frontend, dados, geral) para sua aprovação antes que qualquer coisa seja escrita.

7. Autoria. Escreve cada ADR aprovado (e os arquivos de regras companheiros onde uma decisão é objetivamente verificável), e então corrige as referências cruzadas entre eles.

8. Relatório. Imprime um resumo de governança: ADRs criados, domínios cobertos, lacunas restantes e próximos passos.

Execute-a uma vez, ao configurar o Archgate pela primeira vez. Depois que o conjunto inicial existir, executá-la novamente estende ou audita sua governança.

Manual (skill adr-author)

Se você prefere escrever os ADRs você mesmo, ou quer capturar uma decisão específica, use a skill adr-author (ou os comandos de ADR da CLI diretamente). Ela segue a mesma estrutura de ADR que a skill onboard produz (Contexto, Decisão, Faça e Não Faça, Consequências, Conformidade e Referências) e pode criar um .rules.ts companheiro para decisões verificáveis em código.

Esse caminho serve a projetos greenfield com poucas convenções existentes, ou à adoção incremental em que você documenta uma área arquitetural por vez.

Documente o que você já faz

O objetivo do primeiro conjunto de ADRs é ratificar as convenções que seu código já segue, não impor novas. Codificar os padrões existentes significa que o archgate check passa já no primeiro dia, e as regras começam a pegar regressões imediatamente, em vez de marcar toda a sua base de código como não conforme.

Passo 3: Verificar contra o código atual

Uma vez que seus ADRs existam, confirme que suas regras automatizadas passam contra o repositório como ele está hoje:

archgate check

Uma execução limpa significa que seus ADRs descrevem com precisão sua base de código. Se uma regra falhar em código existente, você tem uma decisão a tomar: corrigir o código, relaxar a regra ou limitar o ADR para aplicar apenas a arquivos novos. O conjunto completo de flags (--verbose, --json, --adr, --base, --staged) está documentado na referência da CLI.

Passo 4: Aplicar continuamente

A governança só se sustenta se for aplicada. Combine camadas de aplicação para que as violações sejam pegas o mais cedo possível:

Pre-commit hooks Bloqueie commits que violam regras na máquina do desenvolvedor, antes que cheguem ao remoto.

Integração com CI Gateie pull requests com o archgate/check-action, a última linha de defesa que bloqueia merges.

Para trabalho assistido por IA, os plugins de editor fecham o ciclo ainda mais cedo: o agente desenvolvedor lê os ADRs relevantes antes de escrever código e valida a conformidade antes de você commitar, de modo que o gate de CI raramente dispara.

Passo 5: Evoluir a governança ao longo do tempo

A adoção é o começo, não o fim. À medida que sua arquitetura muda:

• Use a skill lessons-learned após uma sessão de desenvolvimento para capturar novos aprendizados e codificá-los em ADRs ou na memória do projeto. Esse é o passo final no fluxo de trabalho de desenvolvimento.
• Use a skill adr-author para documentar uma nova decisão que a passagem de onboarding não cobriu.
• Reexecute a skill onboard para estender a governança a um novo domínio (por exemplo, adicionando ADRs da camada de dados após introduzir um banco de dados).

Você também pode iniciar com convenções comprovadas a partir do registro de ADRs do Archgate em vez de começar de uma página em branco. Importe um pack curado e remapeie seus IDs para o seu projeto.

Relacionados

Visão geral das skills As skills onboard, lessons-learned e adr-author em profundidade.

Visão geral dos plugins Quais editores trazem o fluxo de onboarding.

Importando ADRs Comece a partir de packs curados no registro.