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 모델을 지원하며 더욱 강력한 기능을 제공합니다.

flowchart LR
    subgraph Traditional["기존 AI 코딩 도구"]
        direction LR
        T1["❓ 질문"] --> T2["💬 답변<br/>(코드)"] --> T3["📋 복사/<br/>붙여넣기"]
    end

    subgraph Agentic["Claude Code (Agentic)"]
        direction LR
        A1["📝 지시"] --> A2["🔍 코드<br/>분석"] --> A3["✏️ 파일<br/>수정"] --> A4["🧪 테스트<br/>실행"]
    end

    Traditional -.->|"사람이 직접<br/>코드를 복사하고<br/>적용해야 함"| Note1[" "]
    Agentic -.->|"Claude가 직접<br/>코드베이스에서<br/>작업을 수행"| Note2[" "]

    style Traditional fill:#ffcdd2,color:#000000
    style Agentic fill:#c8e6c9,color:#000000
    style T1 fill:#ef9a9a,color:#000000
    style T2 fill:#ef9a9a,color:#000000
    style T3 fill:#ef9a9a,color:#000000
    style A1 fill:#a5d6a7,color:#000000
    style A2 fill:#a5d6a7,color:#000000
    style A3 fill:#a5d6a7,color:#000000
    style A4 fill:#a5d6a7,color:#000000
    style Note1 fill:none,stroke:none
    style Note2 fill:none,stroke:none

1.2 Claude Code의 핵심 특징#

1.3 기존 도구와의 차이점#

flowchart TB
    subgraph Comparison["AI 코딩 도구 비교"]
        direction TB

        subgraph Tools["도구"]
            direction LR
            GC["🤖 GitHub Copilot"]
            CR["💻 Cursor"]
            CC["⚡ Claude Code"]
        end

        subgraph Features["특징"]
            direction LR
            GC_F["현재 파일의<br/>코드 자동완성에 집중"]
            CR_F["IDE 내에서<br/>AI 채팅 + 코드 수정"]
            CC_F["터미널 기반<br/>전체 코드베이스 접근<br/>명령 실행, 완전한 자율성"]
        end

        GC --> GC_F
        CR --> CR_F
        CC --> CC_F
    end

    style GC fill:#e3f2fd,color:#000000
    style CR fill:#e3f2fd,color:#000000
    style CC fill:#c8e6c9,color:#000000
    style GC_F fill:#e3f2fd,color:#000000
    style CR_F fill:#e3f2fd,color:#000000
    style CC_F fill:#c8e6c9,color:#000000

Claude Code는 “주니어 개발자에게 작업을 위임하는 것"과 비슷합니다. 명확한 지시와 컨텍스트를 제공하면 스스로 작업을 완료합니다.

2. CLAUDE.md의 역할과 동작 원리#

2.1 CLAUDE.md란?#

CLAUDE.md는 Claude Code가 모든 대화를 시작할 때 자동으로 읽는 특별한 파일입니다. 프로젝트의 “사용 설명서"라고 생각하면 됩니다.

flowchart TD
    A["🚀 Claude Code 시작"] --> B

    subgraph B["📁 CLAUDE.md 로드 순서"]
        direction TB
        B1["1️⃣ ~/.claude/CLAUDE.md 로드<br/>(전역 설정)"]
        B2["2️⃣ 프로젝트 루트 CLAUDE.md 로드"]
        B3["3️⃣ 현재 작업 디렉토리의<br/>CLAUDE.md 로드 (있다면)"]
        B1 --> B2 --> B3
    end

    B --> C["💬 사용자 대화 시작<br/>(컨텍스트 확보 완료)"]

    style A fill:#bbdefb,color:#000000
    style B fill:#e8f5e9,color:#000000
    style B1 fill:#c8e6c9,color:#000000
    style B2 fill:#c8e6c9,color:#000000
    style B3 fill:#c8e6c9,color:#000000
    style C fill:#fff9c4,color:#000000

2.2 계층적 구조 이해#

CLAUDE.md는 여러 위치에 존재할 수 있으며, 모두 병합되어 적용됩니다:

flowchart TB
    subgraph Priority["우선순위 (낮음 → 높음)"]
        direction TB

        P1["1️⃣ ~/.claude/CLAUDE.md<br/><b>전역</b>: 모든 프로젝트에 적용<br/><i>예: 개인 코딩 스타일, 선호하는 도구</i>"]

        P2["2️⃣ /project/CLAUDE.md<br/><b>프로젝트</b>: 팀과 공유 (Git 커밋)<br/><i>예: 빌드 명령, 테스트 방법, 아키텍처</i>"]

        P3["3️⃣ /project/CLAUDE.local.md<br/><b>개인 오버라이드</b> (.gitignore 대상)<br/><i>예: 로컬 환경 설정, 개인 API 키</i>"]

        P4["4️⃣ /project/src/module/CLAUDE.md<br/><b>하위 디렉토리</b>: 해당 모듈 작업 시만<br/><i>예: 특정 모듈의 규칙</i>"]

        P1 --> P2 --> P3 --> P4
    end

    style P1 fill:#e3f2fd,color:#000000
    style P2 fill:#bbdefb,color:#000000
    style P3 fill:#90caf9,color:#000000
    style P4 fill:#64b5f6,color:#000000

💡 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에게 다음을 알려줍니다:

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 핵심 원칙#

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. 정리#

이번 파트에서 배운 것#

1. Claude Code는 Agentic Coding Assistant로, 코드베이스에서 직접 작업을 수행
2. CLAUDE.md는 프로젝트의 “사용 설명서"로, 모든 대화 시작 시 자동 로드
3. 계층적 구조로 전역/프로젝트/개인 설정을 분리 가능
4. 좋은 CLAUDE.md는 구체적이고 실행 가능한 지시를 포함

다음 파트 예고#

CLAUDE.md가 점점 커지면 Claude가 지시를 무시하기 시작합니다. Part 2에서는 CLAUDE.md를 최적화하고 효율적으로 관리하는 방법을 배웁니다.

📚 참고 자료#

• Claude Code 공식 문서 - Best Practices
• Claude Code GitHub Repository
• Anthropic Engineering - Claude Code Best Practices

다음: Part 2: CLAUDE.md 최적화 - 비대해지는 것을 막아라