CLAUDE.md - 프로젝트 설정의 핵심

이 장에서 배우는 것

CLAUDE.md가 무엇이고 왜 필요한지
파일 위치와 우선순위
효과적인 작성법과 템플릿
조건부 규칙 설정

CLAUDE.md란?

Claude Code에게 프로젝트 맥락을 알려주는 설정 파일입니다.

Claude Code는 세션을 시작할 때 이 파일을 자동으로 읽어서 프로젝트의 맥락, 규칙, 선호도를 파악합니다.

왜 필요한가?

CLAUDE.md 없이	CLAUDE.md 있으면
매 세션마다 “이 프로젝트는…” 설명	자동으로 맥락 파악
”한국어로 답해줘” 반복	설정대로 자동 적용
결과물 스타일이 매번 다름	일관된 스타일 유지
실수할 수 있는 작업도 실행	금지 규칙으로 사전 방지

공식 문서

참고: Claude Code Memory 문서

파일 위치와 우선순위

CLAUDE.md는 여러 위치에 둘 수 있고, 계층적으로 적용됩니다.

~/.claude/CLAUDE.md              # 1. 전역 (모든 프로젝트)
./CLAUDE.md                      # 2. 프로젝트 루트
./.claude/CLAUDE.md              # 3. 프로젝트 상세
./.claude/CLAUDE.local.md        # 4. 개인 설정 (git 제외)
./.claude/rules/*.md             # 5. 조건부 규칙

적용 순서

순서	위치	범위	용도
1	`~/.claude/CLAUDE.md`	전역	개인 스타일, 공통 규칙
2	`./CLAUDE.md`	프로젝트	프로젝트 개요, 팀 규칙
3	`./.claude/CLAUDE.md`	프로젝트	더 상세한 설정
4	`./.claude/CLAUDE.local.md`	개인	개인 환경 (git 제외)
5	`./.claude/rules/*.md`	조건부	특정 파일/폴더에만 적용

권장 사용법

전역 설정 (~/.claude/CLAUDE.md)

응답 언어 (한국어)
응답 스타일 (존댓말/반말)
개인적인 선호

프로젝트 설정 (./CLAUDE.md)

프로젝트 목표와 맥락
폴더 구조 설명
팀 공통 규칙
git에 커밋해서 팀과 공유

개인 설정 (./.claude/CLAUDE.local.md)

로컬 환경 설정
API 키 경로
.gitignore에 추가

기본 구조

최소 템플릿

# 프로젝트명

## 개요

이 프로젝트가 무엇인지 1-2문장

## 핵심 규칙

- 규칙 1
- 규칙 2

## 금지 사항

- 하지 말아야 할 것

전체 템플릿

# 프로젝트명

## 개요

- **목적**: 이 프로젝트가 무엇을 위한 것인지
- **대상**: 누구를 위한 것인지
- **상태**: 현재 어느 단계인지 (기획/개발/운영)

## 기술 스택

- 주요 기술/도구 목록
- 버전 정보

## 폴더 구조

/src - 소스 코드 /docs - 문서 /tests - 테스트


## 핵심 규칙
- 코드 스타일
- 네이밍 규칙
- 커밋 메시지 형식

## 금지 사항
- 절대 하지 말아야 할 것
- 민감한 파일/폴더

## 참고 자료
- 관련 문서 링크
- 외부 레퍼런스

작성 팁 (Best Practices)

1. 구체적으로 작성

나쁜 예

## 규칙

- 깔끔하게 작성
- 좋은 품질로

좋은 예

## 규칙

- 문장은 3줄 이내로 끊기
- 전문 용어 사용 시 괄호로 설명 추가
- 숫자는 천 단위 콤마 (예: 1,000,000)
- 날짜 형식: YYYY-MM-DD

2. 500줄 이하로 유지

참고: Anthropic Best Practices

너무 길면 Claude가 일부를 무시할 수 있습니다.

핵심만 CLAUDE.md에 작성
상세 내용은 별도 파일로 분리
@path/to/file 문법으로 참조

## 상세 가이드

자세한 내용은 아래 파일 참조:
@docs/style-guide.md
@docs/naming-convention.md

3. 금지 사항 명확히

Claude가 실수하지 않도록 금지 사항을 명시:

## 금지 사항

- `.env` 파일 수정하지 않기
- `main` 브랜치에 직접 커밋하지 않기
- `/secrets` 폴더 내용 읽지 않기
- 외부 API 키를 코드에 하드코딩하지 않기

4. 예시 포함

원하는 결과물의 예시를 보여주면 효과적:

## 커밋 메시지 형식

### 형식

[타입] 제목

본문 (선택)


### 예시

[feat] 사용자 로그인 기능 추가

이메일/비밀번호 로그인
소셜 로그인 (Google, Kakao)

5. 우선순위 표시

중요도를 명시하면 Claude가 더 잘 따릅니다:

## 규칙 (중요도순)

### 필수 (MUST)

- 모든 파일은 UTF-8 인코딩
- 함수명은 camelCase

### 권장 (SHOULD)

- 주석은 한국어로
- 변수명은 의미 있게

### 선택 (NICE TO HAVE)

- 타입 힌트 추가

실전 템플릿

마케팅 프로젝트

# 2024 Q1 마케팅 캠페인

## 개요

- **목적**: Q1 신제품 출시 마케팅
- **기간**: 2024.01 - 2024.03
- **담당**: 마케팅팀

## 브랜드 가이드라인

- **톤앤매너**: 친근하지만 전문적
- **타겟**: 30-40대 직장인
- **키 메시지**: "일상을 바꾸는 작은 시작"

## 콘텐츠 규칙

- 제목: 15자 이내
- 본문: 500자 이내
- CTA: 항상 포함
- 해시태그: 3-5개

## 금지 표현

- "최고", "유일한", "완벽한" (광고법 위반)
- 경쟁사 직접 언급
- 검증되지 않은 수치

## 폴더 구조

/content - 콘텐츠 초안 /assets - 이미지, 영상 /reports - 성과 보고서 /approved - 승인된 최종본


## 승인 프로세스
1. 초안 작성 → /content
2. 팀장 검토
3. 법무 검토 (필요시)
4. 최종 승인 → /approved

기획 문서 프로젝트

# 서비스 기획 - [프로젝트명]

## 개요

- **목적**: 신규 기능 기획
- **상태**: 기획 단계
- **출시 목표**: 2024 Q2

## 문서 규칙

### 파일명 형식

- 기능 정의: `PRD-[기능명].md`
- 회의록: `MTG-YYYY-MM-DD-[주제].md`
- 리서치: `RSC-[주제].md`

### PRD 필수 항목

1. 문제 정의
2. 목표 및 성공 지표
3. 사용자 스토리
4. 기능 요구사항
5. 비기능 요구사항
6. 타임라인

## 용어 정의

- **MVP**: Minimum Viable Product
- **AC**: Acceptance Criteria
- **UAT**: User Acceptance Testing

## 참고

@templates/prd-template.md
@docs/user-research-guide.md

개인 전역 설정

# 나의 Claude Code 설정

## 응답 스타일

- 한국어로 응답
- 존댓말 사용
- 간결하게 (핵심 먼저, 상세 나중)

## 선호하는 형식

- 비교: 표(table) 사용
- 단계: 번호 리스트
- 명령어/코드: 코드블록

## 금지

- 이모지 사용하지 않기
- 불필요한 인사말 생략
- 확실하지 않은 정보 단정적으로 말하지 않기

## 자주 쓰는 도구

- 문서: 마크다운
- 표: 깃허브 스타일 테이블
- 다이어그램: Mermaid

조건부 규칙 (rules)

특정 파일이나 폴더에만 적용되는 규칙을 설정할 수 있습니다.

폴더 구조

.claude/
└── rules/
    ├── reports.md         # /reports 폴더에 적용
    ├── emails.md          # /emails 폴더에 적용
    └── presentations.md   # /presentations 폴더에 적용

규칙 파일 형식

---
paths:
  - "reports/**"
  - "*.report.md"
---

# 보고서 작성 규칙

## 형식

- 제목은 날짜로 시작: YYYY-MM-DD
- 요약 섹션 필수 (3줄 이내)
- 3페이지(A4) 이내

## 톤

- 객관적, 사실 중심
- 추측 표현 금지 ("~인 것 같다" X)
- 데이터 기반 주장

## 구조

1. 요약
2. 배경
3. 본문
4. 결론
5. 다음 단계

YAML frontmatter 옵션

필드	설명	예시
`paths`	적용할 경로 패턴	`["reports/*", ".md"]`
`globs`	glob 패턴 (paths와 동일)	`["*/.json"]`

활용 예시

이메일 템플릿 규칙 (.claude/rules/emails.md)

---
paths:
  - "emails/**"
---

# 이메일 작성 규칙

## 형식

- 제목: [카테고리] 실제 제목
- 인사말 포함
- 서명 포함

## 톤

- 공손하지만 간결
- 요청사항은 명확하게
- 마감일 명시

데이터 파일 규칙 (.claude/rules/data.md)

---
paths:
  - "data/**"
  - "*.csv"
  - "*.json"
---

# 데이터 파일 규칙

## 금지

- 원본 데이터 직접 수정 금지
- 개인정보 포함 파일 외부 노출 금지

## 작업 방식

- 원본 복사 후 작업
- 변경 이력 기록

다른 파일 참조하기

@ 문법

CLAUDE.md가 길어지면 다른 파일을 참조할 수 있습니다:

## 스타일 가이드

@docs/style-guide.md

## API 문서

@docs/api-reference.md

## 템플릿

@templates/report-template.md

언제 사용하나?

CLAUDE.md가 500줄을 넘어갈 때
여러 프로젝트에서 공유하는 규칙
자주 변경되는 참고 자료
팀원별로 다른 설정이 필요할 때

Claude에게 CLAUDE.md 작성 요청하기

직접 작성하기 어려우면 Claude에게 요청하세요:

> 이 프로젝트를 위한 CLAUDE.md 파일을 만들어줘.
>
> 프로젝트: [프로젝트 설명]
> 목적: [목적]
> 주요 규칙: [규칙들]
>
> 프로젝트 루트에 CLAUDE.md로 저장해줘.

기존 CLAUDE.md 개선 요청

> 현재 CLAUDE.md를 검토하고 개선해줘.
> 더 명확하게 만들어줘.

체크리스트

CLAUDE.md 작성 시 확인할 것:

프로젝트 목적이 1-2문장으로 명확한가?
핵심 규칙이 구체적인가?
금지 사항이 명시되어 있는가?
500줄 이하인가?
예시가 포함되어 있는가?
팀과 공유 가능한가? (민감 정보 제외)

참고 자료

리소스	설명
Claude Code Memory 문서	공식 CLAUDE.md 문서
Best Practices	Anthropic 권장 사항
Builder.io CLAUDE.md 가이드	커뮤니티 상세 가이드
claude-code-showcase	CLAUDE.md 예제 모음

다음 단계

CLAUDE.md로 프로젝트 맥락을 설정했다면, 스킬 시스템으로 반복 작업을 자동화하는 방법을 배워봅시다.

→ 3장. 스킬 시스템 - 재사용 가능한 능력 만들기

← 1장. 시작하기 - 설치부터 첫 대화까지 3장. 스킬 시스템 - 재사용 가능한 능력 만들기 →