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.