Windows에서 Claude Code를 쓰면 명령어가 자꾸 에러를 낸다. 수정하고, 또 에러 나고, 또 수정하고. 같은 작업에 시간이 두 배로 들었다. 왜 그런지, 어떻게 해결했는지를 정리한다.
왜 에러가 나는가
Claude Code는 Linux 명령어를 쓴다. Claude Code만 그런 게 아니라, OpenAI Codex CLI, Aider 등 터미널 기반 AI 코딩 도구 대부분이 Linux 명령어를 기본으로 쓴다. AI 모델이 학습한 코드의 대부분이 Linux/Mac 환경 기준이기 때문이다.
Windows의 PowerShell은 문법이 다르다. 그래서 AI가 명령을 내릴 때마다 에러가 난다.
# AI가 이런 명령을 실행하면
rm -rf node_modules && npm install
# PowerShell은 이렇게 말한다
'rm'은(는) 인식할 수 없는 cmdlet입니다에러가 나면 AI가 수정하고, 또 에러가 나면 또 수정한다. 같은 작업에 시간이 두 배, 토큰도 두 배로 든다.
내가 거쳐온 단계
1단계: PowerShell (기본값의 함정)
VS Code를 설치하면 터미널이 PowerShell로 열린다. 아무것도 모르고 여기서 시작했다. 위에서 말한 에러가 계속 났다.
2단계: Git Bash (좀 나아졌다)
Git을 설치하면 Git Bash가 딸려온다. VS Code 터미널을 Git Bash로 바꿨다.
Linux 명령어가 대부분 동작한다. rm, cp, ls 같은 기본 명령이 먹히니까 Claude Code와의 소통이 훨씬 나아졌다.
하지만 완벽하진 않았다. 가끔 경로 문제가 나오고, 일부 도구가 제대로 안 돌아가는 경우가 있었다. "좀 나아졌다" 수준이지 "해결됐다"는 아니었다.
3단계: Claude에게 직접 물어봤다
Claude Code를 많이 쓰면서 어느 날 직접 물어봤다.
"Windows에서 너랑 작업하기에 가장 최적화된 환경이 뭐야?"답이 돌아왔다: WSL (Windows Subsystem for Linux).
Windows 안에 진짜 Linux를 깔아서 쓰는 거란다. 가짜 Linux 흉내가 아니라, 진짜 Ubuntu가 Windows 안에서 돌아간다.
WSL이 뭔가
쉽게 말하면, Windows 안에 Linux 방을 하나 만드는 것.
Windows (내 평소 환경)
└── WSL (Linux 방)
└── 여기서 Claude Code 실행VS Code가 이걸 자동으로 연결해준다. VS Code는 Windows에서 열리는데, 실제 작업은 Linux 방에서 일어난다. AI 코딩 도구가 내리는 모든 명령이 Linux에서 실행되니까 에러가 안 난다.
설치 과정
생각보다 간단했다.
1. WSL 설치
PowerShell을 관리자 모드로 열고 명령어 1줄.
wsl --installUbuntu가 기본으로 설치된다. 버전 선택이 나오면 Ubuntu 24.04 LTS를 선택하면 된다.
2. 재부팅
설치 후 재부팅이 필요하다.
3. Ubuntu 초기 설정
재부팅하면 Ubuntu 터미널이 자동으로 열린다. 사용자명과 비밀번호를 설정한다.
비밀번호 기준이 궁금할 텐데, Ubuntu는 최소 요구사항이 없다. 대문자, 특수문자 필수 아니다. sudo 명령할 때마다 입력하니까 짧고 외우기 쉬운 걸로 하면 된다.
4. VS Code에서 WSL 확장 설치
Extensions에서 "WSL" 검색 → Microsoft 공식 확장 설치. 다운로드 수 천만 단위인 그거다.
5. WSL 연결
VS Code 좌하단 >< 아이콘 → "Connect to WSL" 클릭.
창이 한 번 리로드되면서 확장들이 사라진 것처럼 보인다. 놀라지 마라. WSL 환경에 확장을 다시 설치하는 과정이다. Windows 쪽과 WSL 쪽은 별도 환경이라 확장도 각각 설치된다. 한 번만 하면 된다.
좌하단에 "WSL: Ubuntu" 가 표시되면 성공이다.
6. 기본 터미널 변경
매번 WSL 연결하기 귀찮으면, 기본 터미널을 바꾸면 된다.
Ctrl + Shift + P → "Terminal: Select Default Profile" → Ubuntu (WSL) 선택.
이후 터미널 열 때마다 자동으로 Ubuntu다.
하나 더: Claude Code 확장도 다시 설치
WSL 모드에서는 VS Code 확장이 Windows 쪽과 별도다. Claude Code 확장이 안 보이면 Extensions에서 "Install in WSL" 을 눌러주면 된다. WSL 확장과 Claude Code 확장은 역할이 다르다.
- WSL 확장: VS Code를 Linux 환경에 연결
- Claude Code 확장: VS Code 안에서 Claude Code 실행
둘 다 켜야 한다. 충돌 없다.
파일은 어디에 있는 건가
WSL을 켜면 파일이 두 곳에 존재한다.
C:\Users\내이름\→ Windows 파일\\wsl$\Ubuntu\home\내이름\→ Linux 파일 (WSL 가상 공간)
WSL은 가상으로 마운트된 공간이다. Windows 파일을 WSL에서 /mnt/c/로 접근할 수 있지만, 이 경로로 작업하면 느리다. 가상 공간을 거치는 경로가 길어지기 때문이다.
그래서 프로젝트를 WSL 네이티브 경로에 복사해서 쓰는 게 빠르다.
# WSL Ubuntu 터미널에서
mkdir -p ~/DEV
cp -r /mnt/c/Users/내이름/DEV/프로젝트명 ~/DEV/
# node_modules는 무거우니 재설치
cd ~/DEV/프로젝트명
rm -rf node_modules
npm install기존 프로젝트는 어떻게 하나
WSL을 깔고 나면 고민이 된다. "기존 프로젝트를 전부 WSL로 옮겨야 하나?"
안 옮겨도 된다. 기준은 간단하다:
- 기존 프로젝트: Windows에서 잘 돌아가면 그대로 유지
- 새 프로젝트: 처음부터 WSL에서 시작
VS Code를 두 모드로 쓰면 된다. Windows 모드와 WSL 모드를 프로젝트에 따라 왔다 갔다 하는 거다. 전부 옮기려다가 괜히 설정 꼬이는 것보다 훨씬 낫다.
체감 차이
| PowerShell | Git Bash | WSL | |
|---|---|---|---|
| Linux 명령어 | 대부분 안 됨 | 대부분 됨 | 전부 됨 |
| AI 코딩 도구 호환 | 자주 에러 | 가끔 에러 | 에러 없음 |
| npm/node | 동작하지만 느림 | 동작함 | 네이티브 속도 |
| 경로 문제 | 자주 발생 | 가끔 발생 | 없음 |
| 셋업 난이도 | 기본값 | Git 설치 시 자동 | 명령어 1줄 + 재부팅 |
정리
PowerShell → Git Bash → WSL. 나는 이 순서로 왔다.
WSL을 깔면서 잠깐 "맥북을 살 걸" 하는 생각이 들었다. Mac은 기본이 Unix라서 이런 과정이 필요 없으니까. 근데 WSL2가 진짜 Linux라는 걸 체감하고 나니, 그 생각이 사라졌다. Windows에서도 동일한 환경이 된다.
이건 Claude Code만의 문제가 아니다. 터미널 기반 AI 코딩 도구는 전부 Linux 명령어를 쓴다. WSL은 Claude Code용 세팅이 아니라, Windows에서 AI 코딩을 하기 위한 기본 인프라다. 처음부터 이걸 쓸 걸.
이 글은 Claude Code 플레이북을 만들면서 배운 것을 비개발자 시점으로 정리한 시리즈입니다.
