VS Code 확장 프로그램

들어가며

이전 차시에서 터미널에서 Claude Code를 사용하는 방법을 살펴봤다. CLI 명령어와 플래그, 슬래시 명령어, 파이프와 리다이렉션을 다뤘다. 이런 터미널 기반 사용법은 강력하지만, 코드 에디터와 분리된 환경에서 작업해야 한다.

VS Code 확장 프로그램은 이 문제를 해결한다. 에디터 안에서 Claude Code의 모든 기능을 사용할 수 있다. 파일을 열고, 코드를 선택하고, Claude에게 질문하고, 변경사항을 리뷰하는 과정이 하나의 창에서 이루어진다. 인라인 diff로 변경사항을 바로 확인하고, @-멘션으로 파일을 참조하고, 권한 모드를 클릭 한 번으로 전환할 수 있다.

이번 차시에서는 세 가지를 다룬다. 먼저 확장 프로그램 설치와 초기 설정을 진행한다. 그 다음 프롬프트 박스, @-멘션, 권한 모드, 체크포인트 같은 주요 기능을 살펴본다. 마지막으로 단축키, 플러그인, Chrome 연동 같은 고급 기능을 알아본다.

설치

요구 사항

설치 전에 두 가지를 확인한다.

VS Code 1.98.0 이상: Help > About에서 버전을 확인한다
Anthropic 계정: 첫 실행 시 로그인이 필요하다. Amazon Bedrock이나 Google Vertex AI 같은 서드파티 프로바이더를 사용하는 경우에는 별도 설정이 필요하다

Cursor에서도 동일한 확장 프로그램을 사용할 수 있다.

설치 방법

마켓플레이스에서 설치:

VS Code에서 Cmd+Shift+X(Mac) 또는 Ctrl+Shift+X(Windows/Linux)를 눌러 Extensions 뷰를 연다
“Claude Code”를 검색한다
Install을 클릭한다

설치 후 확장 프로그램이 나타나지 않으면 VS Code를 재시작하거나, Command Palette에서 “Developer: Reload Window”를 실행한다.

시작하기

패널 열기

VS Code 안에서 Claude Code를 나타내는 아이콘은 스파크(Spark) 아이콘이다. 패널을 여는 방법은 여러 가지가 있다.

에디터 툴바: 에디터 오른쪽 상단의 스파크 아이콘을 클릭한다. 파일이 열려 있어야 표시된다
액티비티 바: 왼쪽 사이드바의 스파크 아이콘을 클릭하면 세션 목록이 열린다. 세션을 클릭하면 에디터 탭으로 열린다
Command Palette: Cmd+Shift+P(Mac) 또는 Ctrl+Shift+P(Windows/Linux)를 누르고 “Claude Code”를 입력한다. “Open in New Tab” 같은 옵션을 선택한다
상태 바: 하단 오른쪽의 ”✱ Claude Code”를 클릭한다. 파일이 열려 있지 않아도 동작한다

첫 프롬프트 전송

에디터에서 코드를 선택하면 Claude가 자동으로 선택한 코드를 인식한다. Option+K(Mac) 또는 Alt+K(Windows/Linux)를 누르면 @file.ts#5-10 같은 @-멘션 참조가 프롬프트에 삽입된다.

변경사항 리뷰

Claude가 파일을 수정하려고 하면, 원본과 변경안을 나란히 비교하는 diff 뷰를 보여준다. 승인하거나, 거부하거나, Claude에게 다른 방향을 지시할 수 있다.

프롬프트 박스

프롬프트 박스는 단순한 입력창이 아니다. 여러 기능이 내장되어 있다.

권한 모드

프롬프트 박스 하단의 모드 표시기를 클릭하면 권한 모드를 전환한다.

UI 표시	모드	설명
Ask before edits	`default`	각 작업 전에 허가를 요청한다
Edit automatically	`acceptEdits`	파일 수정을 자동으로 허용한다
Plan mode	`plan`	변경 계획을 세우고 승인을 기다린다
Auto mode	`auto`	모든 작업을 자동 실행한다 (별도 활성화 필요)

Plan 모드에서는 Claude가 계획을 마크다운 문서로 작성한다. VS Code가 이 문서를 에디터 탭으로 열어준다. 인라인 코멘트를 추가해서 피드백을 줄 수 있다. Claude가 수정을 시작하기 전에 계획을 충분히 검토할 수 있다.

기본 권한 모드는 VS Code 설정의 claudeCode.initialPermissionMode에서 지정한다.

명령 메뉴

/를 입력하면 명령 메뉴가 열린다. 사용 가능한 기능은 다음과 같다.

파일 첨부
모델 전환
확장 사고(Extended Thinking) 토글
사용량 확인 (/usage)
Remote Control 세션 시작 (/remote-control)
MCP 서버, Hooks, 메모리, 권한, 플러그인 등 커스터마이즈 항목

터미널 아이콘이 표시된 항목은 통합 터미널에서 열린다.

컨텍스트 표시

프롬프트 박스에 Claude의 컨텍스트 윈도우 사용량이 표시된다. Claude가 필요하면 자동으로 압축하지만, /compact를 직접 실행할 수도 있다.

확장 사고

복잡한 문제에서 Claude가 더 깊이 추론하게 하는 기능이다. 명령 메뉴(/)에서 토글할 수 있다.

여러 줄 입력

Shift+Enter를 누르면 전송하지 않고 줄을 바꾼다. 질문 다이얼로그의 자유 텍스트 입력에서도 동일하게 동작한다.

@-멘션으로 파일 참조

@를 입력하고 파일이나 폴더 이름을 쓰면 Claude가 해당 내용을 읽고 참조한다. 퍼지 매칭을 지원하므로 이름의 일부만 입력해도 된다.

> @auth 이 로직을 설명해줘 (auth.js, AuthService.ts 등에 매칭)
> @src/components/ 이 폴더 구조를 설명해줘 (폴더는 끝에 / 추가)

대용량 PDF 파일은 전체 대신 특정 페이지만 읽도록 요청할 수 있다. 단일 페이지, 1-10 같은 범위, 3페이지부터 끝까지 같은 열린 범위를 지정한다.

에디터에서 코드를 선택하면 Claude가 자동으로 하이라이트된 코드를 인식한다. 프롬프트 박스 하단에 선택한 줄 수가 표시된다. Option+K(Mac) / Alt+K(Windows/Linux)를 누르면 파일 경로와 줄 번호가 포함된 @-멘션이 삽입된다 (예: @app.ts#5-10). 선택 표시기를 클릭하면 선택 영역의 표시/숨김을 토글한다.

Shift를 누른 채 파일을 프롬프트 박스로 드래그하면 첨부 파일로 추가된다. 첨부 파일의 X를 클릭하면 제거한다.

터미널 출력 참조

@terminal:name 형식으로 터미널 출력을 프롬프트에 포함할 수 있다. name은 터미널의 제목이다. 명령 출력, 에러 메시지, 로그를 복사-붙여넣기 없이 Claude에게 전달할 수 있다.

대화 관리

대화 재개

패널 상단의 드롭다운을 클릭하면 대화 히스토리에 접근한다. 키워드로 검색하거나 시간별(오늘, 어제, 최근 7일 등)로 탐색한다. 대화를 클릭하면 전체 메시지 히스토리와 함께 재개된다. 새 세션은 첫 메시지 기반으로 AI가 제목을 생성한다. 세션 위에 마우스를 올리면 이름 변경과 삭제 아이콘이 나타난다.

원격 세션 재개

Claude Code on the web(claude.ai)에서 시작한 원격 세션을 VS Code에서 재개할 수 있다. Claude.ai Subscription으로 로그인해야 한다.

Past Conversations 드롭다운을 연다
Remote 탭을 선택한다
원격 세션을 클릭하면 로컬에서 대화를 이어간다

GitHub 리포지토리와 함께 시작한 웹 세션만 Remote 탭에 나타난다. 재개하면 대화 히스토리가 로컬에 다운로드되며, 변경사항이 claude.ai로 다시 동기화되지는 않는다.

여러 대화 실행

Command Palette에서 “Open in New Tab” 또는 “Open in New Window”를 선택하면 추가 대화를 시작한다. 각 대화는 독립된 히스토리와 컨텍스트를 유지하므로, 다른 작업을 병렬로 진행할 수 있다.

탭을 사용할 때, 스파크 아이콘 위의 작은 점이 상태를 나타낸다. 파란색은 권한 요청이 대기 중이라는 뜻이고, 주황색은 탭이 숨겨진 동안 Claude가 작업을 완료했다는 뜻이다.

패널 위치 조정

Claude 패널의 탭이나 타이틀 바를 드래그해서 원하는 위치로 옮길 수 있다.

보조 사이드바: 윈도우 오른쪽. 코딩하면서 Claude를 계속 볼 수 있다
기본 사이드바: Explorer, Search 등이 있는 왼쪽 사이드바
에디터 영역: 파일 탭과 나란히 열린다. 사이드 작업에 유용하다

주요 Claude 세션은 사이드바에, 추가 작업은 탭으로 열면 효율적이다. Claude가 선호 위치를 기억한다.

체크포인트

VS Code 확장 프로그램은 체크포인트를 지원한다. Claude가 파일을 수정할 때마다 상태를 추적하고, 이전 상태로 되돌릴 수 있다.

작동 방식

모든 사용자 프롬프트마다 새 체크포인트가 생성된다
체크포인트는 세션 간에 유지되어, 재개된 대화에서도 접근할 수 있다
30일 후 세션과 함께 자동 정리된다

되돌리기

메시지 위에 마우스를 올리면 되돌리기 버튼이 나타난다. 세 가지 옵션을 선택할 수 있다.

Fork conversation from here: 이 메시지부터 새 대화를 분기한다. 코드 변경은 유지한다
Rewind code to here: 이 시점으로 파일 변경을 되돌린다. 전체 대화 히스토리는 유지한다
Fork conversation and rewind code: 새 대화를 분기하면서 파일 변경도 이 시점으로 되돌린다

제한 사항

체크포인트가 추적하지 않는 것이 있다.

Bash 명령으로 인한 변경: rm, mv, cp 같은 셸 명령은 추적하지 않는다. Claude의 파일 편집 도구(Read, Edit, Write)를 통한 수정만 추적한다
외부 변경: 현재 세션 밖에서 직접 수정한 파일은 캡처하지 않는다
Git 대체 불가: 체크포인트는 세션 수준의 빠른 복구를 위한 것이다. 버전 관리는 Git으로 해야 한다

VS Code 명령어와 단축키

Command Palette(Cmd+Shift+P / Ctrl+Shift+P)에서 “Claude Code”를 입력하면 사용 가능한 모든 VS Code 명령이 표시된다.

일부 단축키는 포커스 위치에 따라 달라진다. 커서가 코드 파일에 있으면 에디터가 포커스된 상태고, Claude의 프롬프트 박스에 있으면 Claude가 포커스된 상태다. Cmd+Esc(Mac) / Ctrl+Esc(Windows/Linux)로 포커스를 토글한다.

명령	단축키	설명
Focus Input	`Cmd+Esc` / `Ctrl+Esc`	에디터와 Claude 간 포커스 토글
Open in New Tab	`Cmd+Shift+Esc` / `Ctrl+Shift+Esc`	새 대화를 에디터 탭으로 열기
New Conversation	`Cmd+N` / `Ctrl+N`	새 대화 시작 (Claude 포커스 + 설정 필요)
Insert @-Mention Reference	`Option+K` / `Alt+K`	현재 파일과 선택 영역의 참조 삽입
Show Logs	-	확장 프로그램 디버그 로그 보기
Logout	-	Anthropic 계정 로그아웃

New Conversation은 Claude가 포커스된 상태에서만 동작하고, enableNewConversationShortcut 설정이 true여야 한다.

URI 핸들러

확장 프로그램은 vscode://anthropic.claude-code/open URI 핸들러를 등록한다. 셸 별칭, 브라우저 북마클릿, 스크립트에서 Claude Code 탭을 열 수 있다.

# macOS
open "vscode://anthropic.claude-code/open"

# 프롬프트 미리 채우기
open "vscode://anthropic.claude-code/open?prompt=review%20my%20changes"

# 특정 세션 재개
open "vscode://anthropic.claude-code/open?session=abc123"

Linux에서는 xdg-open, Windows에서는 start를 사용한다. prompt 파라미터는 프롬프트 박스에 텍스트를 미리 채우지만 자동으로 전송하지는 않는다. session 파라미터는 해당 세션을 재개한다.

플러그인 관리

VS Code 확장 프로그램에서 플러그인을 설치하고 관리할 수 있다. 프롬프트 박스에 /plugins를 입력하면 관리 인터페이스가 열린다.

설치

플러그인 다이얼로그에는 Plugins 탭과 Marketplaces 탭이 있다.

Plugins 탭에서는 설치된 플러그인의 활성화/비활성화를 토글하고, 마켓플레이스에서 사용 가능한 플러그인을 검색해 설치한다. 플러그인 설치 시 스코프를 선택한다.

스코프	설명
Install for you	모든 프로젝트에서 사용 가능 (사용자 스코프)
Install for this project	프로젝트 공동 작업자와 공유 (프로젝트 스코프)
Install locally	이 리포지토리에서 나만 사용 (로컬 스코프)

마켓플레이스 관리

Marketplaces 탭에서 플러그인 소스를 추가하거나 제거한다. GitHub 리포지토리, URL, 로컬 경로를 입력해서 새 마켓플레이스를 추가한다. 새로고침 아이콘으로 목록을 업데이트하고, 휴지통 아이콘으로 제거한다.

변경 후에는 Claude Code 재시작 배너가 표시된다. VS Code에서 설정한 플러그인과 마켓플레이스는 CLI에서도 동일하게 사용할 수 있고, 반대도 마찬가지다.

Chrome 브라우저 연동

Chrome 브라우저를 Claude에 연결하면 웹 앱을 테스트하고, 콘솔 로그로 디버깅하고, 브라우저 작업을 자동화할 수 있다. VS Code를 떠나지 않고 코딩과 브라우저 테스트를 함께 진행한다.

요구 사항

Chrome 또는 Microsoft Edge 브라우저
Claude in Chrome 확장 프로그램 버전 1.0.36 이상
Claude Code 버전 2.0.73 이상
Anthropic 직접 플랜 (Pro, Max, Team, Enterprise)

사용 방법

프롬프트 박스에 @browser를 입력하고 원하는 작업을 설명한다.

@browser localhost:3000에 가서 콘솔 에러를 확인해줘

첨부 메뉴에서 특정 브라우저 도구(새 탭 열기, 페이지 내용 읽기 등)를 선택할 수도 있다. Claude는 브라우저의 로그인 상태를 공유하므로, 이미 로그인한 사이트에 접근할 수 있다.

활용 예시

로컬 웹 앱 테스트: 폼 유효성 검증, 시각적 회귀 확인
콘솔 디버깅: 페이지 로드 시 에러 확인
데이터 추출: 웹 페이지에서 구조화된 정보 추출
GIF 녹화: 브라우저 상호작용을 데모 GIF로 기록

터미널 모드

기본적으로 확장 프로그램은 그래픽 채팅 패널을 연다. CLI 스타일 인터페이스를 선호하면 터미널 모드로 전환할 수 있다.

VS Code 설정(Cmd+, / Ctrl+,)에서 Extensions > Claude Code > “Use Terminal”을 체크한다. 또는 프롬프트 박스에서 /를 입력하고 “Open in Terminal”을 선택한다.

확장 프로그램 vs CLI

Claude Code는 VS Code 확장 프로그램(그래픽 패널)과 CLI(터미널 인터페이스) 두 가지로 사용할 수 있다. 일부 기능은 CLI에서만 사용 가능하다. CLI 전용 기능이 필요하면 VS Code 통합 터미널에서 claude를 실행한다.

기능	CLI	VS Code 확장 프로그램
명령어와 스킬	전체	일부 (`/`로 확인)
MCP 서버 설정	전체	부분 (CLI로 추가, `/mcp`로 관리)
체크포인트	지원	지원
`!` Bash 단축키	지원	미지원
Tab 자동완성	지원	미지원

확장 프로그램과 CLI는 같은 대화 히스토리를 공유한다. 확장 프로그램에서 시작한 대화를 CLI에서 이어가려면 터미널에서 claude --resume을 실행한다.

외부 터미널에서 Claude Code를 실행할 때 VS Code와 연결하려면 /ide를 실행한다.

설정

확장 프로그램에는 두 종류의 설정이 있다.

VS Code 확장 프로그램 설정

VS Code 안에서 확장 프로그램의 동작을 제어한다. Cmd+,(Mac) 또는 Ctrl+,(Windows/Linux)로 열고, Extensions > Claude Code로 이동한다.

설정	기본값	설명
`useTerminal`	`false`	그래픽 패널 대신 터미널 모드로 시작
`initialPermissionMode`	`default`	새 대화의 권한 모드
`preferredLocation`	`panel`	Claude가 열리는 위치 (`sidebar` 또는 `panel`)
`autosave`	`true`	Claude가 파일을 읽거나 쓰기 전 자동 저장
`useCtrlEnterToSend`	`false`	Enter 대신 Ctrl/Cmd+Enter로 전송
`enableNewConversationShortcut`	`false`	Cmd/Ctrl+N으로 새 대화 시작 활성화
`respectGitIgnore`	`true`	.gitignore 패턴을 파일 검색에서 제외
`usePythonEnvironment`	`true`	워크스페이스의 Python 환경 활성화
`disableLoginPrompt`	`false`	인증 프롬프트 건너뛰기 (서드파티 프로바이더용)

Claude Code 설정

~/.claude/settings.json에 저장되며, 확장 프로그램과 CLI에서 공유된다. 허용 명령, 환경 변수, Hooks, MCP 서버 등을 설정한다.

settings.json 파일에 다음 줄을 추가하면 자동완성과 인라인 검증을 사용할 수 있다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Git 통합

커밋과 PR

Claude에게 커밋과 PR을 요청할 수 있다.

> 내 변경사항을 설명이 포함된 메시지로 커밋해줘
> 이 기능에 대한 PR을 만들어줘
> auth 모듈에 대한 변경사항을 요약해줘

Git Worktree

--worktree(-w) 플래그로 격리된 worktree에서 Claude를 시작할 수 있다. 각 worktree는 독립된 파일 상태를 유지하면서 Git 히스토리를 공유한다.

claude --worktree feature-auth

내장 IDE MCP 서버

확장 프로그램이 활성화되면 로컬 MCP 서버가 실행된다. CLI가 이 서버에 자동으로 연결해서 VS Code의 네이티브 diff 뷰어를 열고, 현재 선택 영역을 읽고, Jupyter 노트북에서 셀을 실행한다.

이 서버는 ide라는 이름이고, 설정할 것이 없어서 /mcp에 표시되지 않는다. 127.0.0.1의 랜덤 고포트에 바인딩되어 외부에서 접근할 수 없다. 매 활성화마다 새 인증 토큰이 생성되고, ~/.claude/ide/의 잠금 파일에 0600 권한으로 저장된다.

모델에 노출되는 도구는 두 개다.

도구 이름	설명	쓰기 여부
`mcp__ide__getDiagnostics`	VS Code Problems 패널의 언어 서버 진단 정보를 반환한다	아니오
`mcp__ide__executeCode`	활성 Jupyter 노트북 커널에서 Python 코드를 실행한다	예

mcp__ide__executeCode는 아무것도 자동으로 실행하지 않는다. 매번 코드가 노트북 마지막에 새 셀로 삽입되고, VS Code가 스크롤해서 보여준 뒤, Quick Pick으로 실행 또는 취소를 묻는다.

문제 해결

스파크 아이콘이 보이지 않을 때

파일을 연다. 폴더만 열어서는 아이콘이 나타나지 않는다
VS Code 버전이 1.98.0 이상인지 확인한다
VS Code를 재시작하거나 “Developer: Reload Window”를 실행한다
다른 AI 확장 프로그램(Cline, Continue 등)을 일시적으로 비활성화한다
Workspace Trust의 Restricted Mode가 아닌지 확인한다

상태 바의 ”✱ Claude Code”는 파일 없이도 동작하므로 대안으로 사용할 수 있다.

Claude Code가 응답하지 않을 때

인터넷 연결을 확인한다
새 대화를 시작해본다
터미널에서 claude를 실행해서 더 자세한 에러 메시지를 확인한다

확장 프로그램 제거

Extensions 뷰(Cmd+Shift+X / Ctrl+Shift+X)를 연다
“Claude Code”를 검색한다
Uninstall을 클릭한다

확장 프로그램 데이터와 설정까지 완전히 제거하려면 다음을 실행한다.

rm -rf ~/.vscode/globalStorage/anthropic.claude-code

서드파티 프로바이더

기본적으로 Claude Code는 Anthropic API에 직접 연결한다. Amazon Bedrock, Google Vertex AI, Microsoft Foundry를 통해 Claude에 접근하는 경우에는 별도 설정이 필요하다.

VS Code 설정에서 “Disable Login Prompt”를 체크한다
~/.claude/settings.json에 프로바이더 설정을 추가한다

이 설정은 확장 프로그램과 CLI에서 공유된다.

보안과 프라이버시

코드는 Claude의 분석을 위해 Anthropic 서버로 전송되지만, 모델 학습에 사용되지 않는다.

자동 편집 허용 모드에서는 Claude Code가 VS Code 설정 파일(settings.json, tasks.json)을 수정할 수 있고, VS Code가 이를 자동으로 실행할 수 있다. 신뢰할 수 없는 코드를 작업할 때는 다음을 고려한다.

VS Code의 Restricted Mode를 활성화한다
자동 승인 대신 수동 승인 모드를 사용한다
변경사항을 승인 전에 신중히 검토한다

정리

핵심 요점

설치와 시작: VS Code 1.98.0 이상에서 Extensions 뷰를 통해 설치한다. 스파크 아이콘, 액티비티 바, Command Palette, 상태 바 등 여러 경로로 Claude Code 패널을 열 수 있다
프롬프트 박스: 단순한 입력창이 아니라 권한 모드 전환, 명령 메뉴, 컨텍스트 사용량 표시, 확장 사고 토글 등의 기능이 내장되어 있다
@-멘션: @파일명으로 파일을 참조하고, @terminal:name으로 터미널 출력을 포함하고, Option+K / Alt+K로 현재 선택 영역을 @-멘션으로 삽입한다
체크포인트: 모든 편집 작업의 상태를 추적한다. 메시지 위에서 되돌리기 버튼으로 대화 분기, 코드 되돌리기, 또는 둘 다 수행할 수 있다
단축키: Cmd+Esc / Ctrl+Esc(포커스 토글), Cmd+Shift+Esc / Ctrl+Shift+Esc(새 탭), Option+K / Alt+K(@-멘션 삽입)가 핵심이다
확장 프로그램 vs CLI: 같은 대화 히스토리를 공유하지만 CLI에만 있는 기능(! Bash 단축키, Tab 자동완성, 전체 명령어)이 있다. 필요하면 통합 터미널에서 claude를 실행한다

확인해볼 링크

다음 단계

다음 차시에서는 JetBrains 플러그인을 다룬다. IntelliJ IDEA, PyCharm, WebStorm 등에서 Claude Code를 설치하고 설정하는 방법, IDE 통합 기능, 단축키 커스터마이징을 살펴본다.

VS Code 확장 프로그램

들어가며

설치

요구 사항

설치 방법

시작하기

패널 열기

로그인

첫 프롬프트 전송

변경사항 리뷰

프롬프트 박스

권한 모드

명령 메뉴

컨텍스트 표시

확장 사고

여러 줄 입력

@-멘션으로 파일 참조

터미널 출력 참조

대화 관리

대화 재개

원격 세션 재개

여러 대화 실행

패널 위치 조정

체크포인트

작동 방식

되돌리기

제한 사항

VS Code 명령어와 단축키

URI 핸들러

플러그인 관리

설치

마켓플레이스 관리

Chrome 브라우저 연동

요구 사항

사용 방법

활용 예시

터미널 모드

확장 프로그램 vs CLI

설정

VS Code 확장 프로그램 설정

Claude Code 설정

Git 통합

커밋과 PR

Git Worktree

내장 IDE MCP 서버

문제 해결

스파크 아이콘이 보이지 않을 때

Claude Code가 응답하지 않을 때

확장 프로그램 제거

서드파티 프로바이더

보안과 프라이버시

정리

핵심 요점

확인해볼 링크

다음 단계

참고 자료