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 um agente e skills baseadas em papéis ao Claude Code. O agente 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.

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. Execute archgate login para se cadastrar e autenticar.

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 de forma segura no gerenciador de credenciais do sistema operacional via git credential approve.

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.