Plugin para Claude Code

O plugin Archgate para Claude Code oferece aos agentes de IA que trabalham no Claude Code guardrails integrados. 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 agentes e skills baseadas em papéis ao Claude Code. O agente developer orquestra o fluxo de guardrails, invocando skills conforme necessário — ler as decisões antes de codificar, validar depois e capturar novos padrões para a equipe.

Agentes

Agente	Propósito
archgate:developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois
archgate:planner	Agente de planejamento para escopar trabalho e dividir tarefas em passos compatíveis com ADRs

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:reviewer	Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural
archgate:lessons-learned	Captura aprendizados 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
archgate:cli-reference	Referência interna para agentes de IA com o guia completo de comandos do CLI Archgate

Instalação

Acesso beta necessário

O plugin para Claude Code está atualmente em beta. Execute archgate login para entrar.

1. Entre na plataforma Archgate

Entre para obter acesso aos plugins:

archgate login

Isso inicia um OAuth 2.0 Device Authorization Grant na plataforma Archgate. O CLI exibe um código único e uma URL — abra a URL no seu navegador, insira o código e autorize. Ao concluir, os tokens resultantes são entregues ao credential helper do git que você configurou via git credential approve; um helper apoiado no sistema operacional os mantém criptografados, enquanto o helper store embutido do git os grava em texto puro.

2. Inicialize seu projeto com o plugin

Execute archgate init com a flag --editor claude. Se você já estiver logado, o plugin é instalado automaticamente:

archgate init --editor claude

Sem --editor, uma execução interativa detecta os editores instalados na sua máquina e permite escolher um ou mais; uma execução não interativa (um agente ou CI) usa Claude Code como padrão.

Para solicitar explicitamente a instalação do plugin:

archgate init --editor claude --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 https://plugins.archgate.dev/archgate.git (registra o marketplace do Archgate)
2. claude plugin install archgate@archgate (instala o plugin)

A URL do marketplace não contém credenciais — o git se autentica em plugins.archgate.dev usando o token que o archgate login entregou ao seu credential helper do git.

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 --editor claude

Sem --editor, uma execução interativa pede para você selecionar os editores e uma execução não interativa usa Claude Code como padrão.

Para imprimir a URL do repositório do plugin para configuração manual:

archgate plugin url --editor claude

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 faz parte do fluxo de trabalho do 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 das alterações

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

5. Capturar aprendizados

O agente invoca archgate:lessons-learned para revisar o trabalho e identificar padrões que valem ser capturados. Essa skill 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 — 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 conteúdo de ADR ou de código-fonte 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
Planejando e escopando trabalho	archgate:planner
Revisando um PR para conformidade com ADRs	archgate:reviewer
Percebendo um padrão recorrente que vale ser codificado	archgate:lessons-learned
Criando ou editando um ADR	archgate:adr-author

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