Integração com Cursor

O Archgate se integra com o Cursor para oferecer aos agentes de IA um fluxo de governança estruturado. 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

Com plugin (beta)

Acesso beta necessário

O plugin para Cursor está atualmente em beta. Cadastre-se em plugins.archgate.dev para obter acesso.

Se você fez login via archgate login, o comando init também baixa e instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pré-configuradas e skills que dão ao agente de IA do Cursor um fluxo de governança completo.

Para instalar o plugin explicitamente:

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

O pacote do plugin é baixado de plugins.archgate.dev e extraído no diretório .cursor/. Ele inclui regras de agente e definições de skills.

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

archgate plugin install --editor cursor

Sem plugin (gratuito)

Sem o plugin, archgate init --editor cursor ainda configura uma regra de governança básica. O agente de IA pode consultar ADRs e executar verificações via comandos CLI, mas não recebe as skills baseadas em papéis descritas abaixo.

Arquivos gerados

Arquivo	Propósito
.cursor/rules/archgate-governance.mdc	Regra sempre ativa do Cursor que instrui o agente a consultar os ADRs

O que o plugin oferece

O plugin adiciona um agente e skills baseadas em papéis ao Cursor. Cada um é invocado como um slash command com o prefixo /ag-. O agente orquestra o fluxo de governança, invocando skills conforme necessário.

Agente

Slash command	Propósito
/ag-developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois

O agente /ag-developer orquestra as skills abaixo automaticamente como parte do seu fluxo.

Skills

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

Esses são o mesmo agente e skills disponíveis no plugin para Claude Code (archgate:developer, archgate:architect, etc.), adaptados para a interface de slash commands do Cursor com o prefixo ag-.

Configuração inicial com onboard

Após instalar o plugin, execute /ag-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

Com o plugin

O agente /ag-developer segue um fluxo estruturado para cada tarefa de codificaçã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. Qualquer violação é corrigida antes de prosseguir.

4. Revisão do arquiteto — O agente invoca /ag-architect para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam.

5. Capturar aprendizados — O agente invoca /ag-quality-manager para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes.

Sem o plugin

O agente usa a regra de governança e comandos CLI para seguir quatro passos manuais:

1. Revisar contexto — Executar archgate review-context para ver quais ADRs se aplicam aos arquivos sendo alterados.

2. Ler ADRs individuais — Para contexto completo sobre uma decisão específica, executar archgate adr show <id> (por exemplo, archgate adr show ARCH-001).

3. Escrever código — Implementar as alterações seguindo as restrições dos ADRs aplicáveis.

4. Executar verificações de conformidade — Executar archgate check --staged para validar que o código está em conformidade com todas as regras dos ADRs.

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	Slash command
Iniciando um novo projeto com Archgate	/ag-onboard
Tarefas de codificação do dia a dia	/ag-developer
Revisando um PR para conformidade com ADRs	/ag-architect
Percebendo um padrão recorrente que vale ser codificado	/ag-quality-manager
Criando ou editando um ADR	/ag-adr-author

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

Regra de governança

A regra de governança em .cursor/rules/archgate-governance.mdc usa alwaysApply: true, o que significa que o agente do Cursor sempre tem o contexto de governança disponível sem ativação manual. Ela instrui o agente a executar archgate review-context antes de codificar e archgate check --staged depois.

Dicas para uso eficaz

• Use /ag-developer para tarefas de codificação. Ele orquestra todo o fluxo de leitura-validação-captura automaticamente.
• Execute /ag-onboard uma vez por projeto. Ele configura seus ADRs iniciais com base no seu codebase e convenções reais.
• Use /ag-architect para revisões de PR. Ele valida a conformidade estrutural além do que as regras automatizadas capturam.
• Use /ag-quality-manager após resolver problemas complexos. Ele captura aprendizados para que os mesmos erros não se repitam.
• Faça commit do diretório .cursor/. Isso garante que cada membro da equipe receba a mesma configuração de governança 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.