Windows에서 Claude Code 설치하고 IntelliJ와 연동하기

LV2.생존자 2025. 6. 24. 08:39

Claude Code는 Anthropic에서 개발한 agentic 코딩 도구로, 터미널에서 자연어로 코딩 작업을 수행할 수 있게 해 준다.

원래는 Max 구독($100/월) 사용 가능했지만, 최근 Pro 구독($20/월)에서도 사용할 수 있게 되어 설치를 해보았다.

Windows에서 직접 설치하는 방법과 발생한 문제를 해결한 방법에 대해 공유하고자 한다.

1. 설치 환경 확인

Claude Code는 macOS와 Linux에서 공식 지원되며, Windows에서는 WSL2를 통해서만 사용할 수 있다.

먼저 Windows에서 직접 설치를 시도했다.

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

cmd에서 위 명령어 실행 시 다음과 같이 에러가 발생했다

npm error Error: Claude Code is not supported on Windows.
npm error Claude Code requires macOS or Linux to run properly.

이 에러를 통해 WSL2 환경 구축이 필요함을 확인했다.

2. WSL2 설치

Windows에서 Linux 환경을 사용하기 위해 WSL2를 설치했다.

PowerShell을 관리자 권한으로 실행하여 다음 명령어를 입력했다.

wsl --list

실행 시 사용법만 표시되고 설치된 배포판이 없었다.

해결 방법

PowerShell을 관리자 권한으로 실행하여 Ubuntu를 설치했다.

wsl --install -d Ubuntu-22.04

설치 중: 가상 머신 플랫폼
가상 머신 플랫폼이(가) 설치되었습니다.
설치 중: Linux용 Windows 하위 시스템
Linux용 Windows 하위 시스템이(가) 설치되었습니다.
설치 중: Ubuntu 22.04 LTS
Ubuntu 22.04 LTS이(가) 설치되었습니다.
요청한 작업이 잘 실행되었습니다. 시스템을 다시 시작하면 변경 사항이 적용됩니다.

설치 후 시스템 재시작이 필요했다.

3. 시스템을 재시작한 후 WSL2 실행

wsl --list --verbose

Linux용 Windows 하위 시스템 설치된 배포가 없습니다.

재시작 후에도 배포판이 인식되지 않았다. WSL 상태를 확인한 결과, 가상 머신 플랫폼이 제대로 활성화되지 않은 것을 발견했다.

해결 방법

wsl --status

WSL2는 현재 컴퓨터 구성에서 지원되지 않습니다.
"가상 머신 플랫폼" 선택적 구성 요소를 사용하도록 설정하고 BIOS에서 가상화가 사용하도록 설정되어 있는지 확인하세요.
실행하여 "가상 머신 플랫폼"을 사용하도록 설정: wsl.exe --install --no-distribution

에러 메시지에서 제시한 해결 방법을 적용했다.

wsl.exe --install --no-distribution

기능을 사용하도록 설정하는 중
[==========================100.0%==========================] 
The operation completed successfully.
요청한 작업이 잘 실행되었습니다. 시스템을 다시 시작하면 변경 사항이 적용됩니다.

다시 시스템을 재시작한 후 WSL2가 정상적으로 작동하는 것을 확인했다.

4. Ubuntu 초기 설정

재시작 후 Ubuntu가 정상적으로 설치되었고, 초기 사용자 설정을 진행했다

Ubuntu 22.04 LTS 시작하는 중...
Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
Enter new UNIX username: [이름]
Enter new UNIX password: [비밀번호]
Retype new UNIX password: [비밀번호 확인]

[이름]@DESKTOP-NJF3F27:~$

설정이 완료되면 Ubuntu 터미널 프롬프트가 표시된다.

5. Node.js 및 Claude Code 설치

Claude Code 설치를 위해 Node.js를 설치했다.

Node.js 설치

sudo apt update
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

node --version  # v20.19.2
npm --version   # 10.8.2

설치 완료 후 버전을 확인했다.

Claude Code 설치

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

Claude Code 설치 시 권한 에러가 발생했다.

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

npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@anthropic-ai'

sudo 권한으로 재시도했다.

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

설치가 성공적으로 완료되었다.

6. Claude Code 인증

Claude Code를 실행하여 인증을 진행했다.

claude

WSL2 환경에서는 브라우저가 자동으로 열리지 않아 인증 URL이 터미널에 표시되었다.

Browser didn't open? Use the url below to sign in:
https://claude.ai/oauth/authorize?code=true&client_id=...

제공된 URL을 Windows 브라우저에서 직접 열어 Claude Pro 계정으로 로그인하고, 인증 코드를 터미널에 입력했다.

7. 보안 확인 단계

인증 완료 후 보안 주의사항이 나타났다. Enter 키를 눌러 계속 진행했다.

Security notes:
1. Claude can make mistakes
2. Due to prompt injection risks, only use it with code you trust

Claude Code 실행 시 작업 폴더에 대한 신뢰 확인이 표시되었다. 1. Yes, proceed 를 선택하여 진행했다.

Do you trust the files in this folder?
/home/[이름]

8. IntelliJ 연동 설정

Windows PowerShell에서는 claude 명령어가 인식되지 않아, IntelliJ 터미널을 WSL2 환경으로 변경하여 해결했다.

IntelliJ 설정을 다음과 같이 변경했다

File → Settings → Tools → Terminal
Shell path: wsl.exe
Working directory: (비워두기)

이후 IntelliJ를 재시작하여 터미널이 자동으로 WSL2 환경에서 열리도록 설정했다.

9. 프로젝트 폴더 접근

WSL2에서 Windows 프로젝트 폴더에 접근할 때 경로 문제가 발생했다.

해결 방법

WSL2에서 Windows 프로젝트 폴더에 접근할 때는 마운트 경로를 사용해야 한다.

# Windows 경로: C:\dev\workspace\projectName\projectName-admin
# WSL2 경로: /mnt/c/dev/workspace/projectName/projectName-admin

cd "/mnt/c/dev/workspace/projectName/projectName-admin"

Claude Code는 보안상 원래 작업 디렉토리 외부로의 이동을 제한한다.

프로젝트 폴더 접근 시 다음과 같은 확인 메시지가 나타났다.

ERROR: cd to '/mnt/c/dev/workspace/projectName/projectName-admin' was blocked. 
For security, Claude Code may only change directories to child directories of the original working directory (/home/[이름]) for this session.

Do you want to proceed?
1. Yes
2. Yes, and add /mnt/c/dev/workspace/projectName/projectName-admin as a working directory for this session
3. No, and tell Claude what to do differently

2번 옵션을 선택하여 해당 디렉토리를 신뢰할 수 있는 작업 디렉토리로 추가했다.

10. 최종 확인

설정 완료 후 Claude Code가 프로젝트를 정상적으로 분석하는 것을 확인했다.

This looks like a Spring Boot Java web application for the ProjectName admin panel. 
It has a typical Maven/Gradle project structure with source code, resources, templates, 
and configuration files. The application appears to be for managing course data, 
users, events, coupons, and other administrative functions.

11. 개발 지침 설정

프로젝트 루트에 CLAUDE.md 파일을 생성하여 개발 규칙과 가이드라인을 설정했다. 이 파일에는 다음과 같은 내용을 포함했다.

Spring Boot 개발 패턴
코딩 컨벤션
신입 개발자를 위한 용어 설명
실무 중심의 개발 가이드라인
보안 및 성능 최적화 규칙

결론

Windows 환경에서 Claude Code를 사용하려면 WSL2를 통한 Linux 환경 구축이 필수다.
Claude Code를 Pro 버전으로 사용할 수 있다는 점이 큰 장점인 거 같다.
아직 신입 개발자이기 때문에 Claude Code에 의존하기 보다는, 경험 많은 시니어 개발자에게 조언을 구하는 느낌으로 활용하는 것이 좋을 것 같다고 생각한다.