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 — 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.