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

Se você fez login via archgate login, o comando init também 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.

O plugin é distribuído de duas formas:

1. Cursor Team Marketplace — O plugin é publicado em um repositório team marketplace baseado em git. Após a instalação, o Cursor o descobre a partir da URL do team marketplace impressa pela CLI.
2. Extensão VS Code (VSIX) — Uma extensão .vsix é instalada no Cursor via o comando cursor --install-extension.

Para instalar o plugin explicitamente:

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

O comando archgate plugin install --editor cursor instala a extensão VS Code via CLI cursor se disponível e exibe a URL do team marketplace; exibe instruções manuais caso contrário.

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. O sistema de plugins do Cursor gerencia o namespacing, então as skills usam seus nomes diretos sem prefixo.

Agente

Nome	Propósito
developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois

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

Skills

Nome	Propósito
architect	Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural
quality-manager	Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem
adr-author	Cria e edita ADRs seguindo as convenções do projeto
onboard	Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais
cli-reference	Referência interna para agentes de IA com o guia completo de comandos CLI do Archgate

Esses são o mesmo agente e skills disponíveis no plugin para Claude Code (archgate:developer, archgate:architect, etc.), adaptados para o sistema de plugins do Cursor.

Configuração inicial com onboard

Após instalar o plugin, execute a skill 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 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 --staged para rodar as regras automatizadas. Qualquer violação é corrigida antes de prosseguir.

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

5. Capturar aprendizados — O agente invoca a skill 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	Skill
Iniciando um novo projeto com Archgate	onboard
Tarefas de codificação do dia a dia	developer
Revisando um PR para conformidade com ADRs	architect
Percebendo um padrão recorrente que vale ser codificado	quality-manager
Criando ou editando um ADR	adr-author

O agente developer orquestra as skills automaticamente — ele invoca architect e quality-manager como parte do seu fluxo. Na maioria das vezes, você só precisa usar 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 a skill developer para tarefas de codificação. Ela orquestra todo o fluxo de leitura-validação-captura automaticamente.
• Execute onboard uma vez por projeto. Ela configura seus ADRs iniciais com base no seu codebase e convenções reais.
• Use architect para revisões de PR. Ela valida a conformidade estrutural além do que as regras automatizadas capturam.
• Use quality-manager após resolver problemas complexos. Ela 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.