Claude Code 설치부터 CLAUDE.md 설정까지 완전 가이드 (2025)
Claude Code 설치부터 CLAUDE.md 설정까지 - 로컬 개발환경 완전 셋업 가이드
Claude Code는 Anthropic이 제공하는 터미널 기반 AI 코딩 어시스턴트입니다. VS Code 확장이나 웹 인터페이스와 달리, 터미널에서 직접 코드베이스를 읽고 수정하며 명령을 실행할 수 있는 에이전트형 도구입니다. 이 가이드에서는 설치부터 CLAUDE.md 설정, 실전 워크플로우까지 단계별로 안내합니다.
1단계: 사전 요구사항 확인
Claude Code를 설치하기 전에 다음 환경이 준비되어야 합니다.
- Node.js 18 이상 — Claude Code는 npm 패키지로 배포됩니다- Git — 코드베이스 탐색 및 변경 추적에 필요- Anthropic API 키 또는 Claude Max 구독터미널에서 버전을 확인하세요:
node —version git —version
2단계: Claude Code 설치
npm을 통해 전역으로 설치합니다.
npm install -g @anthropic-ai/claude-code
설치가 완료되면 프로젝트 디렉토리로 이동하여 Claude Code를 실행합니다.
cd /path/to/your/project
claude
처음 실행 시 인증 과정을 거칩니다. API 키를 사용하는 경우 환경변수로 설정할 수 있습니다.
export ANTHROPIC_API_KEY=YOUR_API_KEY
claude
## 3단계: CLAUDE.md 파일 이해하기
CLAUDE.md는 Claude Code의 핵심 설정 파일입니다. 이 파일을 통해 프로젝트별 지침, 코딩 규칙, 워크플로우를 정의할 수 있습니다. Claude Code가 시작될 때 자동으로 이 파일을 읽어 컨텍스트로 활용합니다.
CLAUDE.md 위치별 역할
| 위치 | 적용 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md | 모든 프로젝트 (전역) | 개인 선호사항, 공통 규칙 |
프로젝트루트/CLAUDE.md | 해당 프로젝트 | 프로젝트별 지침, 팀 공유 규칙 |
하위폴더/CLAUDE.md | 해당 디렉토리 | 모듈별 세부 규칙 |
# 프로젝트 개요
이 프로젝트는 React + TypeScript 기반의 대시보드 앱입니다.
패키지 매니저는 pnpm을 사용합니다.
기술 스택
- Frontend: React 18, TypeScript 5
- Styling: Tailwind CSS
- State: Zustand
- Testing: Vitest + React Testing Library
코딩 규칙
- 함수형 컴포넌트와 훅만 사용
- any 타입 사용 금지
- 모든 컴포넌트는 /components 하위에 배치
- 테스트 파일은 tests 폴더에 .test.tsx 확장자로 작성
자주 쓰는 명령어
- 개발 서버: pnpm dev
- 테스트: pnpm test
- 빌드: pnpm build
- 린트: pnpm lint
주의사항
- .env 파일을 절대 커밋하지 마세요
- API 호출은 반드시 /lib/api.ts를 통해 수행
에러 핸들링 시 커스텀 AppError 클래스 사용
5단계: 전역 CLAUDE.md 설정하기
모든 프로젝트에 공통 적용할 개인 규칙은 전역 CLAUDE.md에 작성합니다.
# ~/.claude/CLAUDE.md
개인 설정
- 응답 언어: 한국어
- 커밋 메시지: Conventional Commits 형식 사용
- 코드 설명 시 간결하게 핵심만 전달
외부 도구 연동
- config: ~/.config/gws/
scopes: drive, gmail.modify, calendar
6단계: 실전 워크플로우 활용
CLAUDE.md가 설정된 상태에서 Claude Code를 효과적으로 활용하는 워크플로우입니다.
버그 수정 워크플로우
# 프로젝트 디렉토리에서 실행
claude
Claude Code 대화에서:
로그인 페이지에서 빈 이메일로 제출하면 500 에러가 발생해. 원인을 찾고 수정해줘.
새 기능 개발 워크플로우
> 사용자 프로필 페이지에 아바타 업로드 기능을 추가해줘.
> 기존 /lib/api.ts의 패턴을 따르고, 파일 크기는 5MB로 제한해.코드 리뷰 워크플로우
> git diff main 결과를 보고 코드 리뷰해줘. 보안 이슈와 성능 문제에 집중해.Pro Tips: 파워 유저를 위한 고급 설정
- 권한 모드 활용 —
claude —dangerously-skip-permissions는 CI/CD 환경에서 자동화할 때 유용합니다. 로컬에서는 기본 권한 모드를 유지하세요.- CLAUDE.md에 예제 포함 — 단순 규칙 나열보다 코드 예제를 포함하면 Claude가 더 정확하게 패턴을 따릅니다.- 하위 디렉토리 CLAUDE.md — 백엔드와 프론트엔드가 모노레포에 있다면 각 디렉토리에 별도 CLAUDE.md를 두어 컨텍스트를 분리하세요.- 슬래시 명령어 — 대화 중/help로 사용 가능한 명령어를 확인하고,/compact로 컨텍스트를 압축할 수 있습니다.- 메모리 시스템 — Claude Code는~/.claude/projects/경로에 프로젝트별 메모리를 저장합니다. “이것 기억해줘”라고 말하면 영구 메모리에 저장됩니다.
Troubleshooting: 자주 발생하는 오류 해결
| 증상 | 원인 | 해결 방법 |
|---|---|---|
command not found: claude | 전역 설치 실패 또는 PATH 미설정 | npm install -g @anthropic-ai/claude-code 재실행 후 터미널 재시작 |
| 인증 오류 (401) | API 키 만료 또는 잘못된 키 | echo $ANTHROPIC_API_KEY로 확인 후 올바른 키로 재설정 |
| CLAUDE.md가 인식되지 않음 | 파일명 대소문자 오류 | 반드시 CLAUDE.md (대문자)로 저장. claude.md는 인식되지 않음 |
| 컨텍스트 초과 오류 | 대화가 너무 길어짐 | /compact 명령으로 컨텍스트 압축 또는 새 세션 시작 |
| 도구 실행 권한 거부 | 기본 권한 모드에서 위험한 명령 차단 | 프롬프트에서 승인하거나, 안전한 명령으로 대체 |
Q1. CLAUDE.md 파일은 Git에 커밋해야 하나요?
프로젝트 루트의 CLAUDE.md는 팀 전체가 공유하는 규칙이므로 Git에 커밋하는 것이 좋습니다. 반면 ~/.claude/CLAUDE.md는 개인 설정이므로 커밋 대상이 아닙니다. 민감한 정보(API 키, 내부 URL 등)가 포함되지 않도록 주의하세요.
Q2. Claude Code와 VS Code Copilot을 동시에 사용할 수 있나요?
네, 두 도구는 독립적으로 동작합니다. Claude Code는 터미널에서, Copilot은 에디터 내에서 각각 실행됩니다. 다만 동일 파일을 동시에 수정하면 충돌이 발생할 수 있으므로, Claude Code가 파일을 수정하는 동안에는 에디터에서 해당 파일의 편집을 자제하는 것이 안전합니다.
Q3. CLAUDE.md의 내용이 너무 길면 성능에 영향을 주나요?
CLAUDE.md는 매 대화 시작 시 컨텍스트에 로드되므로, 지나치게 긴 내용은 실질적인 대화에 사용할 수 있는 컨텍스트 공간을 줄입니다. 핵심 규칙과 명령어 중심으로 간결하게 유지하고, 상세 문서는 별도 파일로 분리한 뒤 필요할 때 참조하도록 안내하는 것이 효과적입니다.