Plugin para VS Code

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

Versão do VS Code necessária

Plugins de agente requerem VS Code 1.110 (lançamento de fevereiro de 2026) ou posterior. Versões anteriores não suportam marketplaces de plugins de agente baseados em git. Verifique sua versão com code --version.

Acesso beta necessário

O plugin para VS Code está atualmente em beta. Execute archgate login para entrar antes de seguir os passos abaixo.

1. Entre na plataforma Archgate

Entre para obter acesso aos plugins:

archgate login

Isso inicia um OAuth 2.0 Device Authorization Grant na plataforma Archgate. O CLI exibe um código único e uma URL — abra a URL no seu navegador, insira o código e autorize. Ao concluir, os tokens resultantes são entregues ao credential helper do git que você configurou via git credential approve; um helper apoiado no sistema operacional os mantém criptografados, enquanto o helper store embutido do git os grava em texto puro.

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:

1. Cria o diretório .archgate/ com ADRs e regras de lint
2. Adiciona a URL do marketplace nas suas configurações de usuário do VS Code

O archgate init não baixa a extensão do VS Code. Para instalar a extensão em si, execute archgate plugin install --editor vscode (veja abaixo).

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
WSL	O caminho do lado Windows acima (o VS Code roda no Windows)

3. Instale a extensão

Para instalar ou reinstalar a extensão em um projeto já inicializado:

archgate plugin install --editor vscode

Sem --editor, uma execução interativa detecta os editores instalados na sua máquina e permite escolher; uma execução não interativa (um agente ou CI) usa Claude Code como padrão.

Isso reescreve a URL do marketplace nas suas configurações de usuário e, quando o CLI code está no seu PATH, baixa a extensão Archgate para VS Code a partir do serviço de plugins e a instala via code --install-extension. Se o CLI code não estiver disponível, instruções de instalação manual são exibidas. Se a instalação em si falhar, o .vsix baixado é mantido em ~/.archgate/archgate.vsix para que você possa instalá-lo manualmente.

Arquivos gerados

Os comandos criam ou atualizam o seguinte:

Arquivo	Escopo	Propósito
settings.json do usuário	Usuário	chat.plugins.marketplaces com a URL do marketplace Archgate (init)
Extensão Archgate	Aplicação	Extensão VS Code instalada via .vsix (archgate plugin install)

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 configuração do marketplace no nível de usuário (adicionada ao seu settings.json):

{
  "chat.plugins.marketplaces": [
    "https://plugins.archgate.dev/archgate/vscode.git"
  ]
}

A URL não contém credenciais. O archgate credential é o credential helper; o archgate login o registra para plugins.archgate.dev. O git o consulta a cada requisição e recebe um token de acesso válido, renovado apenas quando o token em cache expira.

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 imprimir a URL executando archgate plugin url --editor vscode.

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

printf 'protocol=https\nhost=plugins.archgate.dev\n\n' |
  archgate credential get |
  sed -n 's|^password=\(.*\)|header = "Authorization: Bearer \1"|p' |
  curl --config - --fail --silent --show-error --output archgate.vsix https://plugins.archgate.dev/api/vscode &&
  code --install-extension archgate.vsix
rm -f archgate.vsix

O archgate credential get emite uma resposta de credencial do git, então a linha password= é convertida em uma diretiva curl --config e enviada por pipe. O token nunca chega à linha de comando, onde ficaria visível na lista de processos e no histórico do shell. O --fail faz o curl sair com erro em um 401, em vez de gravar o corpo do erro por cima de archgate.vsix, e o && impede que o code instale algo que o curl não terminou de baixar; o rm -f final limpa em qualquer caso.

Prefira a configuração de marketplace acima quando possível: assim o git consulta o helper a cada requisição e nenhum token é manipulado à mão.

O que o plugin oferece

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

Agentes

Agente	Propósito
archgate:developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois
archgate:planner	Agente de planejamento para escopar trabalho e dividir tarefas em passos compatíveis com ADRs

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

Configuração inicial com onboard

Após a instalação, execute a skill archgate: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

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 das alterações

O agente invoca archgate:reviewer para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam.

5. Capturar aprendizados

O agente invoca archgate:lessons-learned 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, depois archgate plugin install --editor vscode para instalar a extensão.
• 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.