Claude Code 설치 및 설정 가이드: Windows 개발자를 위한 완벽 안내서
Claude Code란? Windows 개발자를 위한 AI 코딩 어시스턴트
Claude Code는 Anthropic에서 개발한 터미널 기반 AI 코딩 어시스턴트입니다. 코드 작성, 디버깅, 리팩토링, 프로젝트 탐색까지 터미널에서 바로 수행할 수 있어 개발 워크플로우를 획기적으로 개선합니다. 이 가이드에서는 Windows 환경에서 Claude Code를 설치하고 최적의 개발 환경을 구축하는 전 과정을 단계별로 안내합니다.
사전 요구사항 확인
Claude Code를 설치하기 전에 다음 환경이 준비되어 있는지 확인하세요.
- Node.js 18 이상 — Claude Code는 Node.js 런타임에서 실행됩니다- npm 또는 npx — 패키지 관리자가 필요합니다- Git Bash 또는 WSL — Unix 호환 셸 환경을 권장합니다- Anthropic API 키 —
console.anthropic.com에서 발급 가능합니다
Step 1: Node.js 설치 및 버전 확인
먼저 Node.js가 올바르게 설치되어 있는지 확인합니다.
# Node.js 버전 확인
node —version
v18.0.0 이상이어야 합니다
npm 버전 확인
npm —version
nvm을 사용하는 경우 최신 LTS 설치
nvm install —lts
nvm use —lts
Node.js가 설치되어 있지 않다면 nodejs.org에서 LTS 버전을 다운로드하거나, Windows 패키지 매니저를 사용하세요.
# winget으로 설치
winget install OpenJS.NodeJS.LTS
또는 choco로 설치
choco install nodejs-lts
Step 2: Claude Code 설치
npm을 통해 글로벌로 Claude Code를 설치합니다.
# 글로벌 설치
npm install -g @anthropic-ai/claude-code
설치 확인
claude —version
또는 npx로 직접 실행 (설치 없이)
npx @anthropic-ai/claude-code
Step 3: API 인증 설정
Claude Code를 사용하려면 Anthropic API 키가 필요합니다. 환경 변수로 설정하는 방법이 가장 일반적입니다.
# 환경 변수 설정 (현재 세션)
export ANTHROPIC_API_KEY=YOUR_API_KEY
Windows PowerShell에서 영구 설정
[System.Environment]::SetEnvironmentVariable(‘ANTHROPIC_API_KEY’, ‘YOUR_API_KEY’, ‘User’)
Git Bash의 .bashrc에 추가
echo ‘export ANTHROPIC_API_KEY=YOUR_API_KEY’ >> ~/.bashrc
source ~/.bashrc
또는 첫 실행 시 claude 명령어를 입력하면 대화형 로그인 프로세스가 시작되어 브라우저를 통해 인증할 수 있습니다.
# 대화형 인증 시작
claude
브라우저가 열리며 Anthropic 계정으로 로그인
Step 4: 셸 통합 설정
셸 통합을 활성화하면 자동 완성, 히스토리 탐색 등의 편의 기능을 사용할 수 있습니다.
# 셸 통합 설치
claude setup
Git Bash에서 수동으로 셸 통합 추가
claude setup —shell bash
셸 재시작 후 적용 확인
source ~/.bashrc
Step 5: CLAUDE.md 프로젝트 설정
CLAUDE.md는 Claude Code에 프로젝트별 지침을 전달하는 핵심 설정 파일입니다. 프로젝트 루트에 이 파일을 만들면 Claude가 코드베이스의 컨텍스트를 이해하고 일관된 코딩 스타일을 유지합니다.
# 프로젝트 루트에 CLAUDE.md 생성
touch CLAUDE.md
다음은 실용적인 CLAUDE.md 예시입니다.
# Project: My Web Application
Tech Stack
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- ORM: Prisma
Coding Conventions
- Use functional components with hooks
- File naming: kebab-case for files, PascalCase for components
- Always use TypeScript strict mode
- Write unit tests for all utility functions
Project Structure
- src/components/ — React components
- src/api/ — API route handlers
- src/utils/ — Shared utilities
- prisma/ — Database schema and migrations
Commands
- Dev server: npm run dev
- Test: npm run test
- Build: npm run build
Lint: npm run lintCLAUDE.md는 세 가지 위치에 배치할 수 있으며, 우선순위가 다릅니다.
| 위치 | 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md | 전역 (모든 프로젝트) | 개인 선호도, 공통 규칙 |
프로젝트루트/CLAUDE.md | 프로젝트 전체 | 팀 공유 컨벤션, 기술 스택 정보 |
하위폴더/CLAUDE.md | 특정 디렉토리 | 모듈별 특수 규칙 |
# 프로젝트 디렉토리로 이동 후 실행
cd /c/projects/my-app
claude
단일 명령 실행 모드
claude -p “이 프로젝트의 구조를 설명해줘”
파일 지정하여 질문
claude -p “src/utils/auth.ts 파일의 보안 취약점을 분석해줘”
비대화형 모드로 코드 생성
claude -p “Express 미들웨어로 rate limiter를 작성해줘” —output-format text
Pro Tips: 파워 유저를 위한 고급 설정
- 메모리 시스템 활용 — Claude Code는
~/.claude/projects/경로에 프로젝트별 메모리를 저장합니다. 대화 중 “이것을 기억해줘”라고 요청하면 이후 세션에서도 컨텍스트가 유지됩니다.- MCP 서버 연동 —claude mcp add명령으로 외부 도구(데이터베이스, API 문서 등)를 연결하면 Claude의 능력을 크게 확장할 수 있습니다.- 권한 모드 설정 —/permissions명령으로 파일 편집, 명령 실행 등의 자동 승인 규칙을 세밀하게 제어하세요.- Git 연동 최적화 — Claude Code는 Git 저장소에서 가장 효과적으로 작동합니다. 프로젝트를 반드시 Git으로 관리하세요. 커밋 메시지 작성, diff 분석, 브랜치 관리까지 자동화됩니다.- 모델 선택 — 기본 모델은 Claude Sonnet이며,/model명령으로 Opus 등 다른 모델로 전환할 수 있습니다. 복잡한 작업에는 Opus를 추천합니다.
Troubleshooting: 자주 발생하는 오류 해결
1. “command not found: claude” 오류
글로벌 npm 바이너리 경로가 시스템 PATH에 포함되지 않은 경우 발생합니다.
# npm 글로벌 경로 확인
npm config get prefix
PATH에 추가 (Git Bash)
export PATH=“$PATH:$(npm config get prefix)/bin”
echo ‘export PATH=“$PATH:’$(npm config get prefix)‘/bin”’ >> ~/.bashrc
2. Node.js 버전 호환성 오류
Node.js 18 미만 버전에서는 Claude Code가 실행되지 않습니다.
# 현재 버전 확인
node --version
nvm으로 버전 업그레이드
nvm install 20
nvm use 20
3. API 키 인증 실패
환경 변수가 올바르게 설정되지 않았거나 API 키가 만료된 경우입니다.
# 환경 변수 확인
echo $ANTHROPIC_API_KEY
키가 비어있다면 다시 설정
export ANTHROPIC_API_KEY=YOUR_API_KEY
인증 상태 초기화 후 재로그인
claude logout
claude
4. Windows 줄바꿈(CRLF) 문제
Git Bash에서 CRLF 관련 경고가 뜨면 Git 설정을 확인하세요.
git config --global core.autocrlf input
### 5. 권한 거부(EACCES) 오류
npm 글로벌 설치 시 권한 문제가 발생하면 npm 기본 디렉토리를 변경합니다.
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$PATH:$HOME/.npm-global/bin"
echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.bashrc
## 자주 묻는 질문 (FAQ)
Q1: Claude Code는 무료로 사용할 수 있나요?
Claude Code는 Anthropic API를 통해 작동하므로 API 사용량에 따른 비용이 발생합니다. Anthropic Console에서 API 키를 발급받을 때 결제 정보를 등록해야 합니다. 또한 Claude Pro나 Max 구독을 통해서도 사용할 수 있으며, 구독 플랜에 포함된 사용량 내에서 추가 비용 없이 이용 가능합니다.
Q2: CLAUDE.md 파일을 Git에 커밋해도 되나요?
프로젝트 루트의 CLAUDE.md는 팀원 모두가 공유하는 프로젝트 컨벤션을 담는 파일이므로 Git에 커밋하는 것을 권장합니다. 반면 ~/.claude/CLAUDE.md는 개인 전역 설정 파일이므로 저장소에 포함하지 않습니다. API 키나 개인 인증 정보는 절대 CLAUDE.md에 포함하지 마세요.
Q3: WSL과 Git Bash 중 어떤 것이 Claude Code에 더 적합한가요?
두 환경 모두 Claude Code를 원활하게 실행할 수 있습니다. WSL은 완전한 Linux 환경을 제공하므로 Linux 기반 프로젝트나 Docker 연동이 필요한 경우 유리합니다. Git Bash는 설치가 간편하고 Windows 파일 시스템에 직접 접근이 가능하여 가벼운 개발 환경에 적합합니다. Claude Code는 Unix 셸 문법을 사용하므로 두 환경 모두 호환됩니다.