Claude Code no VS Code: como usar a extensão

Como mencionei na seção de recursos, o modo plano funciona bem para mudanças maiores. Um detalhe que deixei de lado lá: o Claude também roda comandos de exploração primeiro e salva o plano completo em um arquivo. Adicione seus comentários antes de qualquer escrita. Eu acho o plano escrito útil mesmo quando acabo mudando boa parte dele.

Para dar contexto direcionado, use menções com @ e intervalo de linhas: @app.ts#5-10 foca o Claude em uma região específica. Segurar Shift ao arrastar arquivos para a caixa de prompt os adiciona como anexos. Option+K no Mac (ou Alt+K no Windows e Linux) insere uma menção com @ do seu arquivo e seleção atuais diretamente.

Atalhos do VS Code que valem a pena conhecer

Esses atalhos vêm da documentação da extensão do VS Code da Anthropic e cobrem os que eu mais uso no painel.

A troca de modo de permissão ainda vive no CLI: pressione Shift+Tab no terminal integrado para alternar entre os modos padrão, plano e accept-edits. Para a lista completa de comandos com barra, veja nosso guia de comandos com barra do Claude Code.

Checkpoints rastreiam as edições de arquivos do Claude durante a sessão. Passe o mouse sobre qualquer mensagem da conversa para revelar o botão de voltar. As opções são: ramificar a conversa mantendo as mudanças no código, voltar o código mantendo o histórico da conversa, ou ambos. Os checkpoints persistem por 30 dias. Eles não rastreiam comandos bash: rm, mv e cp ficam fora do sistema de checkpoints. O Git continua sendo a rede de segurança certa para qualquer coisa destrutiva.

Claude Code no VS Code para depuração e refatoração

Ambos os fluxos seguem os mesmos passos: dar contexto ao Claude, revisar a mudança proposta, verificar o resultado. A parte difícil em cada um é juntar o contexto certo.

Depuração

Compartilhe o erro colando-o diretamente, referenciando a saída do terminal com @terminal:name ou deixando o Claude puxar do painel Problems via mcp__ide__getDiagnostics. O Claude rastreia a causa raiz, propõe uma correção em diff e você roda seus testes para verificar.

O Claude Code não integra com o depurador nativo do VS Code: sem breakpoints, sem step-through, sem variáveis ao vivo. Colar erros e usar diagnósticos resolve a maioria dos casos. Se você precisar especificamente do depurador, há um servidor MCP da comunidade (claude-debugs-for-you no GitHub) que faz a ponte, mas requer configuração própria.

Para depuração web ao vivo, @browser conecta o Claude ao Chrome via a extensão Claude no Chrome (versão 1.0.36 ou superior). Um prompt como @browser go to localhost:3000 and check the console for errors permite ao Claude inspecionar o estado do navegador ao vivo sem você alternar de janela.

Refatoração

O Claude lida bem com mudanças coordenadas entre arquivos: renomear uma função em um codebase grande, migrar de uma biblioteca para outra. A etapa de revisão de diff é o que evita decisões impensadas.

O arquivo CLAUDE.md importa aqui mais do que em qualquer outra parte do artigo. Sem carregar convenções específicas do projeto, o Claude adota os padrões que infere do codebase, que podem não bater com o que você realmente quer. Como mencionei na configuração, /init te dá um arquivo inicial; refiná-lo antes de uma sessão grande de refatoração vale os dez minutos.

A compactação de contexto é o limite prático em sessões longas. Quando a janela de contexto enche, o Claude compacta automaticamente resumindo conversas antigas. Depois disso, ele pode perder decisões tomadas antes. Rodar /compact manualmente antes de iniciar uma nova fase dá resultados mais previsíveis do que esperar a compactação automática entrar no meio da tarefa.

Claude Code no VS Code vs. fluxo no terminal

A documentação da Anthropic chama a extensão do VS Code de "a forma recomendada de usar o Claude Code no VS Code". A extensão adiciona coisas que o terminal não tem: o visualizador de diffs lado a lado, a revisão de plano em um documento markdown que você pode editar, várias conversas em abas separadas e @browser para depuração web ao vivo.

O terminal vence em capacidade. O atalho de bash !, o autocomplete por tab, o conjunto completo de comandos com barra e fluxos baseados em pipe como tail -200 app.log | claude -p "..." são exclusivos do CLI. A configuração de servidores MCP também é só no terminal. Pela extensão, você pode gerenciar servidores existentes com /mcp, mas não adicionar novos.

As duas coisas não se excluem. Rodar claude no terminal integrado do VS Code ainda garante a integração com a IDE: visualização de diffs, compartilhamento de contexto de seleção e compartilhamento de diagnósticos funcionam a partir dali. Sessões iniciadas na extensão podem ser continuadas no terminal com claude --resume. Execute claude --ide no terminal integrado quando quiser forçar o CLI a se conectar ao visualizador de diffs e à ponte de diagnósticos do VS Code.

A maioria dos devs usa ambos: VS Code para trabalho multiarquivo e revisão cuidadosa, terminal para tarefas rápidas e automação. Alguns ficam só no terminal, e honestamente funciona bem também. Se você prefere o Cursor ao VS Code, nosso guia Claude Code no Cursor cobre o mesmo fluxo da extensão lá. Nosso fluxo completo via CLI vale a pena conhecer de qualquer forma.

Claude Code no VS Code vs. GitHub Copilot

Como falei no começo, "Claude no VS Code" pode significar a extensão nativa, o Claude acessado pelo GitHub Copilot pelo seletor de modelos, ou o CLI no terminal integrado. A extensão nativa e o Copilot compartilham um modelo, mas não um produto, e funcionam de forma bem diferente.

Pelo Copilot, o modelo Claude roda dentro do paradigma de chat e autocompletar do GitHub: sem sandbox local do SO, sem integrações MCP personalizadas, sem comandos nativos de terminal. Pela extensão Claude Code, o mesmo modelo roda com até 1M de tokens de contexto, executa tarefas entre arquivos e tem acesso a checkpoints, modo plano e servidores MCP.

As ferramentas foram feitas para trabalhos diferentes. O Copilot oferece autocompletar inline como recurso central. O Claude Code não faz autocomplete. O modo agente do Copilot evoluiu bastante, mas em benchmarks da comunidade tende a ficar atrás em tarefas que abrangem muitos arquivos. Nenhum é inerentemente melhor.

Extensão nativa e Copilot: mesmo modelo, experiência diferente. Imagem do autor.

Sobre preços: o Copilot Pro custa US$ 10/mês com 300 solicitações premium. O Claude Code Pro custa US$ 20/mês. Um padrão comum entre devs que usam ambos é US$ 10 para o Copilot (autocomplete enquanto digita) e US$ 20 para o Claude Code (tarefas deliberadas e em maior escala). Os dois produtos cobrem partes diferentes do fluxo de trabalho sem muita sobreposição. A Anthropic também se uniu ao GitHub para colocar modelos Claude dentro do Copilot, que cuida do lado de autocomplete.

Considerações de segurança e privacidade

A Anthropic não usa seu código para treinar os modelos Claude. Usuários Free, Pro e Max podem optar por desativar o registro de dados nas configurações da conta; planos Team, Enterprise e API ficam excluídos por padrão. Para detalhes sobre modos de permissão, servidores MCP e sandbox além da superfície do VS Code, veja nosso guia de segurança do Claude Code.

Um conjunto fixo de caminhos é sempre protegido, independentemente do modo: .git, .vscode, .idea, .husky e .claude (com exceções para seus próprios subdiretórios de trabalho), além de .gitconfig, .gitmodules e vários arquivos de configuração de shell e ferramentas. Isso importa mais no modo de aceitação automática, que grava sem pausar e pode tocar settings.json e tasks.json. Confira os diffs no git antes de commitar.

O sandbox isola comandos bash ao seu diretório de trabalho e bloqueia acesso de rede não autorizado. Ele vem desativado por padrão; ative com /sandbox.

O modo automático substitui a aprovação por ação por um classificador que revisa as ações antes de rodarem, bloqueando coisas como deleção em massa de arquivos, envio de dados para endpoints não autorizados e force push para o main. A Anthropic o descreve como uma alternativa mais segura ao --dangerously-skip-permissions.

Transcrições locais ficam em texto puro em ~/.claude/projects/ por 30 dias (cleanupPeriodDays ajusta isso). Ambientes Enterprise no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry seguem os termos de dados desses provedores. O modo automático não está disponível nesses provedores; ele requer a API da Anthropic diretamente.

Solução de problemas comuns da extensão do VS Code

A maioria dos problemas de configuração cai em uma lista curta. Eu já passei por todos pelo menos uma vez.

• Ícone Spark ausente: Abra um arquivo de projeto, não só uma pasta. Recarregue a janela pela Command Palette (Developer: Reload Window) ou clique na entrada Spark na barra de status (canto inferior direito), que funciona mesmo sem arquivo aberto.

• Conflitos de extensão: Desative temporariamente outras extensões de IA (Cline, Continue, etc.) se o Claude Code não ativar.

• Modo restrito: O Claude Code não roda no Modo Restrito do VS Code. Marque o workspace como confiável.

• Bloqueio de arquivos no Windows: Recolha o painel Explorer e pause depuradores ativos antes de sessões grandes multiarquivo se as gravações falharem no meio da sessão.

• Conflito do macOS Tahoe com Cmd+Esc: O Game Overlay do sistema pode interceptar Cmd+Esc. Reassocie Claude Code: Focus input nos atalhos do VS Code (Cmd+K Cmd+S) se o alternar de foco parar de funcionar.

• Bedrock ou Vertex em vez de login Anthropic: Você pode apontar o Claude Code para endpoints de provedores cloud. Nosso guia de modelos locais e alternativos mostra caminhos sem assinatura.

A Anthropic mantém um guia de troubleshooting dedicado se nada disso resolver seu problema.

Limitações e trade-offs

A extensão é um subconjunto do CLI. Como visto na comparação com o terminal, o autocomplete por tab, o atalho de bash ! e fluxos baseados em pipe são exclusivos do CLI, assim como o modo dontAsk para pipelines de CI.

A visibilidade de tarefas em segundo plano é limitada; para qualquer coisa que você precise vigiar de perto, o terminal integrado é mais transparente.

A aprovação é por arquivo, não por bloco: se o Claude acertou uma função e errou outra no mesmo arquivo, você aceita tudo e reverte manualmente o que não queria.

Os limites de uso são a frustração que mais pega usuários Pro. Os rate limits funcionam em janelas deslizantes, não por mensagem, e se esgotam mais rápido nos horários de pico. Para uso ocasional, o Pro dá conta; para um dia inteiro de trabalho, Max 5x ou Max 20x é mais realista. Eu não confiaria em estimativas da comunidade; a Anthropic não publica contagens exatas e elas mudam.

No Windows, o bloqueio de arquivos entre o Explorer do VS Code e as gravações do Claude causa falhas com mais frequência do que no macOS ou Linux. Recolher o Explorer e pausar depuradores ativos antes de sessões grandes multiarquivo costuma prevenir isso.

Considerações finais

O Claude Code no VS Code é um agente de codificação orientado a tarefas com uma interface focada na revisão. O visualizador de diffs, o modo plano e os checkpoints existem porque importa mais capturar o que o agente realmente mudou do que obter um primeiro rascunho rápido.

O fluxo via terminal não vai desaparecer e, para trabalho scriptado, automatizado ou pesado em CLI, continua sendo a melhor superfície. Mas se você faz um tipo de trabalho em que quer ler cada mudança proposta antes de aplicá-la, o editor é o melhor encaixe.

O Claude Code recebe atualizações semanais, então partes deste artigo vão envelhecer rápido. Nossas melhores práticas para o Claude Code e o guia do Claude Code 2.1 são bons complementos para se manter atualizado. O changelog oficial acompanha os lançamentos. Se algo aqui não bater com o que você vê, confira lá primeiro.

Se você quer prática guiada com modelos Claude e fluxos agentic, eu recomendo nosso curso Introduction to Claude Models.