VS Code에서 Claude Code 사용하기: 설정, 단축키, 팁 (2026)
VS Code 안에서 Claude Code를 실행하고 싶으세요? 공식 Anthropic 확장을 Marketplace에서 설치하고('Claude Code' 검색, publisher는 Anthropic), 유료 Claude 플랜으로 로그인한 다음, Spark 아이콘 ✱에서 패널을 열면 돼요. 약 2분이면 충분해요. 최신 VS Code 빌드와 Pro, Max, Team, Enterprise 중 하나의 플랜이 필요해요(API 키 불필요, 무료 등급 없음). 바로 써볼 만한 기능은 세 가지예요: diff 리뷰(변경을 하나씩 승인), 플랜 모드, 그리고 파일과 터미널 출력을 컨텍스트로 가져오는 @멘션이에요.
공식 문서 code.claude.com/docs/en/vs-code와 대조해 다시 확인했어요(2026/08/10 접속).
잠깐 짚고 가기: 'claude code vs code'는 무슨 뜻일까요?
혹시 'claude code vs code'라고 검색해서 다른 도구와의 정면 비교를 기대했다면, 잘못 찾아오셨어요. 여기서 'vs code' = Visual Studio Code이니, 진짜 주제는 VS Code에 통합된 Claude Code 사용법이지 대결이 아니에요. (정말 비교를 찾고 있다면, 먼저 Claude Code가 무엇인지부터 기본을 잡아 보세요.)
또 흔한 혼동 하나: 이 글이 다루는 건 공식 'Claude Code' 확장(publisher anthropic.claude-code, Spark 아이콘 ✱, diff/플랜/체크포인트 포함)이지, 많은 가이드가 안내하는 예전 'Claude AI' 채팅 사이드바 확장이 아니에요. 둘은 완전히 다른 제품이에요. 공식 확장은 워크스페이스 전체를 이해하고, 여러 파일을 한 번에 편집하며, 검토할 수 있게 diff를 돌려줘요. 반면 예전 채팅 확장은 대부분 코드 옆에 놓인 질문·답변 상자에 가까워요. 어떤 가이드가 Spark 아이콘, diff 리뷰, 플랜 모드를 전혀 언급하지 않는다면, 거의 확실히 다른 제품 이야기예요.
먼저 필요한 것(요구 사항)
설치 전에, 시간을 낭비하지 않도록 세 가지를 확인하세요:
- 최신 VS Code 빌드 - 공식 문서는 버전
>= 1.94.0을 제시해요.Help -> About에서 확인하고, 너무 오래됐다면 먼저 업데이트하세요. - 유료 Claude 플랜: Pro, Max, Team, Enterprise 중 하나(또는 Claude Console 접근). 이건 필수 조건이에요.
- API 키 불필요, 무료 등급 없음. 이 확장은 일부 다른 도구처럼 붙여넣은 키가 아니라 Claude 계정으로 로그인해요. 아직 플랜이 없다면 사용할 수 없어요 - 자기 API 키를 넣을 수 있는 일부 서드파티 AI 확장과의 분명한 차이예요.
제약을 솔직히 말하면, 유료 플랜에 의존하기 때문에 무료로 쓰고 싶은 분에게 맞는 선택지는 아니에요. 대신 API 할당량을 관리하거나 토큰 청구서에 놀랄 일이 없고, 사용량은 구독 안에 머물러요. 플랜 사이에서 망설여진다면 사용 빈도로 정하세요: 가볍게 시험하거나 배우는 데는 Pro면 충분하고, 하루 종일 이 도구를 쓴다면 Max가 값을 해요.
Claude Code가 무엇인지, 어디까지 되는지 아직 잘 모르겠다면 Claude Code 입문을 읽고 여기로 돌아와 확장을 설치하세요.
VS Code용 Claude Code 확장 설치 방법(단계별)
전체 과정은 약 2분이에요. 네 단계예요:
- 확장 탭 열기:
Ctrl+Shift+X(Windows/Linux) 또는Cmd+Shift+X(macOS). 검색창에 'Claude Code'를 입력하고, publisher Anthropic의 확장을 고른 뒤(다른 'Claude AI' 확장과 헷갈리지 마세요) Install을 클릭해요. - Claude Code 패널 열기: Spark 아이콘 ✱을 클릭해요. 아이콘은 에디터 툴바(파일을 열면 오른쪽 위), 왼쪽 액티비티 바, 또는 아래쪽 상태 표시줄에 나타나요. 팁: 아이콘이 뚜렷이 보이려면 파일을 최소 하나는 열어 두어야 해요.
- 로그인: Sign in을 클릭하면 VS Code가 브라우저를 열어 Claude 계정으로 인증해요. VS Code로 돌아오면 패널이 준비돼요.
- 테스트 프롬프트 보내기: '이 파일이 무엇을 하는지 설명해줘' 같은 간단한 걸로 전부 잘 되는지 확인해요. Claude가 답하고 열어 둔 파일을 인식하면 설치가 잘 된 거예요.
처음부터 들이면 좋은 습관 하나: 설치 후에는 낱개 파일이 아니라 실제 프로젝트 폴더를 열어 Claude가 워크스페이스 전체 컨텍스트를 볼 수 있게 하세요. Windows에서 WSL로 작업한다면, 평소처럼 VS Code의 WSL 모드로 프로젝트를 열고 패널을 띄우면 돼요 - 그 환경에서도 확장은 잘 동작해요.
이 확장은 순정 VS Code에만 국한되지 않아요 - Cursor, Kiro, Open VSX 기반 빌드에도 같은 단계로 설치돼요. 터미널에서 claude 명령도 쓰고 싶다면 Claude Code CLI 전체 설치 가이드를 보세요(확장과 CLI는 서로를 보완해요, 아래에서 더 다룰게요).
VS Code 안의 인터페이스와 핵심 기능
터미널에 명령을 입력하는 것과 비교하면, 확장은 훨씬 시각적인 인터페이스를 줘요. 써볼 만한 기능은 다음과 같아요:
- 나란히 보는 diff 리뷰: Claude가 파일을 편집할 때마다 변경이 초록·빨강으로 또렷하게 나란히 diff로 표시돼요. 한 번에 하나씩 검토하고, 각각을 개별로 수락하거나 거절하며, 수락 전에 diff 안에서 직접 편집할 수도 있어요. 채팅에서 코드를 복사해 손으로 병합하는 것과는 천지 차이로, 무엇이 바뀔지 항상 정확히 보이고 줄 단위로 막을 수 있어요. 이것이 VS Code에서 작업하는 가장 강력한 이유예요.
- 플랜 모드: 플랜 모드에서 Claude는 계획을 Markdown으로 열어 주어, 코드에 손대기 전에 읽고 인라인으로 코멘트할 수 있어요. 큰 작업에 아주 잘 맞아요: 방향을 검토하고 계획의 몇 군데를 손본 다음에야 실행시키니, AI가 갑자기 열몇 개 파일로 돌진하는 걸 지켜볼 일이 없어요. 계획 워크플로를 더 깊이 알고 싶다면 초보자를 위한 첫 10단계를 보세요.
- 프롬프트에 컨텍스트를 더하는 @멘션:
@file#5-10(5~10번째 줄만),@folder/(폴더 전체),@terminal:name(터미널 출력 가져오기),@browser(Chrome 제어). 복사·붙여넣기 대신 Claude가 봐야 할 것을 곧장 가리키는 거예요. 예를 들어 디버깅할 때@file#40-72를 쓰면 천 줄짜리 파일을 읽히는 대신 고장 난 함수에만 Claude를 집중시켜요 - 더 정확하고 토큰도 아껴요. - 체크포인트 / 되감기: Claude가 엉뚱한 방향으로 가면 파일 변경을 이전 상태로 되돌릴 수 있어요 -
git stash나 한 단계씩 하는 Ctrl+Z에 전적으로 기대지 않아도 되는 안전망이에요. - 세션 기록 + 여러 탭: 여러 세션을 동시에 실행하고 지난 대화를 다시 볼 수 있어, 여러 갈래를 오갈 때 편해요 - 한 탭은 리팩터링 중, 다른 탭은 간단한 API 질문용으로요.
- 권한 모드: 프롬프트 상자 바로 거기서 Manual(각 동작을 손으로 승인), Plan(계획만), 또는 자동 편집을 골라요. 낯선 저장소에서는 신중하게 두고, 신뢰가 생기면 느슨하게 풀어요. 설정의
initialPermissionMode로 기본값을 미리 지정할 수 있어요.
VS Code에서의 Claude Code 키보드 단축키
대부분의 가이드가 빼놓는 전체 단축키 표(공식 문서에서)는 다음과 같아요:
| 동작 | macOS | Windows / Linux |
|---|---|---|
| 에디터와 Claude 사이에서 포커스 전환(Focus Input) | Cmd+Esc | Ctrl+Esc |
| 새 탭에서 Claude 열기 | Cmd+Shift+Esc | Ctrl+Shift+Esc |
| 선택한 줄로 @멘션 삽입 | Option+K | Alt+K |
| Focus 뷰 토글 | Ctrl+Option+F | Ctrl+Alt+F |
| 마지막으로 닫은 세션 다시 열기 | Cmd+Shift+T | Ctrl+Shift+T |
| 프롬프트 상자에서 줄 바꿈 | Shift+Enter | Shift+Enter |
하나 잊었나요? 커맨드 팔레트(Ctrl/Cmd+Shift+P)를 열고 'Claude Code'라고 입력하면 모든 명령을 볼 수 있어요. 인쇄해서 볼 수 있는 총정리는 Claude Code 치트시트를 보세요.
VS Code에서 Claude Code를 최대한 활용하는 팁
설치는 누구나 할 수 있지만, 매끄럽게 굴리려면 요령이 조금 필요해요. 제가 매일 쓰는 것들이에요:
- 패널을 보조 사이드바로 옮기기: Claude가 에디터를 가리지 않고 코드 옆에 자리하도록요. Spark 아이콘을 오른쪽 끝으로 드래그하기만 하면 돼요 - diff와 코드를 한눈에 보니 훨씬 편해요.
- '프로젝트 기억'으로 CLAUDE.md 쓰기: 품질을 가장 크게 끌어올리는 하나예요. 규칙, 스택, 테스트 명령을 이 파일에 담아 두면 Claude가 추측하지 않아도 돼요. 탄탄한 CLAUDE.md 쓰는 법을 보세요.
- 에러를 복사·붙여넣지 말고
@terminal쓰기: 실패한 명령을 통합 터미널에서 실행한 다음@terminal로 출력 전체를 프롬프트에 넣어요 - 손으로 붙여넣는 것보다 빠르고 컨텍스트도 풍부해요. useTerminal토글: CLI 느낌이 좋으면 설정에서 켜고, 순수한 GUI를 원하면 꺼요.autosave와respectGitIgnore고려: diff를 깔끔하게 유지하고, Claude가 쓸모없거나 민감한 파일을 실수로 읽지 않도록요.- 비용 추적:
/usage로 소비량을 확인하고, 채팅이 가득 차면/compact로 컨텍스트를 압축해요 - Claude의 집중을 유지하고 토큰을 아껴요. - 상태 표시줄 깔끔하게 유지: 커스터마이즈해서 현재 모델과 비용을 한눈에 보세요 - 상태 표시줄 커스터마이즈 가이드를 보세요.
들일 만한 습관 하나: 큰 작업을 맡기기 전에 30초를 들여 목표와 제약을 프롬프트에 적어 두고(또는 CLAUDE.md에 남기고), 편집을 시키기 전에 플랜 모드를 켜서 방향을 검토하세요. 한 박자 더 들지만 Claude가 목표에서 벗어나는 빈도를 뚝 떨어뜨려 되감기 수고를 덜어 줘요. 큰 저장소에서는 프로젝트 전체를 통째로 던지지 말고 작업 중인 모듈에 @folder/를 함께 쓰세요 - Claude가 집중을 유지하고, 출력이 깔끔하며, 토큰도 덜 들어요.
확장과 CLI - 무엇을 써야 할까요?
흔한 질문: 확장이 있으면 CLI가 여전히 필요할까요? 간단히 비교해 볼게요:
| 기준 | 확장(VS Code 내) | CLI(터미널의 claude) |
|---|---|---|
| 인터페이스 | 시각적 GUI: diff, 플랜, 체크포인트 | 순수한 커맨드 라인 |
| 명령 집합 | 패널에는 충분 | 가장 완전: !로 bash 실행, 탭 자동완성, 모든 명령 |
claude를 PATH에 추가 | 아니요(확장은 패널용 자체 CLI를 동봉) | 별도 설치 필요 |
중요한 참고: 확장은 claude 명령을 PATH에 추가하지 않아요. 그래서 통합 터미널에서 claude를 입력하려면 단독 CLI를 따로 설치해야 해요. 실용적인 조언: 둘 다 쓰세요 - diff와 계획 검토에는 GUI, 빠른 동작에는 CLI. 둘은 같은 기록을 공유하니 claude --resume으로 세션을 이어서 열 수 있어요. CLI 전체 설치 세부 사항은 Claude Code 전체 설치 가이드에 있어요.
흔한 문제와 해결 방법
자주 겪는 몇 가지 문제와 빠른 해결책이에요:
- macOS Tahoe에서
Cmd+Esc가 안 될 때: 그 단축키는 흔히 Game Overlay가 가로채요.System Settings -> Keyboard -> Keyboard Shortcuts -> Game Controllers로 가서 그걸 차지한 항목의 체크를 해제하거나, VS Code의 키보드 단축키에서Claude Code: Focus input을 다른 조합으로 다시 지정하세요. - Spark 아이콘 ✱이 없을 때: 순서대로 확인하세요 - 파일을 최소 하나 열었나요? VS Code가
>= 1.94.0인가요?Reload Window(커맨드 팔레트)를 시도하고, 충돌하는 다른 AI 확장을 잠시 비활성화하고, 프로젝트 폴더에 workspace trust를 활성화하세요. - 'Please run /login':
Reload Window를 시도하거나, VS Code를 닫고 터미널에서code .로 프로젝트를 다시 열어 올바른 로그인 세션을 잡게 하세요. - Claude가 응답하지 않을 때: 네트워크를 확인하고, 새 세션을 열거나, CLI를 시도해 문제가 확장 쪽인지 계정 쪽인지 좁혀 보세요. 채팅이 아주 길어졌다면
/compact로 컨텍스트를 압축하고 다시 시도하세요. - diff가 안 나타나거나 엉뚱한 곳에 적용될 때: 파일이 저장돼 있고 다른 확장(저장 시 도는 포매터)에 덮어써지지 않는지 확인하세요.
autosave를 통제해서 쓰고, 큰 diff를 검토하는 동안에는 format-on-save를 잠시 꺼 두세요.
이 목록에 없는 문제를 만났나요? 흔한 Claude Code 오류와 해결 방법 총정리를 보세요.
미리 만들어진 skill과 subagent로 레벨 업
확장은 Claude Code에 skill, subagent, 워크플로 세트가 처음부터 갖춰져 있으면(직접 하나씩 만드는 대신) 훨씬 강해져요. 빠르게 가고 싶다면 한 가지 선택지가 Claude Code용 AgentKit 키트예요 - 개발과 마케팅 작업을 위한 skill과 agent를 묶은 패키지로, AgentKit을 한번 써 보고(링크로 20% 할인) 자기 워크플로에 맞는지 확인할 수 있어요. 필수는 아니에요: 순정 확장만으로도 충분하고, 키트는 더 빨리 가기 위한 선택적 수단일 뿐이에요.
자주 묻는 질문(FAQ)
VS Code의 Claude Code는 무료인가요?
아니요. 확장 설치는 무료지만, 사용하려면 유료 Claude 플랜(Pro, Max, Team, Enterprise)이나 Claude Console 접근이 필요해요. 무료 등급은 없고 API 키로는 쓸 수 없어요.
Pro 플랜이 필요한가요?
유료 플랜이 최소 하나는 필요하고, 개인이 쓸 수 있는 가장 낮은 등급이 Pro예요. Max는 많이 쓰는 경우에 맞고, Team과 Enterprise는 그룹용이에요.
'Claude AI' 확장이나 Cline, Continue와는 어떻게 다른가요?
'Claude Code' 확장은 Anthropic 공식 빌드(publisher anthropic.claude-code)로, Claude 계정에 연결된 diff 리뷰, 플랜 모드, 체크포인트, @멘션을 갖췄어요. 예전 'Claude AI' 채팅이나 Cline, Continue 같은 확장은 동작과 사용감이 다른 별개의 제품이에요.
Cursor에서 쓸 수 있나요?
네. Claude Code 확장은 VS Code와 같은 단계로 Cursor, Kiro, Open VSX 기반 에디터에 설치돼요.
CLI를 따로 설치해야 하나요?
꼭 그렇진 않아요. 확장은 이미 패널용 CLI를 동봉하고 있어요. 통합 터미널에서 claude 명령을 입력하고 싶을 때만 단독 CLI가 필요한데, 확장이 claude를 PATH에 추가하지 않기 때문이에요.
Windows/WSL에서 작동하나요?
네. 확장은 Windows, macOS, Linux에서 동작해요. WSL이라면 평소처럼 VS Code의 WSL 모드로 프로젝트를 열고 Claude Code 패널을 쓰세요.
마무리와 다음 단계
이렇게 VS Code 안에서 바로 도는 Claude Code예요: 공식 확장을 설치하고, 유료 플랜으로 로그인한 다음, diff/플랜/체크포인트, @멘션, 그리고 단축키를 활용해 더 빠르게 코딩하세요. 다음 단계: 이제 막 시작한다면 초보자를 위한 첫 10단계를, 커맨드 라인도 원한다면 Claude Code CLI 전체 설치 가이드를 보세요. 즐거운 코딩 되세요.