VS Code에서 Claude Code 확장 사용 완전 정리
핵심 요약
Claude Code VS Code 확장은 터미널 없이 IDE 안에서 Claude를 시각적으로 사용할 수 있게 해주는 도구다. 코드 이해, 수정, 디버깅을 돕고, 파일 diff 승인, @-mention, 여러 대화 세션 등 생산성을 높이는 기능을 제공한다. 확장은 CLI와 일부 설정과 히스토리를 공유하며, 필요하면 CLI 모드로도 전환할 수 있다.
VS Code용 Claude Code 확장의 역할 이해하기
Claude Code VS Code 확장은 "터미널 기반 CLI" 위에 얹힌 그래픽 인터페이스라고 보면 이해하기 쉽다.
기본적으로 우측 패널에 채팅 창이 생기고, 그 안에서 Claude에게 질문하고, 수정 제안을 받고, diff를 확인하면서 IDE 안에서 바로 수락·거절할 수 있다.
또한 대화 히스토리를 탭/윈도우 단위로 관리할 수 있어, "작업 단위별 대화"를 분리해 두고 오갈 수 있는 것이 큰 장점이다.
위와 같이 우측에 패널을 띄워 놓고, 코드와 Claude 응답을 동시에 보며 작업하는 것이 기본 사용 패턴이다.
설치와 기본 시작 순서
확장을 쓰기 위해서는 VS Code 1.98.0 이상과 Anthropic 계정(또는 서드파티 제공자 계정)이 필요하다.
VS Code에서 Cmd+Shift+X(Mac) 또는 Ctrl+Shift+X(Win/Linux)를 눌러 Extensions 뷰를 열고 "Claude Code"를 검색해 설치하면 된다.
설치 후에는 VS Code를 재시작하거나 "Developer: Reload Window" 명령으로 새로고침해야 아이콘과 명령들이 제대로 보인다.
처음 Claude 패널을 열면 로그인 창이 나타나며, 여기서 Anthropic 계정으로 로그인하거나, 나중에 설명할 서드파티 제공자 설정을 통해 로그인 없이 사용할 수도 있다.
Claude 패널 여는 방법과 Spark 아이콘
Claude를 열기 위한 대표적인 진입로는 "Spark 아이콘"이다.
파일을 하나 연 상태에서 에디터 오른쪽 위 툴바를 보면 작은 불꽃 모양 아이콘이 나타나는데, 이것을 클릭하면 Claude 패널이 오른쪽에 열린다.
파일이 열려 있지 않으면 이 아이콘은 보이지 않으며, 대신 아래 방법들을 사용할 수 있다.
Command Palette(Cmd+Shift+P / Ctrl+Shift+P)에서 "Claude Code"를 입력해 "Open in New Tab" 같은 항목을 선택하거나, 우측 하단 상태 바에 있는 "✱ Claude Code"를 클릭하면 된다.
Spark 아이콘이 안 보일 때는 VS Code 버전, Restricted Mode, 다른 AI 확장과의 충돌 등을 의심해 볼 수 있으며, 이런 경우 상태 바 또는 Command Palette를 통해 우회할 수 있다.
코드와 함께 쓰는 기본 상호작용 패턴
Claude와 상호작용의 기본은 "코드를 선택 → @-mention으로 맥락 전달 → 질문 → diff 검토" 흐름이다.
에디터에서 특정 코드 범위를 드래그한 뒤 Alt+K를 누르면, 그 파일 경로와 선택된 줄 번호를 포함한 @-mention이 입력란에 자동으로 들어간다.
이 상태에서 "이 함수의 시간 복잡도 설명해줘" 혹은 "여기서 발생하는 버그 원인을 찾아줘"처럼 질문하면, Claude는 정확한 코드 위치를 알고 답변한다.
Claude가 파일 수정을 제안하면, 먼저 diff 화면이 나타나고 사용자는 변경 내용을 한눈에 비교한 뒤 수락 또는 거절할 수 있다.
이 과정을 통해 "AI가 코드 전체를 마음대로 바꾸는 것"이 아니라 "제안된 패치(diff)를 인간이 승인하는 방식"으로 안전하게 협업할 수 있다.
레이아웃과 터미널 모드 커스터마이징
Claude 패널은 위치를 자유롭게 옮길 수 있다.
탭이나 제목 표시줄을 드래그해 오른쪽 보조 사이드바(기본), 왼쪽 메인 사이드바(Explorer 아이콘들이 있는 곳), 또는 에디터 영역(파일 탭과 나란히)으로 이동시킬 수 있다.
왼쪽 사이드바에 둘 경우 Activity Bar에 Spark 아이콘이 생겨 왼쪽에서도 바로 열 수 있지만, 오른쪽에 둘 경우 에디터 상단 아이콘을 사용하는 것이 일반적이다.
GUI 채팅 대신 CLI 스타일을 선호한다면 설정에서 "Use Terminal" 옵션을 켜면 된다.
이렇게 하면 별도의 확장을 바꾸지 않고도 "그래픽 패널 ↔ 터미널 인터페이스"를 전환하며 작업할 수 있다.
자주 쓰이는 VS Code 명령과 단축키
Command Palette에서 "Claude Code"를 입력하면 확장이 제공하는 명령 목록을 확인할 수 있다.
에디터와 Claude 사이 포커스를 오갈 때는 Cmd+Esc/Ctrl+Esc를 사용할 수 있고, 새로운 대화 탭을 열고 싶다면 Cmd+Shift+Esc/Ctrl+Shift+Esc로 "Open in New Tab" 명령을 실행하면 된다.
Claude가 포커스를 갖고 있을 때 Cmd+N/Ctrl+N은 새로운 대화를 여는 용도로 쓰이며, Alt+K는 언제나 현재 파일(또는 선택한 코드 범위)을 @-mention으로 삽입하는 단축키다.
Slash 명령(/help, /model 등)은 CLI보다 제한적이며, 입력란에서 /를 눌러 현재 확장에서 지원하는 목록을 확인할 수 있다.
확장 설정과 공통 설정 파일 이해하기
VS Code 안에는 두 종류의 관련 설정이 존재한다.
하나는 VS Code 자체의 확장 설정으로, Cmd+,/Ctrl+, → Extensions → Claude Code에서 UI로 수정할 수 있다.
여기서는 기본 모델, 터미널 모드 사용 여부, 초기 권한 모드(자동 승인/매번 확인), 기본 위치, 자동 저장, 단축키 동작, .gitignore 존중 여부, 로그인 프롬프트 표시 여부, 위험한 권한 무시 옵션 등 "IDE 동작"에 가까운 항목들을 다룬다.
다른 하나는 ~/.claude/settings.json 파일로, 확장과 CLI가 공유하는 "Claude Code 설정"이다.
여기에는 환경 변수, 허용 명령어와 디렉터리, 훅(Hooks), MCP 서버 설정 등 AI 에이전트 동작 자체에 관한 설정을 정의해 두며, 한 번 설정해 두면 CLI와 VS Code 모두 동일하게 활용할 수 있다.
서드파티 제공자(AWS Bedrock, Vertex, Foundry)와 연동하기
조직에서 Anthropic API 대신 AWS Bedrock, Google Vertex AI, Microsoft Foundry를 통해 Claude에 접근하는 경우도 많다.
이때는 먼저 VS Code 확장 설정에서 "Disable Login Prompt"를 켜 Anthropic 계정 로그인 팝업이 뜨지 않도록 만든다.
그 다음 각 제공자별 문서(예: Amazon Bedrock용 설정 가이드)를 따라 ~/.claude/settings.json에 자격 증명, 엔드포인트, 모델명 등을 기입하면 된다.
이 방식의 장점은 "한 번 설정하면 VS Code 확장과 CLI 둘 다 동일한 서드파티 백엔드를 사용한다"는 점이다.
VS Code 확장과 CLI의 관계 및 전환
확장과 CLI는 완전 동일하지 않다.
CLI는 모든 slash 명령, MCP 서버 설정, 체크포인트, ! bash 단축, 탭 자동 완성 등 고급 기능을 제공하지만, 확장은 이 중 일부만 제공한다.
그래서 "가벼운 코드 편집, 설명, 소규모 리팩터링"은 확장에서 처리하고, "복잡한 자동화, CLI 중심 작업"은 통합 터미널에서 claude를 실행해 하는 식으로 역할을 나누면 효율적이다.
통합 터미널에서 claude를 실행하면 diff 뷰, 진단 공유 등 IDE 통합 기능을 그대로 활용할 수 있고, 기존 대화를 이어서 보고 싶다면 claude --resume으로 이전 세션을 선택해 이어갈 수 있다.
보안과 문제 해결의 핵심 포인트
Claude에 "자동 편집 허용"을 켜두면 VS Code의 설정 파일(settings.json, tasks.json 등)을 수정할 수 있고, VS Code는 이 파일들을 자동으로 실행하거나 로드할 수 있다.
이 조합은 곧 "IDE 수준의 행동"을 우회적으로 바꿀 수 있다는 의미이므로, 특히 외부에서 가져온 의심스러운 코드 작업 시에는 다음을 권장한다.
VS Code의 Restricted Mode를 켜고, 자동 승인 대신 매번 편집 승인을 요구하도록 설정하며, diff를 꼼꼼히 확인한 뒤 적용하는 습관을 들이는 것이 안전하다.
동작 문제가 생길 때는 VS Code 버전/인터넷 연결을 확인하고, 새 대화를 열어보거나 CLI에서 같은 작업을 시도해 더 구체적인 에러 메시지를 확인해 볼 수 있다.
Spark 아이콘 미표시, CLI-IDE 연결 실패 등의 흔한 문제는 버전, PATH에 설치된 code/cursor 명령, 다른 AI 확장 충돌, Restricted Mode를 우선 점검하면 대부분 해결된다.
확장을 완전히 제거하고 싶다면 VS Code Extensions 뷰에서 언인스톨 후, 필요하다면 ~/.vscode/globalStorage/anthropic.claude-code를 삭제해 데이터와 설정까지 초기화할 수 있다.
인사이트
VS Code용 Claude Code는 "코드를 직접 건드리는 AI 파트너"이기 때문에, 설치만 하는 도구가 아니라 편집 권한과 레이아웃, 보안을 스스로 설계하면서 써야 진가가 드러난다.
작업 흐름을 정리하자면, "코드 선택 → @-mention → 질문 → diff 검토 → 점진적 적용"이라는 루틴을 몸에 익히고, 프로젝트나 작업 단위별로 별도의 대화 탭을 유지하면 맥락 관리가 훨씬 쉬워진다.
추가로, ~/.claude/settings.json을 중심으로 CLI와 확장을 함께 운용하는 구조를 잡아두면, 로컬 IDE에서 하던 작업을 그대로 터미널·서버 환경 등으로 확장할 수 있어 장기적으로 큰 생산성 이득을 얻을 수 있다.