Claude Code VS Code 설치 및 설정 완전 가이드 2026

VS Code는 전 세계 개발자들이 가장 많이 사용하는 코드 에디터이며, Claude Code와의 통합을 통해 AI 기반 개발의 핵심 허브로 진화하고 있습니다. 이 가이드에서는 Claude Code VS Code 확장을 설치하고 최적의 개발 환경을 구성하는 방법을 처음부터 끝까지 단계별로 안내합니다. 키보드 단축키 설정, 테마 커스터마이징, CLAUDE.md 파일 구성, MCP 서버 연결, 그리고 자주 발생하는 문제의 해결 방법까지 모두 다루고 있으므로, 이 글 하나만으로 VS Code에서 Claude Code를 완벽하게 활용할 수 있게 될 것입니다.

사전 요구 사항 확인

Claude Code VS Code 확장을 설치하기 전에 다음 사전 요구 사항을 확인해야 합니다. 하나라도 누락되면 설치 과정에서 문제가 발생할 수 있으므로 꼼꼼하게 체크하세요.

Node.js 및 npm

Claude Code는 Node.js 런타임에서 실행됩니다. Node.js 18.0 이상이 설치되어 있어야 하며, npm 9.0 이상이 함께 필요합니다. 터미널에서 다음 명령어로 현재 설치된 버전을 확인할 수 있습니다.

# Node.js 버전 확인
node --version
# 출력 예시: v20.12.2

# npm 버전 확인
npm --version
# 출력 예시: 10.5.0

Node.js가 설치되어 있지 않거나 버전이 낮은 경우, 공식 웹사이트(nodejs.org)에서 LTS 버전을 다운로드하거나 nvm(Node Version Manager)을 사용하여 설치하는 것을 권장합니다.

# nvm으로 Node.js 설치 (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
nvm use --lts

# Windows에서는 nvm-windows 사용
# https://github.com/coreybutler/nvm-windows

VS Code 버전

Claude Code 확장은 VS Code 1.85 이상에서 지원됩니다. VS Code 메뉴에서 Help > About을 클릭하여 현재 버전을 확인하세요. 최신 버전으로 업데이트하는 것을 강력히 권장합니다. VS Code Insiders 버전도 지원되며, 실제로 최신 기능을 먼저 체험하고 싶다면 Insiders 버전이 더 적합할 수 있습니다.

Anthropic API 키 또는 Claude 구독

Claude Code를 사용하려면 다음 중 하나가 필요합니다.

• Claude Pro/Team/Enterprise 구독: claude.ai에서 구독 중이라면 별도의 API 키 없이 OAuth 로그인으로 바로 사용할 수 있습니다.
• Anthropic API 키: API를 직접 사용하는 경우 console.anthropic.com에서 API 키를 발급받아야 합니다.

Step 1: Claude Code CLI 설치

VS Code 확장을 설치하기 전에 먼저 Claude Code CLI를 전역으로 설치합니다. CLI는 VS Code 확장의 기반이 되는 핵심 엔진이며, 터미널에서 독립적으로도 사용할 수 있습니다.

# Claude Code CLI 전역 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version
# 출력 예시: claude-code v2.1.0

# 첫 실행 및 인증
claude
# 브라우저가 열리며 Anthropic 계정으로 로그인

설치 중 권한 문제가 발생하면 다음을 시도하세요.

# macOS/Linux에서 권한 문제 해결
sudo npm install -g @anthropic-ai/claude-code

# 또는 npm 전역 디렉토리 권한 변경 (권장)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code

Step 2: VS Code 확장 설치

Claude Code CLI가 정상적으로 설치되었다면, 이제 VS Code 확장을 설치할 차례입니다.

방법 1: VS Code 마켓플레이스에서 설치

1. VS Code를 엽니다.
2. 사이드바에서 확장(Extensions) 아이콘을 클릭하거나 Ctrl+Shift+X (macOS: Cmd+Shift+X)를 누릅니다.
3. 검색창에 Claude Code를 입력합니다.
4. Anthropic이 배포한 공식 확장을 찾아 Install 버튼을 클릭합니다.
5. 설치가 완료되면 VS Code를 재시작합니다.

방법 2: 명령줄에서 설치

# VS Code 명령줄에서 확장 설치
code --install-extension anthropic.claude-code

# 설치 확인
code --list-extensions | grep claude

방법 3: CLI에서 자동 설치

# Claude Code CLI가 자동으로 VS Code 확장을 설치
claude ide install vscode

# VS Code Insiders에 설치하는 경우
claude ide install vscode-insiders

설치가 완료되면 VS Code 하단 상태바에 Claude Code 아이콘이 나타납니다. 이 아이콘을 클릭하면 Claude Code 패널이 열리며, 사이드바에서도 Claude 아이콘을 통해 접근할 수 있습니다.

Step 3: 인증 설정

확장 설치 후 처음 Claude Code를 실행하면 인증이 필요합니다. 두 가지 인증 방법을 지원합니다.

OAuth 로그인 (권장)

Claude Pro, Team, Enterprise 구독자는 OAuth 로그인을 사용하는 것이 가장 간편합니다.

1. VS Code에서 Claude Code 패널을 엽니다 (Ctrl+Shift+P > Claude: Open Panel).
2. "Sign in with Anthropic" 버튼을 클릭합니다.
3. 브라우저가 열리면 Anthropic 계정으로 로그인합니다.
4. 인증이 완료되면 VS Code로 자동 리다이렉트됩니다.

API 키 직접 입력

API 키를 직접 사용하는 경우 환경변수를 설정합니다.

# 환경변수로 API 키 설정
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# 또는 VS Code settings.json에서 설정
{
  "claude-code.apiKey": "${env:ANTHROPIC_API_KEY}"
}

Step 4: 키보드 단축키 설정

Claude Code를 효율적으로 사용하기 위해 키보드 단축키를 설정하는 것이 매우 중요합니다. 다음은 기본 제공되는 단축키와 추천 커스텀 단축키입니다.

기본 키보드 단축키

커스텀 단축키 추가

VS Code의 keybindings.json 파일에서 Claude Code 전용 단축키를 추가할 수 있습니다. Ctrl+Shift+P를 누르고 Preferences: Open Keyboard Shortcuts (JSON)을 선택하세요.

[
  {
    "key": "ctrl+shift+g",
    "command": "claude-code.generateTests",
    "when": "editorTextFocus"
  },
  {
    "key": "ctrl+shift+f",
    "command": "claude-code.fixError",
    "when": "editorTextFocus && editorHasErrors"
  },
  {
    "key": "ctrl+shift+d",
    "command": "claude-code.addDocstring",
    "when": "editorTextFocus"
  },
  {
    "key": "ctrl+shift+o",
    "command": "claude-code.optimizeCode",
    "when": "editorTextFocus && editorHasSelection"
  }
]

Step 5: 워크스페이스 설정

프로젝트별로 Claude Code의 동작을 세밀하게 제어하려면 워크스페이스 설정을 구성해야 합니다. VS Code의 .vscode/settings.json 파일에 Claude Code 관련 설정을 추가합니다.

{
  // Claude Code 기본 설정
  "claude-code.model": "opus-4",
  "claude-code.contextWindow": "1m",

  // 자동 컨텍스트 포함 설정
  "claude-code.autoContext": {
    "includeOpenFiles": true,
    "includeGitDiff": true,
    "includeTerminalOutput": true,
    "maxFiles": 50
  },

  // 코드 제안 설정
  "claude-code.suggestions": {
    "enabled": true,
    "triggerDelay": 500,
    "maxSuggestions": 3,
    "languages": ["typescript", "python", "javascript", "rust", "go"]
  },

  // 자동 저장 시 포맷팅
  "claude-code.formatOnSave": true,

  // 터미널 통합
  "claude-code.terminal": {
    "autoActivate": true,
    "shell": "default"
  }
}

멀티루트 워크스페이스 설정

여러 프로젝트 폴더를 하나의 VS Code 워크스페이스에서 관리하는 경우, 각 폴더별로 별도의 Claude Code 설정을 적용할 수 있습니다. .code-workspace 파일에서 폴더별 설정을 지정합니다.

{
  "folders": [
    {
      "path": "./frontend",
      "name": "Frontend"
    },
    {
      "path": "./backend",
      "name": "Backend"
    }
  ],
  "settings": {
    "claude-code.model": "opus-4"
  }
}

Step 6: CLAUDE.md 파일 설정

CLAUDE.md 파일은 Claude Code에게 프로젝트에 대한 핵심 정보를 전달하는 설정 파일입니다. 프로젝트 루트에 이 파일을 생성하면, Claude는 모든 대화에서 이 파일의 내용을 우선적으로 참조합니다. 잘 작성된 CLAUDE.md는 Claude의 응답 품질을 극적으로 향상시킵니다.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 React 18 + TypeScript 기반의 SaaS 대시보드입니다.
Vite를 번들러로 사용하며, TanStack Query로 서버 상태를 관리합니다.

## 기술 스택
- **프론트엔드:** React 18, TypeScript 5.4, Tailwind CSS 4.0
- **상태 관리:** Zustand (클라이언트), TanStack Query (서버)
- **테스트:** Vitest, Testing Library, Playwright (E2E)
- **빌드:** Vite 6, pnpm

## 코딩 규칙
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 컴포넌트 파일은 PascalCase, 유틸리티는 camelCase
- 모든 컴포넌트에 TypeScript 인터페이스 정의 필수
- CSS는 Tailwind 유틸리티 클래스 사용 (인라인 스타일 금지)
- API 호출은 반드시 TanStack Query의 useQuery/useMutation 사용

## 프로젝트 구조
src/
├── components/    # 재사용 가능한 UI 컴포넌트
├── features/      # 기능별 모듈 (컴포넌트, 훅, API)
├── hooks/         # 공통 커스텀 훅
├── lib/           # 유틸리티 함수 및 설정
├── pages/         # 라우트 페이지 컴포넌트
└── types/         # 전역 TypeScript 타입 정의

## 자주 사용하는 명령어
- `pnpm dev` - 개발 서버 시작
- `pnpm build` - 프로덕션 빌드
- `pnpm test` - 유닛 테스트 실행
- `pnpm test:e2e` - E2E 테스트 실행
- `pnpm lint` - 린트 검사

CLAUDE.md에 대한 더 자세한 작성 팁은 시작하기 가이드에서 확인할 수 있습니다.

Step 7: MCP 서버 연결

VS Code에서 MCP 서버를 연결하면 Claude Code가 데이터베이스, 외부 API, 클라우드 서비스 등에 직접 접근할 수 있게 됩니다. 프로젝트 루트에 .mcp.json 파일을 생성하여 MCP 서버를 설정합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "--root", "."]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

VS Code에서 MCP 서버의 상태를 확인하려면 Claude Code 패널 하단의 "MCP Servers" 섹션을 확인하세요. 연결된 서버는 녹색 점으로, 연결 실패한 서버는 빨간색 점으로 표시됩니다. MCP 서버 설정에 대한 심층 가이드는 MCP 완전 가이드를 참고하세요.

테마 및 외관 설정

Claude Code VS Code 확장은 에디터의 테마에 맞추어 자동으로 색상을 조정합니다. 하지만 Claude Code 패널의 외관을 별도로 커스터마이징할 수도 있습니다.

Claude Code 테마 옵션

{
  // Claude Code 패널 테마 설정
  "claude-code.theme": {
    "mode": "auto",           // "auto" | "dark" | "light"
    "accentColor": "#7C6AF5", // 강조 색상 (기본: 바이올렛)
    "fontSize": 14,           // 채팅 폰트 크기
    "fontFamily": "Pretendard, sans-serif",
    "codeFont": "JetBrains Mono, monospace",
    "codeFontSize": 13
  },

  // 코드 블록 구문 강조 테마
  "claude-code.syntaxTheme": "one-dark-pro",

  // Diff 뷰 색상
  "claude-code.diffColors": {
    "added": "rgba(0, 200, 83, 0.15)",
    "removed": "rgba(255, 82, 82, 0.15)"
  }
}

실전 활용 워크플로우

VS Code에서 Claude Code를 설치하고 설정했다면, 이제 실제 개발 워크플로우에서 어떻게 활용하는지 살펴보겠습니다.

코드 작성 중 실시간 지원

코드를 작성하는 동안 Claude는 실시간으로 컨텍스트를 분석하고 지능적인 코드 완성을 제공합니다. 단순한 자동완성을 넘어 현재 작성 중인 함수의 의도를 파악하고, 프로젝트의 코딩 규칙에 맞는 완성된 구현을 제안합니다.

// 함수 시그니처만 작성하면 Claude가 전체 구현을 제안합니다
async function fetchUserOrders(userId: string): Promise<Order[]> {
  // Claude의 제안 (Tab으로 수락):
  const { data, error } = await supabase
    .from('orders')
    .select('*, order_items(*)')
    .eq('user_id', userId)
    .order('created_at', { ascending: false });

  if (error) {
    throw new DatabaseError('주문 조회 실패', { cause: error });
  }

  return data.map(transformOrderResponse);
}

에러 즉시 해결

VS Code에서 에러가 발생하면 Claude Code가 해당 에러를 감지하고 자동으로 수정 제안을 제공합니다. 에러가 표시된 줄에서 Ctrl+Shift+F (macOS: Cmd+Shift+F)를 누르면 Claude가 에러 원인을 분석하고 수정 코드를 제안합니다.

코드 리뷰 및 리팩토링

파일 전체 또는 선택한 코드 영역에 대해 즉시 코드 리뷰를 요청할 수 있습니다. Claude는 보안 취약점, 성능 이슈, 코드 스타일 문제, 잠재적 버그 등을 종합적으로 분석하여 구체적인 개선 사항을 제안합니다.

// 코드를 선택한 후 Ctrl+Shift+R로 리뷰 요청
// Claude의 리뷰 결과 예시:

// 1. [보안] SQL 인젝션 위험: 사용자 입력을 직접 쿼리에 포함하고 있습니다.
//    파라미터화된 쿼리를 사용하세요.
// 2. [성능] N+1 쿼리 문제: 루프 내에서 DB 쿼리를 실행하고 있습니다.
//    JOIN이나 배치 조회로 변경하세요.
// 3. [타입] userId가 any 타입입니다. string으로 명시적 타입을 지정하세요.

트러블슈팅: 자주 발생하는 문제와 해결 방법

Claude Code VS Code 확장을 사용하면서 발생할 수 있는 일반적인 문제와 해결 방법을 정리했습니다.

문제 1: 확장이 로드되지 않음

Claude Code 확장을 설치했지만 사이드바에 아이콘이 표시되지 않거나 패널이 열리지 않는 경우입니다.

# 해결 방법 1: VS Code 캐시 초기화
# VS Code 완전 종료 후:
rm -rf ~/.vscode/extensions/.cache
code

# 해결 방법 2: 확장 재설치
code --uninstall-extension anthropic.claude-code
code --install-extension anthropic.claude-code

# 해결 방법 3: Claude Code CLI 버전 확인
claude --version
# 오래된 버전이면 업데이트
npm update -g @anthropic-ai/claude-code

문제 2: 인증 실패

OAuth 로그인이 완료되었지만 VS Code에서 인증이 인식되지 않는 경우입니다.

# 해결 방법 1: 인증 상태 초기화
claude auth logout
claude auth login

# 해결 방법 2: VS Code에서 인증 정보 초기화
# Ctrl+Shift+P > "Claude: Reset Authentication"

# 해결 방법 3: 방화벽/프록시 확인
# 회사 네트워크에서는 프록시 설정이 필요할 수 있습니다
export HTTPS_PROXY=http://proxy.company.com:8080

문제 3: 코드 제안이 느리거나 나타나지 않음

인라인 코드 제안이 너무 느리거나 아예 나타나지 않는 경우입니다.

{
  // VS Code settings.json에서 제안 속도 조정
  "claude-code.suggestions": {
    "triggerDelay": 300,      // 기본 500ms에서 줄이기
    "debounceTime": 200,      // 입력 디바운스 시간
    "maxTokens": 500,         // 제안 최대 길이 제한
    "enabled": true
  },

  // 다른 자동완성 확장과 충돌하는 경우
  "editor.inlineSuggest.enabled": true,
  "editor.suggest.showInlineDetails": true
}

문제 4: MCP 서버 연결 실패

MCP 서버가 연결되지 않거나 빨간색 상태로 표시되는 경우입니다.

# MCP 서버 상태 확인
claude mcp status

# 특정 MCP 서버 로그 확인
claude mcp logs postgres

# 환경변수 확인
echo $DATABASE_URL

# MCP 서버 수동 재시작
claude mcp restart postgres

문제 5: 높은 메모리 사용량

대규모 프로젝트에서 Claude Code가 과도한 메모리를 사용하는 경우입니다.

{
  // 메모리 사용량 최적화 설정
  "claude-code.performance": {
    "maxContextFiles": 30,     // 동시 분석 파일 수 제한
    "indexingMode": "lazy",    // 필요할 때만 인덱싱
    "cacheSize": "256mb"       // 캐시 크기 제한
  },

  // 불필요한 파일 제외
  "claude-code.exclude": [
    "node_modules/**",
    "dist/**",
    ".git/**",
    "*.min.js",
    "package-lock.json"
  ]
}

추천 VS Code 확장 조합

Claude Code와 함께 사용하면 개발 생산성을 더욱 높일 수 있는 VS Code 확장들을 소개합니다.

고급 설정: 프로젝트별 최적화

프로젝트의 특성에 따라 Claude Code의 동작을 최적화하는 고급 설정을 소개합니다.

프론트엔드 프로젝트

{
  "claude-code.context": {
    "priorityFiles": [
      "tsconfig.json",
      "tailwind.config.ts",
      "vite.config.ts",
      "CLAUDE.md"
    ],
    "componentPatterns": ["src/components/**/*.tsx"],
    "stylePatterns": ["src/**/*.css"]
  }
}

백엔드 프로젝트

{
  "claude-code.context": {
    "priorityFiles": [
      "package.json",
      "prisma/schema.prisma",
      "src/routes/**/*.ts",
      "CLAUDE.md"
    ],
    "apiPatterns": ["src/routes/**/*.ts", "src/controllers/**/*.ts"],
    "schemaPatterns": ["prisma/**/*.prisma", "src/types/**/*.ts"]
  }
}

VS Code에서 Claude Code를 올바르게 설정하면, AI 없이 코딩하던 때로 돌아갈 수 없을 정도로 생산성이 향상됩니다. 처음 설정에 15분을 투자하면, 앞으로의 모든 코딩 시간에서 그 효과를 체감할 수 있습니다.

마무리: 다음 단계

이 가이드를 따라 VS Code에서 Claude Code를 성공적으로 설치하고 설정했다면, 이제 본격적으로 AI 기반 개발을 시작할 준비가 완료되었습니다. 다음 단계로 추천하는 리소스를 안내합니다.

• Claude Code 시작하기 가이드를 통해 기본 사용법을 익히세요.
• 명령어 레퍼런스에서 사용 가능한 모든 슬래시 명령어를 확인하세요.
• MCP 완전 가이드를 읽고 외부 도구 통합 방법을 배워보세요.
• MCP 서버 목록에서 프로젝트에 필요한 MCP 서버를 찾아보세요.

Claude Code는 지속적으로 업데이트되고 있으며, VS Code 확장 역시 정기적으로 새로운 기능이 추가됩니다. VS Code의 확장 자동 업데이트 기능을 활성화해 두면 항상 최신 기능을 사용할 수 있습니다. 설정이나 사용 중 궁금한 점이 있다면 Claude Korea 블로그에서 관련 가이드를 찾아보시거나, 커뮤니티에 질문을 남겨 주세요.

관련 리소스