Plugin do Claude Code

O plugin Archgate para o Claude Code é a integração de editor mais completa. Ele entrega cinco skills e dois subagentes, e os conecta em um ciclo de governança estruturado: o agente lê os ADRs que se aplicam aos arquivos que está prestes a tocar, escreve código respeitando essas restrições, valida com verificações automatizadas e uma rodada de revisão focada e, por fim, captura quaisquer novos padrões de volta nos seus ADRs.

Esta é a integração com que a maioria dos times começa. Se você está avaliando o Archgate entre editores, consulte a visão geral do ecossistema de plugins para a matriz de recursos.

Acesso beta necessário

O plugin do Claude Code está em beta fechado. Execute archgate login para se cadastrar e autenticar. O plugin é distribuído a partir de plugins.archgate.dev e requer um token por usuário, que a CLI gerencia para você. A CLI em si é gratuita.

O que o plugin oferece

O plugin (archgate@archgate, versão 0.7.0) registra uma entrada de marketplace no Claude Code e instala dois subagentes e cinco skills.

Agentes

Agente	Modo	Propósito
archgate:developer	Edições (acceptEdits)	Agente de desenvolvimento geral. Lê os ADRs aplicáveis antes de codar, valida depois e captura aprendizados. Orquestra as skills abaixo automaticamente.
archgate:planner	Somente leitura	Projeta abordagens de implementação em conformidade com ADRs sem escrever ou modificar qualquer arquivo. Útil para dimensionar o trabalho antes de passá-lo ao agente developer.

O agente archgate:developer é definido como o agente padrão — o plugin entrega um settings.json com { "agent": "archgate:developer" }. Ele carrega memory: project, então o contexto de governança persiste entre sessões no projeto.

Skills

Skill	Quando o agente a utiliza
archgate:reviewer	Após uma mudança de código — valida todas as mudanças contra os ADRs do projeto usando subagentes focados por domínio.
archgate:lessons-learned	Após codar e validar — captura padrões recorrentes e os codifica em ADRs.
archgate:adr-author	Ao criar ou editar um ADR — segue a estrutura e as convenções de ADR estabelecidas no projeto.
archgate:onboard	Uma vez por projeto — executa archgate init, explora o codebase, entrevista você e escreve os ADRs iniciais.
archgate:cli-reference	Interno: carrega sob demanda as referências autoritativas de comandos da CLI, autoria de regras e formato de ADR.

Você raramente invoca skills manualmente. O agente developer chama reviewer e lessons-learned como parte de seu fluxo de trabalho, e carrega cli-reference sempre que precisa de sintaxe exata de comando ou regra que possa ser mais recente que seus dados de treinamento.

Instalação

1. Faça login com o GitHub.

   Autentique-se para obter seu token de plugin. Isso inicia um GitHub Device Flow — a CLI imprime um código único e uma URL; abra a URL, insira o código e autorize.

   archgate login

   As credenciais são armazenadas com segurança no gerenciador de credenciais do seu SO via git credential approve, de modo que o token persiste para atualizações de plugin em segundo plano.

2. Inicialize seu projeto.

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

   archgate init

   Para solicitar a instalação do plugin explicitamente:

   archgate init --install-plugin

   Isso grava o .claude/settings.local.json com o agente archgate:developer e as permissões de skill pré-configuradas, e configura o diretório .archgate/.

3. Deixe a CLI registrar o marketplace.

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

   claude plugin marketplace add   # registers the Archgate marketplace (plugins.archgate.dev)
   claude plugin install archgate@archgate

   Se a CLI claude não for encontrada, o archgate init imprime esses comandos para você executar manualmente.

Instalando em um projeto existente

Se o projeto já estiver inicializado, instale ou reinstale o plugin sem reexecutar archgate init:

archgate plugin install

Para obter a URL autenticada do marketplace para configuração manual:

archgate plugin url

Dica

O Archgate não é instalado via npm, bun, pip ou qualquer gerenciador de pacotes. Se archgate --version falhar, instale o binário standalone primeiro — consulte cli.archgate.dev/getting-started/installation.

Configuração inicial: onboard

Após a instalação, execute a skill archgate:onboard uma vez por projeto. Peça ao agente para fazer o onboarding do projeto, e a skill irá:

1. Explorar a estrutura do seu codebase — diretórios, arquivos-chave, configuração de pacotes.
2. Entrevistar você sobre as convenções, restrições e decisões arquiteturais do seu time.
3. Criar um conjunto inicial de ADRs a partir das suas respostas.
4. Configurar o diretório .archgate/ com suas primeiras regras.

O onboarding é executado uma vez. Depois disso, as outras skills cuidam do desenvolvimento do dia a dia. Consulte Escrevendo ADRs para o formato de ADR que a skill onboard segue.

Como skills e agentes conduzem o ciclo

Para cada tarefa de código, o agente developer segue um fluxo de trabalho de cinco fases. As fases mapeiam diretamente no ciclo de governança — prevenção, detecção e aprendizado.

1. Entender — ler os ADRs.

   O agente executa archgate review-context para obter briefings condensados (as seções Decision e Do’s and Don’ts) de cada ADR que se aplica aos arquivos alterados, agrupados por domínio. Ele não escreve código até ter lido os ADRs aplicáveis.

2. Planejar — projetar uma abordagem em conformidade.

   O agente projeta uma implementação que satisfaz todos os ADRs aplicáveis. Se uma restrição conflitar com a tarefa, ele sinaliza o conflito em vez de violar silenciosamente o ADR.

3. Escrever — implementar respeitando as restrições.

   O agente escreve código referenciando os Do’s and Don’ts que leu na fase 1.

4. Validar — verificações e, em seguida, a skill reviewer.

   O agente primeiro descobre e executa a validação do próprio projeto (verificações de CI, linters, type checkers, testes) e, em seguida, executa archgate check para validação automatizada e rápida de regras. Para a conclusão inicial de uma tarefa, ele invoca a skill archgate:reviewer, que lança um subagente focado por domínio afetado para verificar a conformidade estrutural contra o conjunto completo de ADRs. Violações de ADR são bloqueadores absolutos; avisos são exibidos para você, mas não bloqueiam.

5. Capturar — a skill lessons-learned.

   Após a validação passar, o agente invoca archgate:lessons-learned para revisar a cobertura de regras, identificar padrões que valem a pena codificar e propor novos ADRs ou atualizações aos existentes — para que a mesma decisão se propague para toda sessão futura.

Quando o ciclo completo é executado

O agente executa archgate check após cada mudança de código porque é rápido. Ele reserva as skills reviewer e lessons-learned para conclusões iniciais de tarefas e mudanças substanciais — pequenos ajustes de acompanhamento (uma renomeação, uma mudança de valor) recebem apenas a verificação rápida. Isso mantém o ciclo minucioso onde importa, sem processar demais edições triviais.

Recusa orientada por ADR

Quando uma tarefa exigiria violar um ADR, o agente developer recusa, nomeia o ADR que seria violado e sugere uma alternativa em conformidade — de forma consistente, independentemente de como a solicitação for formulada. Os ADRs são tratados como restrições obrigatórias, não sugestões. Se você insistir em contorná-lo, ele recusa novamente.

Por exemplo, ao ser solicitado a adicionar um cache Redis para sessões em um projeto onde um ADR exige um armazenamento de sessões respaldado por banco de dados, o agente recusa, cita o ADR e, em vez disso, propõe um cache read-through sobre o armazenamento existente.

Planejamento somente leitura com o agente planner

Quando você quer um plano antes de escrever qualquer código, mude para o agente archgate:planner. Ele lê os ADRs relevantes, analisa o codebase e produz um plano estruturado — resumo de conformidade com ADRs, abordagem em nível de arquivo, dependências, áreas de risco, lacunas de governança e uma estratégia de verificação — sem escrever ou editar um único arquivo. Entregue o plano resultante ao agente developer para executar.

Como o plugin lê os ADRs

O plugin executa a CLI do Archgate diretamente — nada é enviado a um serviço externo. Os comandos dos quais ele depende:

• archgate review-context — briefings condensados e agrupados por domínio para todos os ADRs aplicáveis aos arquivos alterados.
• archgate check — 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 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 do seu diretório .archgate/adrs/. Para flags exatas, formatos de saída e a API de autoria de regras, consulte a referência autoritativa em cli.archgate.dev — o próprio plugin carrega essas informações via skill cli-reference em vez de adivinhar.

Quando usar cada agente ou skill

Cenário	Use
Configurar o Archgate em um projeto novo	archgate:onboard
Planejar uma abordagem antes de codar	archgate:planner
Tarefas de código do dia a dia	archgate:developer
Revisar mudanças para conformidade com ADRs	archgate:reviewer
Capturar um padrão recorrente como um ADR	archgate:lessons-learned
Criar ou editar um ADR manualmente	archgate:adr-author

Na maior parte do tempo você interage apenas com o agente developer — ele orquestra reviewer e lessons-learned automaticamente.

Próximos passos

Plugin do Cursor As mesmas skills e agentes, adaptados para o Cursor.

Ciclo de governança O ciclo de prevenção–detecção–aprendizado que o plugin automatiza.

Referência da CLI Comandos autoritativos, API de regras e formato de ADR.