VS Code

A extensão Archgate para VS Code traz a governança de arquitetura diretamente para o seu editor. Ela faz duas coisas ao mesmo tempo: expõe violações de ADRs como diagnósticos nativos do VS Code no momento em que você salva um arquivo e adiciona skills de governança de IA ao Copilot Chat para que os agentes leiam suas decisões antes de escrever código.

Ela funciona em conjunto com o plugin de agente para VS Code (o agente archgate:developer e as skills instaladas a partir do marketplace da Archgate). A extensão coberta aqui é a superfície de diagnósticos; o plugin de agente é o fluxo de trabalho de IA. O comando archgate init --editor vscode configura ambos.

Referência oficial da CLI

Esta página cobre a instalação e a configuração no VS Code. Para a sintaxe exata de archgate init, archgate login e archgate plugin install, consulte a referência da CLI em cli.archgate.dev.

Requisitos

• CLI Archgate — instale pelo guia de instalação da CLI. A extensão invoca a CLI; ela não a inclui empacotada.
• Um projeto inicializado com archgate init — a extensão é ativada somente quando seu workspace contém um diretório .archgate/.
• Os plugins de agente para VS Code (para as skills do Copilot Chat) exigem VS Code 1.110 (fevereiro de 2026) ou posterior. A parte de diagnósticos da extensão não tem esse requisito mínimo.

O que a extensão oferece

Diagnósticos em tempo real

As violações de ADRs aparecem na aba Problemas enquanto você programa — erros, avisos e informações com a localização precisa de arquivo e linha. Sem execução separada da CLI, sem esperar pela CI.

Verificações com escopo

Apenas os ADRs relevantes ao arquivo salvo são avaliados, então o feedback é rápido e focado. As violações desaparecem automaticamente quando você as corrige.

Skills de governança

O Copilot Chat ganha skills para redigir ADRs, revisar mudanças, fazer o onboarding de um projeto e capturar lições aprendidas.

Comando de verificação manual

Dispare uma verificação completa de conformidade sob demanda pela Paleta de Comandos.

Instalação

A extensão é distribuída como um pacote .vsix através do serviço de plugins da Archgate. O caminho recomendado a instala automaticamente; a instalação manual do .vsix está disponível se você preferir.

Recomendado (CLI)

1. Faça login para obter um token de plugin (a extensão está em beta fechado):

   archgate login

2. Inicialize seu projeto com o alvo de editor VS Code:

   archgate init --editor vscode

   Quando você está autenticado e a CLI code está no seu PATH, isso cria o diretório .archgate/, registra o marketplace autenticado da Archgate nas configurações de usuário do VS Code e baixa e instala a extensão .vsix.

3. Abra seu projeto no VS Code. A extensão é ativada pelo diretório .archgate/ e começa a executar verificações ao salvar.

Consulte o guia da CLI para as flags exatas (--install-plugin) e os caminhos das configurações de usuário em cada plataforma.

Instalação manual do .vsix

Se você prefere não deixar a CLI modificar suas configurações de usuário, instale o .vsix diretamente. Obtenha sua URL de download autenticada e o token com archgate plugin url vscode e depois:

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

Você também pode instalar um .vsix baixado pela interface do VS Code: abra a visão Extensões, clique no menu ..., escolha Install from VSIX… e selecione o arquivo.

Dica

A sintaxe completa de archgate plugin url e a configuração manual do marketplace estão na referência da CLI.

Como os diagnósticos funcionam

A extensão é uma camada fina sobre a CLI Archgate. O fluxo a cada salvamento é:

1. A extensão é ativada quando o workspace contém um diretório .archgate/.
2. Ao salvar um arquivo, ela executa archgate check --json com escopo no arquivo salvo.
3. A CLI avalia as regras de ADR (arquivos .rules.ts) que se aplicam àquele arquivo.
4. As violações são mapeadas para diagnósticos do VS Code com localizações e severidades precisas, exibidas na aba Problemas e em linha no editor.

Como as verificações têm escopo no arquivo salvo, apenas os ADRs cujos globs de files correspondem são avaliados — você recebe feedback direcionado em vez de uma varredura de todo o projeto a cada tecla. Os diagnósticos desaparecem assim que a violação subjacente é corrigida e o arquivo é salvo novamente.

Para uma passagem por todo o projeto, execute o comando Archgate: Check ADR Compliance pela Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P).

Configuração

A extensão lê estas configurações (defina-as por workspace em .vscode/settings.json ou globalmente nas suas configurações de usuário):

Configuração	Padrão	Descrição
archgate.runOnSave	true	Executa uma verificação de conformidade com ADRs quando um arquivo é salvo.
archgate.debounceMs	1000	Atraso de debounce, em milissegundos, para as verificações ao salvar.
archgate.cliPath	"archgate"	Caminho para o executável da CLI archgate. Substitua se a CLI não estiver no seu PATH.
archgate.timeoutMs	60000	Tempo limite, em milissegundos, para os comandos de verificação.

A extensão não inclui a CLI

Os diagnósticos dependem de a CLI archgate ser resolvível. Se as verificações silenciosamente não produzirem diagnósticos, confirme que archgate --version funciona no seu shell e que archgate.cliPath aponta para o binário correto.

Skills de governança no Copilot Chat

O plugin de agente que acompanha adiciona o agente archgate:developer mais as skills de papel à IA do VS Code. O agente orquestra um fluxo de ler-validar-capturar: ele lê os ADRs aplicáveis antes de escrever código, executa archgate check depois, revisa a conformidade estrutural e captura novos padrões. As skills cobrem a redação de ADRs, a revisão de mudanças, o onboarding único de projeto e as lições aprendidas.

Essas correspondem aos mesmos papéis documentados em Skills e Agentes. A configuração do agente e das skills do plugin é descrita por completo no guia do plugin para VS Code da CLI.

Próximos passos

Todos os plugins de editor Compare os seis editores suportados e o que cada um oferece.

Skills As skills de governança que o agente invoca durante o fluxo de trabalho.

CLI: plugin para VS Code Configuração, flags e configuração manual oficiais.