Plugin para VS Code

Name: Archgate CLI
Author: Archgate

O plugin Archgate para VS Code oferece aos agentes de IA que trabalham no VS Code guardrails integrados. Os agentes leem seus ADRs antes de escrever código, validam depois e capturam novos padrões para a equipe — o mesmo fluxo disponível no plugin para Claude Code.

Como funciona

O VS Code suporta plugins de agente instalados a partir de marketplaces baseados em git. O plugin Archgate é servido a partir de um repositório git em plugins.archgate.dev/archgate/vscode.git. Quando você adiciona esse marketplace às suas configurações de usuário do VS Code, o VS Code descobre e instala o plugin automaticamente.

O plugin é servido no formato nativo .github/plugin/ do VS Code Copilot, separado do formato .claude-plugin/ do Claude Code.

Instalação

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 com a flag --editor vscode:

archgate init --editor vscode

Se você já estiver logado, este comando:

Cria o diretório .archgate/ com ADRs e regras de lint
Adiciona a URL autenticada do marketplace nas suas configurações de usuário do VS Code
Baixa e instala a extensão Archgate para VS Code (.vsix) se o CLI code estiver disponível

A configuração chat.plugins.marketplaces tem escopo de aplicação no VS Code, então não pode ser definida por workspace. O CLI escreve automaticamente no seu settings.json de nível de usuário:

Plataforma	Caminho das configurações de usuário
Windows	`%APPDATA%\Code\User\settings.json`
macOS	`~/Library/Application Support/Code/User/settings.json`
Linux	`~/.config/Code/User/settings.json`

Para solicitar explicitamente a instalação do plugin:

archgate init --editor vscode --install-plugin

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

archgate plugin install --editor vscode

Arquivos gerados

O comando cria ou atualiza o seguinte:

Arquivo	Escopo	Propósito
`settings.json` do usuário	Usuário	`chat.plugins.marketplaces` com a URL autenticada
Extensão Archgate	Aplicação	Extensão VS Code instalada via `.vsix`

O arquivo de configurações de usuário é mesclado de forma aditiva — configurações existentes nunca são sobrescritas. Os marketplaces padrão do VS Code (github/copilot-plugins, github/awesome-copilot) são preservados quando a chave é definida pela primeira vez.

A extensão do VS Code é baixada do serviço de plugins do Archgate e instalada via code --install-extension. Se o CLI code não estiver disponível, instruções de instalação manual são exibidas.

A configuração do marketplace no nível de usuário (adicionada ao seu settings.json):

{
  "chat.plugins.marketplaces": [
    "https://<github-user>:<token>@plugins.archgate.dev/archgate/vscode.git"
  ]
}

Configuração manual

Se preferir não deixar o CLI modificar suas configurações, você pode configurar manualmente:

URL do marketplace: Abra o JSON de configurações de usuário do VS Code (Ctrl+Shift+P → “Preferences: Open User Settings (JSON)”) e adicione a entrada chat.plugins.marketplaces mostrada acima. Você pode encontrar sua URL autenticada executando archgate plugin url vscode.

Extensão: Baixe e instale o arquivo .vsix diretamente:

curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
code --install-extension archgate.vsix
rm archgate.vsix

Substitua <token> pelo seu token archgate (obtenha-o via archgate plugin url vscode).

O que o plugin oferece

O plugin adiciona um agente e skills baseadas em papéis ao VS Code. O agente orquestra o fluxo de guardrails, invocando skills conforme necessário.

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 as configurações do plugin. 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

Configuração inicial com onboard

Após a instalação, execute a skill archgate:onboard no seu projeto uma vez. Essa skill:

Explora a estrutura do seu codebase (diretórios, arquivos-chave, configuração de pacotes)
Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe
Cria um conjunto inicial de ADRs com base nas suas respostas
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.

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.

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.

5. Capturar aprendizados

O agente invoca archgate:quality-manager para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs.

Dicas

Cada desenvolvedor executa archgate init --editor vscode após archgate login para configurar a URL do marketplace no nível de usuário.
Execute o onboard uma vez por projeto para gerar seus ADRs iniciais a partir do seu codebase real.
Mantenha os arquivos de regras dos ADRs atualizados — o agente aplica o que as regras verificam.