VSCode에서 Claude Code 쓰는 법 — 설치부터 실전 워크플로우까지 한 방에 정리

Copilot 쓰다가 Claude Code로 갈아탄 지 몇 달 됐다. 솔직히 처음에는 "터미널에서 AI를 쓴다고?" 하면서 좀 회의적이었는데, 한번 써보니까 차원이 다르더라. 코드 한 줄 자동완성하는 수준이 아니라, 프로젝트 전체 구조를 이해하고 여러 파일을 동시에 수정해준다. 리팩토링 시켜보면 진짜 소름 돋는다.
근데 설치 과정에서 좀 헤매는 사람이 많은 것 같다. 나도 처음에 Node.js 버전 때문에 삽질했었고. 그래서 VSCode에서 Claude Code 쓰는 방법을 처음부터 끝까지 정리해봤다.

---

Claude Code가 뭔데

먼저 개념 정리부터. Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트다. Copilot이나 Cursor 같은 에디터 내장 자동완성 도구와는 성격이 다르다.

차이를 비교하면:

• Copilot/Cursor: 에디터 안에서 커서 위치의 코드를 자동완성. 한 파일 내에서 동작.
• Claude Code: 프로젝트 전체를 읽고, 여러 파일을 동시에 수정하고, 쉘 명령어도 실행하고, Git 커밋까지 한다. 에이전트라는 표현이 맞다.

VSCode 확장 프로그램을 설치하면 이 터미널 에이전트를 GUI로 편하게 쓸 수 있다. 인라인 diff로 변경사항을 확인하고, 수락/거부를 클릭 한 번으로 할 수 있고, 체크포인트로 되감기도 가능하다.

---

설치 전 준비물

Claude Code를 쓰려면 몇 가지가 필요하다.

1. Node.js (v18 이상)

Claude Code는 npm으로 설치하기 때문에 Node.js가 필요하다. LTS 버전(현재 v22)을 권장한다.

# 버전 확인
node -v
# v22.x.x 이상이면 OK

npm -v
# 10.x.x 이상이면 OK

Node.js가 없거나 버전이 낮으면 설치/업데이트하자.

# macOS (Homebrew)
brew install node

# 또는 nvm으로 버전 관리 (추천)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

Windows는 Node.js 공식 사이트에서 설치 파일을 다운로드하면 된다. WSL을 쓰고 있다면 WSL 안에서 설치하는 게 좋다.

2. Anthropic 유료 계정

이게 중요한데, Claude Code는 무료 플랜에서 사용할 수 없다. 최소 Pro 구독($20/월) 이상이 필요하다.

Pro ($20/월)       — 일일 사용량 제한 있지만 일반적인 코딩 세션은 충분
Max ($100/월)      — 전문 개발자 일일 작업량 커버
Max ($200/월)      — 대규모 자율 작업, 팀 공유 워크플로우
Team ($30/유저/월)  — 팀 단위 사용
Enterprise         — 기업용
API 크레딧          — 종량제도 가능

처음이면 Pro로 시작해서, 사용량 제한에 자주 걸리면 Max로 올리는 게 합리적이다.

3. 운영체제

• macOS 13.0 (Ventura) 이상
• Ubuntu 20.04+ / Debian 10+
• Windows 10 (1809+) + WSL

Windows에서는 WSL(Windows Subsystem for Linux) 환경에서 돌려야 한다. 네이티브 Windows 터미널에서는 안 된다.

---

Step 1: Claude Code CLI 설치

VSCode 확장 프로그램은 CLI 위에서 돌아간다. CLI가 먼저 설치돼 있어야 한다.

방법 A: Native 설치 (권장)

2026년 기준 Anthropic이 공식 권장하는 방법이다.

# macOS / Linux
curl -fsSL https://cli.claude.ai/install.sh | sh

# 설치 확인
claude --version

방법 B: npm으로 설치

npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

npm 설치 시 macOS/Linux에서 권한 에러가 나면, sudo를 쓰지 말고 npm 경로를 사용자 디렉토리로 바꾸자:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# 위 export를 ~/.zshrc 또는 ~/.bashrc에 추가해두자
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

첫 로그인

# 프로젝트 폴더로 이동
cd ~/my-project

# Claude Code 실행
claude

# 처음 실행하면 브라우저가 열리면서 Anthropic 로그인 화면이 뜬다
# 로그인하면 인증 완료

여기까지 하면 터미널에서 Claude Code를 쓸 수 있다. 근데 우리의 목표는 VSCode에서 쓰는 거니까 계속 가보자.

---

Step 2: VSCode 확장 프로그램 설치

설치

1. VSCode 열기
2. Cmd+Shift+X (Mac) 또는 Ctrl+Shift+X (Windows/Linux)로 확장 프로그램 탭 열기
3. "Claude Code" 검색
4. Anthropic이 배포한 공식 확장 프로그램의 [Install] 클릭

설치 후 확장 프로그램이 안 보이면 VSCode를 재시작하거나, 명령 팔레트(Cmd+Shift+P)에서 Developer: Reload Window를 실행하자.

💡 참고: VSCode 1.98.0 이상이 필요하다. 오래된 버전이면 업데이트부터 하자.

확장 프로그램 열기

Claude Code를 여는 방법이 여러 가지 있다:

• Spark 아이콘: 파일을 열어놓은 상태에서 에디터 오른쪽 위 툴바의 불꽃 모양 아이콘 클릭
• 명령 팔레트: Cmd+Shift+P → "Claude Code: Open" 입력
• 활동 표시줄: 왼쪽 사이드바의 Spark 아이콘 클릭 (세션 목록 열림)
• 상태 바: 하단 상태 바의 "✱ Claude Code" 클릭

처음 열면 로그인 창이 뜬다. CLI에서 이미 로그인했으면 자동으로 인증이 잡힐 수도 있다.

⚠️ Spark 아이콘이 안 보이면? 파일이 하나도 열려있지 않으면 아이콘이 안 나타난다. 파일을 하나 열어보자. 그래도 안 보이면 다른 AI 확장 프로그램(Copilot 등)과 충돌일 수 있으니, 명령 팔레트나 상태 바로 우회하면 된다.

---

Step 3: 기본 사용법

자연어로 코드 작성 요청

Claude Code 패널이 열리면 프롬프트 입력창에 자연어로 요청하면 된다.

# 이런 식으로 요청
"이 프로젝트에 로그인 API를 추가해줘. JWT 인증 방식으로."

"src/utils/helpers.ts 파일의 날짜 포맷 함수를 리팩토링해줘. dayjs 쓰지 말고 네이티브 Intl API로."

"현재 프로젝트의 전체 구조를 분석하고, 개선할 점을 알려줘."

"이 에러 로그를 분석해줘: [에러 메시지 붙여넣기]"

Claude가 변경사항을 제안하면 인라인 diff로 보여준다. 하이라이트된 부분을 확인하고 수락(Accept)하면 코드가 실제로 적용된다.

@-멘션으로 파일 참조

특정 파일이나 폴더를 직접 지정해서 맥락을 줄 수 있다. 이게 정말 유용하다.

@src/controllers/auth.ts 이 파일의 에러 핸들링을 개선해줘

@src/models/ 이 폴더의 모든 모델에 타입스크립트 타입을 추가해줘

@package.json 사용하지 않는 의존성을 찾아줘

에디터에서 코드 범위를 드래그해서 선택한 뒤 Claude에게 보내는 것도 가능하다:

1. 에디터에서 코드 블록 선택 (드래그)
2. Claude Code 프롬프트에서 @로 참조
3. "선택한 코드를 async/await 방식으로 바꿔줘" 요청

여러 대화 동시에 열기

탭을 여러 개 열어서 각각 다른 작업을 시킬 수 있다. 예를 들어:

• 탭 1: 프론트엔드 컴포넌트 작업
• 탭 2: 백엔드 API 작업
• 탭 3: 테스트 코드 작성

명령 팔레트에서 "Claude Code: Open in New Tab"을 선택하면 새 탭이 열린다. 맥락이 분리되니까 작업별로 나눠서 쓰는 게 효율적이다.

---

실전 워크플로우

워크플로우 1: 코드 리뷰 + 리팩토링

이게 내가 제일 많이 쓰는 패턴이다.

1. 작업할 파일을 에디터에서 연다
2. Claude Code에 요청: "@src/services/payment.ts 이 파일을 리뷰해줘. 보안 이슈, 성능 문제, 코드 스타일 개선점을 찾아줘"
3. Claude가 분석 결과를 보여줌
4. "3번 이슈를 수정해줘" 같은 식으로 후속 요청
5. diff 확인 후 수락

워크플로우 2: 테스트 코드 생성

"@src/utils/calculator.ts 이 파일에 대한 단위 테스트를 Jest로 작성해줘. 엣지 케이스도 포함해서."

이러면 테스트 파일을 새로 만들어주고, 일반 케이스 + 엣지 케이스까지 커버하는 테스트를 작성해준다. 물론 그대로 쓰면 안 되고 검토는 해야 하지만, 빈 파일에서 시작하는 것보다 열 배는 빠르다.

워크플로우 3: 버그 디버깅

"앱을 실행하면 TypeError: Cannot read property 'map' of undefined 에러가 나. 
@src/components/UserList.tsx 여기서 발생하는 것 같은데, 원인이랑 수정 방법 알려줘."

Claude가 코드를 분석해서 원인을 찾아주고, 수정 코드를 제안한다. API 응답이 null일 때의 방어 코드가 없다든지, 비동기 처리에서 초기값을 안 넣었다든지.

워크플로우 4: Git 작업 자동화

Claude Code는 Git도 다룰 수 있다. 이건 터미널 모드에서 더 강력하다.

"지금까지 변경한 내용으로 커밋해줘. 커밋 메시지는 conventional commit 형식으로."

"이 브랜치의 변경사항을 요약해서 PR 설명 초안을 만들어줘."

---

Plan Mode — 실행 전에 계획 먼저 확인

Claude에게 큰 작업을 시킬 때는 Plan Mode를 쓰는 게 좋다. Claude가 바로 코드를 수정하는 게 아니라, 먼저 "이런 식으로 할 거다"라는 계획을 보여준다. 계획을 검토하고 수정한 뒤에 실행을 승인하는 방식.

"이 프로젝트를 Express에서 Fastify로 마이그레이션해줘" (Plan Mode)

→ Claude의 계획:
1. package.json에서 express 제거, fastify 추가
2. src/app.ts 라우팅 구조 변경
3. 미들웨어를 Fastify 플러그인으로 교체
4. 에러 핸들링 수정
5. 테스트 코드 업데이트

→ "2번에서 라우팅은 기존 구조 유지하면서 해줘"처럼 수정 가능
→ 승인하면 실행

큰 변경을 할 때 이 과정 없이 바로 실행하면 의도와 다르게 갈 수 있다. Plan Mode는 습관처럼 쓰자.

---

Checkpoints — 되감기 기능

Claude가 여러 파일을 수정했는데, 결과가 마음에 안 들 때가 있다. 이때 Checkpoint로 되감을 수 있다.
Claude가 작업할 때 자동으로 체크포인트를 만들어두니까, 특정 시점으로 돌아가는 게 가능하다. Git stash나 undo보다 편하다. "아까 그 상태로 돌아가줘"가 된다는 거다.

---

CLAUDE.md — 프로젝트별 지시사항

프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude가 해당 프로젝트에서 항상 참고하는 지시사항이 된다.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 Next.js 14 + TypeScript + Prisma + PostgreSQL 기반 이커머스 플랫폼입니다.

## 코딩 컨벤션
- 함수명은 camelCase
- 컴포넌트명은 PascalCase
- CSS는 Tailwind CSS만 사용 (styled-components 사용 금지)
- API 응답은 항상 { success: boolean, data?: T, error?: string } 형태

## 중요 사항
- DB 마이그레이션은 Prisma Migrate 사용
- 환경변수는 .env.local에서 관리
- 테스트는 Vitest 사용
- 절대 console.log를 프로덕션 코드에 남기지 말 것

이걸 써두면 매번 "Tailwind CSS로 해줘", "Prisma 쓰고 있어" 같은 걸 반복하지 않아도 된다. 팀원들이 같은 CLAUDE.md를 공유하면 모두가 동일한 컨텍스트에서 Claude를 쓸 수 있다.

---

터미널 모드 vs 확장 프로그램 모드

VSCode 안에서 Claude Code를 쓰는 방법이 두 가지다:

확장 프로그램 (GUI)

• Spark 아이콘으로 패널 열기
• 인라인 diff로 변경사항 확인
• 마우스 클릭으로 수락/거부
• 체크포인트 시각적 관리
• @-멘션으로 파일 참조

터미널에서 직접 실행

# VSCode 내장 터미널에서
# Ctrl+` 로 터미널 열고
claude

같은 모델, 같은 인증을 쓴다. 기능적으로 동일한데, 터미널이 더 빠르게 느껴지는 경우가 있다. 복잡한 쉘 명령어나 스크립트 실행이 필요한 작업은 터미널이 편하고, 코드 수정이 주인 작업은 확장 프로그램이 편하다.
나는 보통 이렇게 쓴다:

• 확장 프로그램: 코드 리뷰, 리팩토링, 컴포넌트 작성 같은 에디터 중심 작업
• 터미널: 프로젝트 초기 세팅, 대규모 마이그레이션, Git 작업, 스크립트 실행

---

자주 쓰는 단축키

Cmd+Shift+P → "Claude Code"    — 명령 팔레트에서 Claude 관련 명령 검색
Cmd+Shift+P → "Open in New Tab" — 새 탭에서 Claude 열기
Cmd+N (Claude 패널에서)          — 새 대화 시작
Ctrl+`                          — 터미널 열기 (터미널 모드 사용 시)

---

자주 겪는 문제와 해결법

"claude: command not found"

CLI가 설치 안 됐거나 PATH에 안 잡힌 거다.

# PATH 확인
which claude

# 안 나오면 다시 설치
npm install -g @anthropic-ai/claude-code

# npm 글로벌 경로 확인
npm config get prefix
# 이 경로/bin이 PATH에 있어야 함

확장 프로그램에서 Claude가 안 뜸

1. CLI가 설치돼 있는지 확인 (claude --version)
2. VSCode 버전 확인 (1.98.0 이상)
3. 확장 프로그램 재설치
4. Developer: Reload Window 실행
5. Restricted Mode인지 확인 (좌하단에 표시됨)

인증 문제

# 인증 상태 확인
claude auth status

# 재인증
claude auth login

# 그래도 안 되면 credentials 삭제 후 재인증
rm ~/.claude/credentials.json
claude auth login

Windows에서 안 됨

Claude Code는 Windows 네이티브를 지원하지 않는다. WSL 환경에서 써야 한다.

# WSL 설치 (PowerShell 관리자 모드)
wsl --install

# WSL 안에서 Node.js + Claude Code 설치
# (위의 설치 과정과 동일)

VSCode의 WSL 확장 프로그램을 설치하면 VSCode에서 WSL 환경을 바로 쓸 수 있다. Ctrl+Shift+P → "WSL: Connect to WSL"로 연결하면 된다.

---

Copilot이랑 같이 쓸 수 있나?

쓸 수 있다. 충돌 안 한다. 나도 둘 다 켜놓고 쓰고 있다.
역할 분담이 꽤 자연스럽다:

• Copilot: 타이핑하는 중에 한 줄, 두 줄 자동완성. 단순 반복 코드 빠르게 채우기.
• Claude Code: "이 모듈 전체를 리팩토링해줘", "테스트 파일 만들어줘", "이 에러 분석해줘" 같은 대규모 작업.

자동완성은 Copilot이 처리하고, 맥락이 필요한 큰 작업은 Claude Code에게 맡기는 식. 실제로 이 조합이 꽤 좋다.

---

비용 관련

Claude Code 자체는 무료다. 비용은 Anthropic 구독료에 포함돼 있다.
Pro($20/월)로 시작하면 하루에 코딩 세션 몇 시간 정도는 커버된다. 나는 처음에 Pro로 쓰다가 "일일 사용량 한도에 도달했습니다" 메시지를 일주일에 두세 번 이상 보게 되면서 Max로 올렸다.
API 크레딧 방식으로 종량제로 쓸 수도 있는데, 코딩 에이전트 특성상 컨텍스트 윈도우를 많이 쓰기 때문에 생각보다 비용이 빠르게 늘 수 있다. 월정액이 마음 편하다.

---

마무리

VSCode에서 Claude Code를 쓰는 과정을 정리하면:

1. Node.js 설치 (v18 이상, v22 LTS 권장)
2. Claude Code CLI 설치 (native 또는 npm)
3. VSCode 확장 프로그램 설치 (마켓플레이스에서 "Claude Code" 검색)
4. 로그인 (Anthropic 유료 계정 필요)
5. Spark 아이콘 클릭해서 사용 시작

핵심 팁:

• @-멘션으로 파일을 직접 지정하면 정확도가 올라간다
• 큰 작업은 Plan Mode로 계획 먼저 확인하자
• CLAUDE.md에 프로젝트 컨벤션을 써두면 매번 반복 설명할 필요 없다
• Copilot과 같이 쓸 수 있다. 역할이 다르니까 충돌 없다
• 코드 수정 작업은 확장 프로그램, 쉘 작업은 터미널 모드가 편하다
• Pro로 시작해서 한도에 자주 걸리면 Max로 올리자