Claude Code 완전 정복 가이드 Part 1: CLAUDE.md 기초 - 첫 발을 내딛다
이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.
예상 소요 시간: 30분 난이도: ⭐ 사전 요구사항: Claude Code 설치 완료 (v2.1.x)
1. Claude Code란 무엇인가?#
1.1 Agentic Coding의 개념#
Claude Code는 단순한 코드 자동완성 도구가 아닙니다. Agentic Coding Assistant로서, 터미널에서 직접 코드베이스를 읽고, 파일을 생성/수정하고, 테스트를 실행하고, Git 작업까지 수행할 수 있습니다. 2025년 2월 첫 출시 이후 빠르게 발전하여, 현재 버전 2.1.x에서는 Opus 4.5 모델을 지원하며 더욱 강력한 기능을 제공합니다.
┌─────────────────────────────────────────────────────────────────┐
│ 기존 AI 코딩 도구 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 질문 │ ───▶ │ 답변 │ ───▶ │ 복사/ │ │
│ │ │ │ (코드) │ │ 붙여넣기│ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ 사람이 직접 코드를 복사하고 적용해야 함 │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code (Agentic) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│ │ 지시 │ ───▶ │ 코드 │ ───▶ │ 파일 │ ───▶ │ 테스트 │ │
│ │ │ │ 분석 │ │ 수정 │ │ 실행 │ │
│ └─────────┘ └─────────┘ └─────────┘ └────────┘ │
│ Claude가 직접 코드베이스에서 작업을 수행 │
└─────────────────────────────────────────────────────────────────┘
1.2 Claude Code의 핵심 특징#
| 특징 | 설명 |
|---|---|
| 파일 시스템 접근 | 프로젝트의 모든 파일을 읽고 쓸 수 있음 |
| 터미널 명령 실행 | npm test, go build, gradle build 등 직접 실행 |
| Git 통합 | 브랜치 생성, 커밋, PR 생성까지 자동화 가능 |
| 컨텍스트 인식 | CLAUDE.md를 통해 프로젝트 특성을 이해 |
| 도구 확장 | Skills, Plugins, MCP를 통한 기능 확장 |
1.3 기존 도구와의 차이점#
GitHub Copilot │ 현재 파일의 코드 자동완성에 집중
Cursor │ IDE 내에서 AI 채팅 + 코드 수정
───────────────────┼────────────────────────────────────
Claude Code │ 터미널 기반, 전체 코드베이스 접근,
│ 명령 실행, 완전한 자율성
Claude Code는 “주니어 개발자에게 작업을 위임하는 것"과 비슷합니다. 명확한 지시와 컨텍스트를 제공하면 스스로 작업을 완료합니다.
2. CLAUDE.md의 역할과 동작 원리#
2.1 CLAUDE.md란?#
CLAUDE.md는 Claude Code가 모든 대화를 시작할 때 자동으로 읽는 특별한 파일입니다. 프로젝트의 “사용 설명서"라고 생각하면 됩니다.
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 시작 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. ~/.claude/CLAUDE.md 로드 (전역 설정) │
│ 2. 프로젝트 루트 CLAUDE.md 로드 │
│ 3. 현재 작업 디렉토리의 CLAUDE.md 로드 (있다면) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 사용자 대화 시작 (컨텍스트 확보 완료) │
└─────────────────────────────────────────────────────────────┘
2.2 계층적 구조 이해#
CLAUDE.md는 여러 위치에 존재할 수 있으며, 모두 병합되어 적용됩니다:
우선순위 (낮음 → 높음)
─────────────────────────────────────────────────────────────
1. ~/.claude/CLAUDE.md # 전역: 모든 프로젝트에 적용
│ # 예: 개인 코딩 스타일, 선호하는 도구
│
▼
2. /project/CLAUDE.md # 프로젝트: 팀과 공유 (Git 커밋)
│ # 예: 빌드 명령, 테스트 방법, 아키텍처
│
▼
3. /project/CLAUDE.local.md # 개인 오버라이드 (.gitignore 대상)
│ # 예: 로컬 환경 설정, 개인 API 키
│
▼
4. /project/src/module/CLAUDE.md # 하위 디렉토리: 해당 모듈 작업 시만
# 예: 특정 모듈의 규칙
💡 Best Practice: 하위 디렉토리의 CLAUDE.md는 Claude가 해당 디렉토리의 파일을 작업할 때만 동적으로 로드됩니다.
2.3 /init 명령어로 자동 생성하기#
Claude Code는 프로젝트를 분석하여 기본 CLAUDE.md를 자동 생성해줍니다:
# Claude Code 실행 후
/init
/init 명령어는 다음을 자동으로 감지합니다:
- 빌드 시스템 (Gradle, Maven, npm, Go modules 등)
- 테스트 프레임워크
- 코드 패턴과 구조
- 기존 README.md 내용
생성된 CLAUDE.md를 기반으로 프로젝트에 맞게 수정하면 됩니다.
3. 첫 번째 CLAUDE.md 작성하기#
3.1 필수 포함 요소#
좋은 CLAUDE.md는 Claude에게 다음을 알려줍니다:
| 요소 | 설명 | 예시 |
|---|---|---|
| WHAT | 프로젝트가 무엇인지 | “Spring Boot 기반 결제 API 서버” |
| WHY | 각 부분의 목적 | “internal/ 패키지는 외부 노출 금지” |
| HOW | 작업 방법 | “테스트: ./gradlew test” |
3.2 기본 템플릿 구조#
# 프로젝트 이름
프로젝트에 대한 한 줄 설명
## 빌드 및 실행
- 빌드: `command here`
- 테스트: `command here`
- 단일 테스트: `command here`
- 린트: `command here`
## 코드 스타일
- 스타일 가이드라인 1
- 스타일 가이드라인 2
## 프로젝트 구조
주요 디렉토리와 그 역할 설명
## 워크플로우
- Git 브랜치 전략
- PR 규칙
- 기타 개발 프로세스
3.3 Java/Kotlin 프로젝트용 템플릿#
# Payment API Server
Spring Boot 3.x 기반 결제 처리 API 서버
## 빌드 및 테스트
- 빌드: `./gradlew build`
- 전체 테스트: `./gradlew test`
- 단일 테스트: `./gradlew test --tests "ClassName.methodName"`
- 린트: `./gradlew ktlintCheck`
- 포맷팅: `./gradlew ktlintFormat`
## 기술 스택
- Java 21 / Kotlin 1.9
- Spring Boot 3.2
- Gradle 8.x (Kotlin DSL)
- JUnit 5 + MockK
## 프로젝트 구조
src/main/kotlin/com/example/payment/ ├── api/ # REST Controllers ├── application/ # Use Cases, Application Services ├── domain/ # Domain Models, Repository Interfaces └── infrastructure/# Repository Implementations, External APIs
## 코드 스타일
- Kotlin 공식 코딩 컨벤션 준수
- 함수명: camelCase (동사로 시작)
- 클래스명: PascalCase
- 상수: SCREAMING_SNAKE_CASE
- 패키지명: lowercase (단어 구분 없음)
## 테스트 규칙
- 테스트 클래스명: `{대상클래스}Test`
- 테스트 메서드명: `should_결과_when_조건` 패턴
- Given-When-Then 구조 사용
- Mock은 MockK 사용 (Mockito 금지)
## Git 워크플로우
- 브랜치: `feature/{ticket-number}-{short-description}`
- 커밋: Conventional Commits 형식
- `feat:`, `fix:`, `refactor:`, `test:`, `docs:`
- PR 전 `./gradlew build` 성공 필수
3.4 Go 프로젝트용 템플릿#
# User Service
Go 1.22 기반 사용자 관리 마이크로서비스
## 빌드 및 테스트
- 빌드: `go build -o bin/server ./cmd/server`
- 전체 테스트: `go test ./...`
- 커버리지: `go test -cover ./...`
- 단일 테스트: `go test -run TestFunctionName ./path/to/package`
- 린트: `golangci-lint run`
## 기술 스택
- Go 1.22
- Gin (HTTP Framework)
- sqlx (Database)
- Wire (DI)
## 프로젝트 구조
. ├── cmd/ │ └── server/ # 애플리케이션 진입점 ├── internal/ # 외부 import 금지 │ ├── handler/ # HTTP handlers │ ├── service/ # 비즈니스 로직 │ ├── repository/ # 데이터 접근 │ └── model/ # 도메인 모델 ├── pkg/ # 외부에서 import 가능한 패키지 └── api/ # OpenAPI specs
## 코드 스타일
- `gofmt` 자동 포맷팅 적용
- 변수명: camelCase (짧고 명확하게)
- 인터페이스명: `-er` 접미사 (Reader, Writer, Handler)
- 에러 처리: 즉시 처리, 절대 무시하지 않음
- 주석: exported 항목은 반드시 GoDoc 형식으로
## 에러 처리 패턴
```go
// 권장
if err != nil {
return fmt.Errorf("failed to create user: %w", err)
}
// 금지
if err != nil {
return err // 컨텍스트 없음
}
테스트 규칙#
- 테스트 파일:
{파일명}_test.go - 테이블 기반 테스트 선호
- Mock은 인터페이스 기반으로 직접 작성 또는 mockgen 사용
Git 워크플로우#
- 브랜치:
feature/{description}또는fix/{description} - 커밋: 명령형 현재 시제 (“Add feature” not “Added feature”)
- PR 전
golangci-lint run통과 필수
---
## 4. 실습: Spring Boot 프로젝트에 CLAUDE.md 적용
### 4.1 시나리오
새로운 Spring Boot 프로젝트를 시작하고 CLAUDE.md를 설정해봅시다.
### 4.2 Step-by-Step
**Step 1: 프로젝트 폴더로 이동**
```bash
cd ~/projects/my-spring-app
Step 2: Claude Code 실행 및 초기화
claude
Claude Code 프롬프트에서:
/init
Step 3: 생성된 CLAUDE.md 확인
Claude가 프로젝트를 분석하여 기본 CLAUDE.md를 생성합니다. 내용을 확인하고 부족한 부분을 추가합니다.
Step 4: 프로젝트별 규칙 추가
# 추가할 내용 예시
## 도메인 규칙
- Entity 클래스는 반드시 `domain` 패키지에 위치
- DTO는 `api.dto` 패키지에 위치
- Entity와 DTO 간 변환은 MapStruct 사용
## 예외 처리
- 비즈니스 예외: `BusinessException` 상속
- 예외 코드: `ErrorCode` enum 사용
- GlobalExceptionHandler에서 일괄 처리
## API 규칙
- REST API: `/api/v1/` 프리픽스
- 응답 형식: `ApiResponse<T>` wrapper 사용
- 페이징: `Pageable` 파라미터 사용
Step 5: 동작 확인
Claude Code에서 질문해봅니다:
새로운 User 엔티티를 만들어줘
Claude는 CLAUDE.md의 규칙을 따라:
domain패키지에 Entity 생성api.dto패키지에 DTO 생성- MapStruct mapper 생성
4.3 확인 포인트#
✅ Claude가 코드 스타일을 따르는가? ✅ 테스트 명령어를 올바르게 사용하는가? ✅ 프로젝트 구조를 이해하고 있는가?
5. CLAUDE.md 작성 팁#
5.1 DO: 이렇게 하세요#
# ✅ 좋은 예: 구체적이고 실행 가능한 지시
## 테스트
- 단일 테스트: `./gradlew test --tests "UserServiceTest.shouldCreateUser"`
- 통합 테스트: `./gradlew integrationTest`
## 코드 스타일
- 함수는 20줄 이하로 유지
- 한 파일에 하나의 public 클래스만
5.2 DON’T: 이렇게 하지 마세요#
# ❌ 나쁜 예: 모호하고 일반적인 내용
## 테스트
- 테스트를 잘 작성하세요
- 커버리지를 높이세요
## 코드 스타일
- 좋은 코드를 작성하세요
- 가독성 있게 작성하세요
5.3 핵심 원칙#
| 원칙 | 설명 |
|---|---|
| 간결하게 | 100-200줄 이내 권장 |
| 구체적으로 | 실행 가능한 명령어와 규칙 |
| 검증 가능하게 | “이 줄을 삭제해도 Claude가 실수하지 않을까?” |
| 업데이트 | 코드처럼 CLAUDE.md도 유지보수 |
6. 자주 발생하는 문제와 해결#
6.1 Claude가 CLAUDE.md를 무시하는 것 같아요#
원인: CLAUDE.md가 너무 길거나 지시가 모호함
해결:
# 강조가 필요한 규칙에는 IMPORTANT 추가
IMPORTANT: 절대로 main 브랜치에 직접 커밋하지 마세요.
# 또는 대문자로 강조
YOU MUST run tests before committing.
6.2 프로젝트마다 다른 설정을 적용하고 싶어요#
해결: 계층적 구조 활용
~/.claude/CLAUDE.md # 공통 (개인 스타일)
/project-a/CLAUDE.md # Project A 전용
/project-b/CLAUDE.md # Project B 전용
6.3 팀원과 설정을 공유하고 싶어요#
해결: 프로젝트 루트의 CLAUDE.md를 Git에 커밋
# 팀 공유용
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md for team collaboration"
# 개인 설정은 .gitignore
echo "CLAUDE.local.md" >> .gitignore
7. 정리#
이번 파트에서 배운 것#
- Claude Code는 Agentic Coding Assistant로, 코드베이스에서 직접 작업을 수행
- CLAUDE.md는 프로젝트의 “사용 설명서"로, 모든 대화 시작 시 자동 로드
- 계층적 구조로 전역/프로젝트/개인 설정을 분리 가능
- 좋은 CLAUDE.md는 구체적이고 실행 가능한 지시를 포함
다음 파트 예고#
CLAUDE.md가 점점 커지면 Claude가 지시를 무시하기 시작합니다. Part 2에서는 CLAUDE.md를 최적화하고 효율적으로 관리하는 방법을 배웁니다.
📚 참고 자료#
- Claude Code 공식 문서 - Best Practices
- Claude Code GitHub Repository
- Anthropic Engineering - Claude Code Best Practices