Windows에서 WSL 기반 Claude Code 개발환경 구축하기

부제: 성능 비교, 메모리 운영, tmux 기반 Agent Team 실전 구성

Windows에서 Claude Code를 쓰다 보면 금방 느끼는 문제가 있다.
“돌아가긴 하는데, 왜 이렇게 버벅이지?”

특히 Node 기반 프로젝트(파일 수 많음, 빌드/테스트 반복, 에이전트 병렬 실행)에서는 체감 차이가 더 커진다.
이 글은 Windows + WSL2 + Claude Code 조합을 실무 기준으로 안정적으로 운영하기 위한 가이드다.

1. 왜 Windows에서 WSL을 써야 하나? (성능 관점)

핵심은 하나다.

코드 실행/빌드/패키지 설치는 Linux FS (~/...)에서
Windows는 호스트 + UI + 브라우저 역할

이렇게 분리하면 성능과 안정성이 올라간다.

성능/운영 비교

항목	Windows 경로(C:\, /mnt/c)	WSL Linux 경로(/home/…)
파일 I/O (node_modules, 빌드 산출물)	느림/불안정 체감	빠르고 일관적
`pnpm install`, `npm ci`	프로젝트 커질수록 지연	상대적으로 빠름
테스트/빌드 반복	I/O 병목 발생 쉬움	반복 작업에 유리
쉘/CLI 호환성	도구별 편차 큼	Linux 표준에 가까움
Claude Code 자동화 루프	경로/권한 이슈 가능	매끄러움
대규모 모노레포	체감 성능 하락 큼	상대적으로 안정

스크린샷 포인트

time pnpm install 결과 (C:\ 미러 vs ~/work)
같은 프로젝트/같은 브랜치/비슷한 캐시 조건으로 비교

2. WSL 환경 구성 방법 (처음 세팅)

2-1. WSL2/Ubuntu 설치

PowerShell(관리자)에서:

wsl --install

설치 후 재부팅하고 Ubuntu 실행.

WSL 상태 확인:

wsl -l -v

2-2. WSL 내부 개발 패키지 설치

			
sudo apt-get update
sudo apt-get install -y build-essential git curl unzip tmux

Node는 nvm 사용 권장:

			
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
source ~/.bashrc
nvm install --lts
node -v
npm -v

		

pnpm 설치:

			
npm i -g pnpm
pnpm -v

2-3. 작업 디렉토리 구조

			
mkdir -p ~/work/
mkdir -p ~/work/shared

중요 원칙: 프로젝트는 /home/... 아래에 clone (/mnt/c/...에서 직접 개발하지 않기)

3. 메모리 관리: 실무에서 가장 중요한 포인트

Claude Code + 빌드 + 테스트 + 에이전트 병렬 작업을 하면 WSL 메모리가 빠르게 커지고 vmmem 사용량이 커질 수 있다.

3-1. `.wslconfig` 권장 설정

Windows 파일 경로: C:\Users\<USER>\.wslconfig

예시 (RAM 32GB 기준):

			
[wsl2]
memory=16GB
processors=8
swap=8GB
pageReporting=true

		

적용:

wsl --shutdown

3-2. 권장 튜닝 기준

RAM 16GB: memory=8GB, swap=4GB
RAM 32GB: memory=12~16GB, swap=8GB
RAM 64GB: memory=24~32GB, swap=8~16GB

3-3. 상태 점검 명령어

WSL에서:

			
free -h
ps aux --sort=-%mem | head -20

Windows PowerShell에서:

Get-Process -Name "vmmem*" | Select-Object Name,CPU,PM,WS

4. Claude Code 추천 운영: tmux split pane 기반 Agent Team

단일 터미널에서 다 처리하면 맥락 전환 비용이 커진다.
tmux로 역할 분리하면 작업 안정성이 높아진다.

4-1. 추천 레이아웃

상단 70%: Claude Code 실행
하단 좌: 리소스 모니터 (watch free -h)
하단 우: 로그/치트시트/테스트 결과

4-2. tmux 핵심 명령어

			
tmux new -s cc-work
tmux ls
tmux attach -t cc-work
tmux kill-session -t cc-work

pane 제어:

			
tmux list-panes -t cc-work
tmux kill-pane -t cc-work:0.1
tmux capture-pane -t cc-work -p | tail -30
tmux send-keys -t cc-work "pnpm test" Enter

4-3. 역할 분담 예시 (Agent Team)

Pane A: 기능 구현
Pane B: 테스트/린트 모니터
Pane C: 로그 분석/문서 정리

5. VS Code + WSL 실전 사용법

WSL 터미널에서 프로젝트 진입 후:

			
cd ~/work/[your-project]
code .

확인 포인트:

좌하단: WSL: Ubuntu-24.04
통합 터미널 pwd: /home/...

Windows 탐색기 접근 경로:
\\wsl.localhost\Ubuntu-24.04\home\<user>\work\...

6. Auto Memory 관리(운영 루틴)

완전 자동화보다 루틴화가 실무에서 더 강력하다.

세션 시작: 목표/브랜치/범위 고정
세션 중: pane 분리 + 타입체크/테스트 주기 실행
세션 종료: 불필요 세션 종료 + 리소스 정리 + 커밋/요약

종료 점검 스니펫:

			
echo "[1] tmux sessions"
tmux ls || true
echo "[2] memory"
free -h
echo "[3] git status"
git status -sb

		

7. 트러블슈팅 체크리스트

Q1. VS Code가 Windows 모드로 열려서 느리다
– WSL 터미널에서 code . 실행했는지 확인
– 좌하단 WSL: 표시 확인

Q2. 빌드/설치가 느리다
– 프로젝트가 /mnt/c/...에 있는지 확인
– /home/...로 이동 후 재시도

Q3. vmmem 메모리가 너무 크다
– .wslconfig 상한 확인
– wsl --shutdown으로 리셋
– 불필요 tmux/session 종료

Q4. Git 경로가 두 군데로 갈라졌다
– 원본 repo를 /home/... 하나로 통일
– Windows는 \\wsl.localhost\... 경유 접근 권장

결론

Windows에서 Claude Code 생산성을 높이는 핵심은,

“Windows에서 개발”이 아니라 “WSL Linux에서 개발 + Windows는 호스트로 사용”이다.

코드/빌드/테스트: WSL /home/...
편집기: code . + Remote-WSL
병렬 작업: tmux split pane
안정성: .wslconfig 메모리 설계 + 세션 정리 루틴

이 4가지만 잡아도 체감이 크게 달라진다.

생각과 행동(IDEA on Action)

recent posts

about