Integração com Cursor

O Archgate se integra com o Cursor para oferecer aos agentes de IA guardrails integrados. O agente lê seus ADRs antes de escrever código, valida depois e captura novos padrões para a equipe — o mesmo fluxo disponível no plugin para Claude Code.

Configuração

Execute archgate init com a flag --editor cursor para configurar a integração com o Cursor no seu projeto:

archgate init --editor cursor

Acesso beta necessário

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

Se você fez login via archgate login, o comando init também instala o plugin Archgate para o Cursor. O plugin fornece agentes, skills e hooks pré-configurados que dão ao agente de IA do Cursor um fluxo completo de guardrails.

O plugin é distribuído como um tarball autenticado. A CLI faz o download e extrai apenas os diretórios agents/ e skills/ em ~/.cursor/; qualquer outro conteúdo do tarball é descartado. Agentes archgate-* e diretórios de skills obsoletos de uma instalação anterior são removidos primeiro, então edições locais nesses arquivos não sobrevivem a uma reinstalação. Nenhuma detecção de CLI é necessária — os arquivos são gravados diretamente no diretório de usuário do Cursor.

O hook afterFileEdit não vem do tarball. A CLI o grava em ~/.cursor/hooks.json diretamente, preservando quaisquer hooks que você já tenha ali e deixando um arquivo malformado intocado.

Para instalar o plugin explicitamente:

archgate login              # configuração única
archgate init --editor cursor --install-plugin

Para instalar ou reinstalar o plugin em um projeto já inicializado:

archgate plugin install --editor cursor

Arquivos gerados

Escopo de usuário (~/.cursor/):

Arquivo	Propósito
~/.cursor/skills/archgate-reviewer/SKILL.md	Valida alterações de código contra todos os ADRs do projeto
~/.cursor/skills/archgate-lessons-learned/SKILL.md	Captura aprendizados e propõe novos ADRs quando padrões emergem
~/.cursor/skills/archgate-adr-author/SKILL.md	Cria e edita ADRs seguindo as convenções do projeto
~/.cursor/skills/archgate-onboard/SKILL.md	Configuração única: explora o codebase, entrevista você e cria ADRs
~/.cursor/skills/archgate-cli-reference/SKILL.md	Referência interna para agentes de IA com o guia CLI do Archgate
~/.cursor/agents/archgate-developer.md	Agente principal de desenvolvimento com o fluxo completo de guardrails de ADR
~/.cursor/agents/archgate-planner.md	Agente de planejamento para escopo e divisão de trabalho
~/.cursor/hooks.json	Hook afterFileEdit, mesclado em quaisquer hooks que você já tenha

Escopo do projeto:

Arquivo	Propósito
.cursor/hooks.json	Hook afterFileEdit que executa archgate check em cada arquivo editado

O arquivo .cursor/hooks.json é o único arquivo gravado na árvore do seu projeto, e o archgate init só o grava quando ele ainda não existe — um arquivo existente é deixado intacto. Ele garante que archgate check seja executado automaticamente após cada edição de arquivo, detectando violações de ADR em tempo real.

O que o plugin oferece

O plugin adiciona agentes e skills ao Cursor, instalados no escopo de usuário para que estejam disponíveis em todos os seus projetos.

Agentes

Nome	Propósito
archgate-developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois
archgate-planner	Agente de planejamento para escopo de trabalho e divisão de tarefas conforme ADRs

Os usuários invocam agentes explicitamente via /archgate-developer ou /archgate-planner no chat do Cursor.

Skills

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

Esses são os mesmos papéis disponíveis no plugin para Claude Code (archgate:reviewer, archgate:lessons-learned, etc.), adaptados para o sistema de skills e agentes do Cursor.

Hooks

Hook	Gatilho	Ação
afterFileEdit	Cada edição de arquivo	Executa archgate check no arquivo editado para detectar violações de ADR

O hook é definido em .cursor/hooks.json no nível do projeto, então funciona tanto localmente quanto em ambientes de agentes na nuvem. A instalação do plugin adicionalmente registra o mesmo hook no seu ~/.cursor/hooks.json de nível de usuário.

Configuração inicial com onboard

Após instalar o plugin, invoque /archgate-developer e peça para ele executar a skill de onboard no seu projeto. 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

Invoque /archgate-developer no chat do Cursor ao iniciar uma tarefa de codificação. O agente segue um fluxo estruturado para cada alteração:

1. Ler os ADRs aplicáveis — O agente executa archgate review-context para ver quais ADRs se aplicam aos arquivos sendo alterados. Ele não escreve código até ter lido os ADRs aplicáveis.

2. Escrever código seguindo as restrições dos ADRs — O agente implementa as alterações seguindo as seções Do’s and Don’ts dos ADRs aplicáveis.

3. Executar verificações de conformidade — O agente executa archgate check para rodar as regras automatizadas. O hook afterFileEdit também detecta violações em tempo real. Qualquer violação é corrigida antes de prosseguir.

4. Revisar alterações — O agente invoca a skill archgate-reviewer para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam.

5. Capturar aprendizados — O agente invoca a skill archgate-lessons-learned para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes.

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 por um ADR de política de dependências, o agente irá:

1. Recusar, citando o ADR e a lista de dependências aprovadas
2. Sugerir o uso da alternativa aprovada
3. Oferecer-se para implementar a tarefa usando a abordagem 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.

Quando usar cada agente ou skill

Cenário	Agente / Skill
Iniciando um novo projeto com Archgate	/archgate-developer (e peça para fazer o onboard)
Tarefas de codificação do dia a dia	/archgate-developer
Planejamento e escopo de trabalho	/archgate-planner
Revisando uma alteração 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 invocar /archgate-developer e deixá-lo executar.

Suporte a agentes na nuvem

O Cursor suporta agentes na nuvem que executam em VMs remotas. Esses ambientes não têm acesso a ~/.cursor/, então skills e agentes no escopo de usuário não estão disponíveis. No entanto, o arquivo .cursor/hooks.json faz parte da árvore do seu projeto e funciona em VMs na nuvem. Isso significa que archgate check ainda é executado automaticamente após cada edição de arquivo, mesmo em sessões de agentes na nuvem.

Para governança completa em ambientes na nuvem, garanta que archgate esteja disponível no PATH da VM (ex: via o script de instalação no setup do seu projeto).

Acesso à transcrição da sessão

O comando archgate session-context lê transcrições de sessão do agente Cursor do disco. Isso permite que skills acessem o histórico da conversa atual, o que é útil para recuperar contexto que pode ter sido compactado ou truncado.

Quando o Cursor é o editor detectado, não é preciso informar um editor. Use --editor cursor para ler as transcrições do Cursor independentemente do que foi detectado — útil quando outro agente executa dentro do Cursor e vence a detecção. As duas opções relevantes para o Cursor são:

• --max-entries <n> — Número máximo de entradas a retornar (padrão: 200, entradas mais recentes). Deve ser um número inteiro positivo.
• --editor <name> — Lê as transcrições de outro editor em vez do detectado.

(Uma terceira opção, --root, se aplica apenas ao opencode.)

Use archgate session-context list para descobrir sessões anteriores e archgate session-context show <session-id> para ler uma sessão específica.

Dicas para uso eficaz

• Invoque /archgate-developer para tarefas de codificação. Ele orquestra todo o fluxo de leitura-validação-captura automaticamente.
• Execute onboard uma vez por projeto. Ele configura seus ADRs iniciais com base no seu codebase e convenções reais.
• Use archgate-reviewer para revisões. Ele valida a conformidade estrutural além do que as regras automatizadas capturam.
• Use archgate-lessons-learned após resolver problemas complexos. Ele captura aprendizados para que os mesmos erros não se repitam.
• Faça commit do diretório .cursor/. O arquivo hooks.json garante que cada membro da equipe receba archgate check em edições de arquivo ao clonar o repositório.
• Mantenha os arquivos de regras dos ADRs atualizados. O agente aplica o que as regras verificam — se uma regra estiver faltando, a violação não será detectada.
• Execute archgate plugin install --editor cursor para atualizar. O serviço retorna o bundle de plugin mais recente em cada download autenticado.