Plugin para Claude Code

O plugin Archgate para Claude Code oferece aos agentes de IA que trabalham no Claude Code um fluxo de governança estruturado. Em vez de depender de instruções em prompts que se deterioram com o tempo, os agentes leem seus ADRs diretamente via comandos do CLI Archgate e validam o próprio código contra suas regras.

O que o plugin oferece

O plugin adiciona um agente e skills baseadas em papéis ao Claude Code. O agente orquestra o fluxo de governança, invocando skills conforme necessário — ler as decisões antes de codificar, validar depois e capturar novos padrões para a equipe.

Agente

Agente	Propósito
archgate:developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois

O agente archgate:developer é definido como agente padrão via .claude/settings.local.json. Ele orquestra as skills abaixo automaticamente como parte do seu fluxo.

Skills

Skill	Propósito
archgate:architect	Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural
archgate:quality-manager	Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem
archgate:adr-author	Cria e edita ADRs seguindo as convenções do projeto
archgate:onboard	Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais

Instalação

Acesso beta necessário

O plugin para Claude Code está atualmente em beta. Cadastre-se em plugins.archgate.dev para obter acesso antes de seguir os passos abaixo.

1. Faça login com o GitHub

Autentique-se com sua conta do GitHub para obter um token do plugin:

archgate login

Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL — abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas em ~/.archgate/credentials.

2. Inicialize seu projeto com o plugin

Execute archgate init no seu projeto. Se você já estiver logado, o plugin é instalado automaticamente:

archgate init

Para solicitar explicitamente a instalação do plugin:

archgate init --install-plugin

Isso cria .claude/settings.local.json com o agente archgate:developer e as permissões de skills pré-configuradas.

Se o CLI claude estiver no seu PATH, o plugin é instalado automaticamente via:

1. claude plugin marketplace add (registra o marketplace do Archgate)
2. claude plugin install archgate@archgate (instala o plugin)

Se o CLI claude não for encontrado, o comando exibe os comandos manuais para você executar.

Instalando o plugin em um projeto existente

Se seu projeto já foi inicializado, você pode instalar ou reinstalar o plugin sem executar archgate init novamente:

archgate plugin install

Para obter a URL autenticada do repositório para configuração manual:

archgate plugin url

Configuração inicial com onboard

Após a instalação, execute a skill archgate:onboard no seu projeto uma vez. Essa skill:

1. Explora a estrutura do seu codebase (diretórios, arquivos-chave, configuração de pacotes)
2. Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe
3. Cria um conjunto inicial de ADRs com base nas suas respostas
4. Configura o diretório .archgate/ com suas primeiras regras

A skill de onboard foi projetada para ser executada uma vez por projeto. Após o onboarding, as outras skills cuidam do desenvolvimento no dia a dia.

Como funciona na prática

O plugin segue um fluxo estruturado para cada tarefa de codificação:

1. Ler os ADRs aplicáveis

Quando o desenvolvedor atribui uma tarefa de codificação, o agente executa archgate review-context para ler todos os ADRs que se aplicam aos arquivos sendo alterados. Isso fornece um resumo condensado com as seções Decision e Do’s and Don’ts de cada ADR relevante.

O agente não escreve código até ter lido os ADRs aplicáveis. Isso é garantido pelo agente archgate:developer.

2. Escrever código seguindo as restrições dos ADRs

O agente escreve código que cumpre as restrições dos ADRs. As seções Do’s and Don’ts servem como guardrails concretos — o agente as consulta enquanto codifica.

3. Validar as alterações

Após escrever o código, o agente executa archgate check para rodar as regras automatizadas contra as alterações. Qualquer violação é corrigida antes de prosseguir.

4. Revisão do arquiteto

O agente invoca archgate:architect para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam. A skill de arquiteto revisa o contexto completo das alterações contra todos os ADRs aplicáveis.

5. Capturar aprendizados

O agente invoca archgate:quality-manager para revisar o trabalho e identificar padrões que valem ser capturados. O quality manager pode propor novos ADRs ou atualizações em existentes quando convenções recorrentes surgem.

Recusa orientada por ADRs

Quando o agente encontra uma tarefa que exigiria violar um ADR, ele recusa e explica qual ADR seria violado. Em seguida, sugere como alcançar o mesmo objetivo mantendo a conformidade.

Por exemplo, se um desenvolvedor pedir ao agente para adicionar chalk como dependência em um projeto governado pelo ARCH-006 (política de dependências), o agente irá:

1. Recusar, citando o ARCH-006 e a lista de dependências aprovadas
2. Sugerir o uso de styleText() do node:util como alternativa
3. Oferecer-se para implementar a tarefa usando a alternativa em conformidade

Esse comportamento é consistente independentemente de como o desenvolvedor formula a solicitação. ADRs são tratados como restrições obrigatórias, não sugestões.

Como o plugin acessa os ADRs

O plugin usa comandos do CLI Archgate diretamente para ler ADRs e executar verificações de conformidade. Os comandos principais são:

• archgate review-context — resumos condensados de todos os ADRs aplicáveis a arquivos alterados, agrupados por domínio
• archgate check --staged — verificação automatizada de regras com relatório de violações
• archgate adr show <id> — texto completo de um ADR específico
• archgate adr list — inventário de todos os ADRs do projeto com metadados
• archgate session-context claude-code — lê transcrições de sessão para recuperação de contexto

Todos os comandos rodam localmente e leem diretamente do seu diretório .archgate/adrs/. Nenhum dado sai da sua máquina.

Quando usar cada agente ou skill

Cenário	Agente ou skill
Iniciando um novo projeto com Archgate	archgate:onboard
Tarefas de codificação do dia a dia	archgate:developer
Revisando um PR para conformidade com ADRs	archgate:architect
Percebendo um padrão recorrente que vale ser codificado	archgate:quality-manager
Criando ou editando um ADR	archgate:adr-author

O agente archgate:developer orquestra as skills automaticamente — ele invoca archgate:architect e archgate:quality-manager como parte do seu fluxo. Na maioria das vezes, você só precisa interagir diretamente com o agente developer.