CLAUDE.md 작성법 완전 가이드: 프로젝트 맞춤 AI 만들기

CLAUDE.md 작성법 완전 가이드: 프로젝트 맞춤 AI 만들기

Claude Code를 사용하면서 매번 같은 규칙을 반복 설명하고 계신가요? CLAUDE.md 파일 하나면 프로젝트 규칙, 코딩 스타일, 워크플로우를 Claude에게 영구적으로 알려줄 수 있습니다. 이 글에서는 CLAUDE.md의 작성법부터 고급 활용까지 완전 정리합니다.

CLAUDE.md 작성법

---

1. CLAUDE.md란?

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 지침 파일입니다. 프로젝트별 규칙, 코딩 관례, 빌드 명령어 등을 한 번 작성해두면 매번 반복 설명할 필요 없이 Claude가 알아서 따릅니다.

핵심 특징

항목	설명
형식	Markdown (.md)
로드 시점	매 세션 시작 시 자동
영향 범위	Claude의 판단 기준에 반영
성격	권장사항 (강제가 아님)
공유	Git 커밋으로 팀과 공유 가능

CLAUDE.md가 없으면?

• 매 세션마다 "이 프로젝트는 TypeScript strict mode 쓰고..."를 반복 설명
• Claude가 프로젝트 관례를 모르고 임의로 코드 작성
• 팀원마다 다른 지침을 줘서 일관성 없는 결과

CLAUDE.md가 있으면?

• 세션 시작 시 자동으로 규칙 파악
• 프로젝트 관례에 맞는 코드 생성
• 팀 전체가 동일한 AI 지침 공유

CLAUDE.md란?

---

2. 파일 위치와 계층 구조

CLAUDE.md는 여러 위치에 둘 수 있으며, 위치에 따라 적용 범위가 달라집니다.

5가지 저장 위치

위치	경로	적용 범위	공유
관리 정책	/etc/claude-code/CLAUDE.md (Linux)	조직 전체 (최우선)	IT 관리
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	현재 프로젝트	Git 커밋
개인	~/.claude/CLAUDE.md	모든 프로젝트	개인용
로컬	./CLAUDE.local.md	현재 프로젝트 (개인)	.gitignore
하위 디렉토리	./packages/app/.claude/CLAUDE.md	해당 폴더만	Git 커밋

로드 순서

작업 중인 폴더: /project/src/api/
↓
1. /project/src/api/.claude/CLAUDE.md (가장 구체적)
2. /project/src/.claude/CLAUDE.md
3. /project/CLAUDE.md
4. /project/.claude/CLAUDE.md
5. ~/.claude/CLAUDE.md (개인)
6. /etc/claude-code/CLAUDE.md (관리 정책)

원칙: 더 구체적인 위치의 규칙이 우선합니다. 프로젝트 규칙 > 개인 규칙.

언제 어떤 위치를 쓸까?

상황	권장 위치
팀 공유 규칙	./CLAUDE.md (Git 커밋)
개인 코딩 스타일	~/.claude/CLAUDE.md
프로젝트 내 개인 설정	./CLAUDE.local.md
모노레포 패키지별 규칙	./packages/app/.claude/CLAUDE.md
회사 전체 보안 정책	/etc/claude-code/CLAUDE.md

파일 위치와 계층 구조

---

3. CLAUDE.md 만들기

방법 1: /init으로 자동 생성

가장 쉬운 방법입니다. Claude가 프로젝트를 분석해서 자동으로 만들어줍니다.

$ claude
> /init

Claude가 자동으로 감지하는 항목:

• 빌드 시스템 (npm, yarn, cargo, gradle 등)
• 테스트 프레임워크 (Jest, pytest, RSpec 등)
• 코드 스타일 도구 (ESLint, Black, Prettier 등)
• 프로젝트 구조

방법 2: 직접 작성

프로젝트 루트에 CLAUDE.md 파일을 직접 만듭니다.

# 프로젝트 가이드

## 빌드 및 테스트
- 설치: npm install
- 테스트: npm test
- 빌드: npm run build

## 코드 스타일
- TypeScript strict mode
- 변수명: camelCase
- 들여쓰기: 2칸 스페이스

## 워크플로우
- 커밋 전: npm run lint && npm test
- 브랜치: feature/설명 형식

방법 3: /memory로 편집

기존 CLAUDE.md를 편집하거나 확인하려면:

> /memory

로드된 모든 CLAUDE.md 목록이 표시되고, 각 파일을 에디터로 열 수 있습니다.

CLAUDE.md 만들기

---

4. 무엇을 넣어야 할까?

반드시 넣어야 할 내용

항목	예시	이유
빌드/테스트 명령	npm test, cargo build	Claude가 추측 불가
코드 스타일	2칸 들여쓰기, camelCase	기본값과 다를 때
금지 사항	.env 수정 금지	보안/안전 규칙
파일 구조	API는 /src/api/, 모델은 /src/models/	아키텍처 결정
워크플로우	PR 전 lint 실행	팀 프로세스
명명 규칙	브랜치: feature/*, 커밋: conventional commit	관례 통일

넣지 말아야 할 내용

항목	이유	대안
일반적인 언어 규칙	Claude가 이미 알고 있음	불필요
긴 API 문서	컨텍스트 낭비	URL 링크로 대체
자주 변하는 정보	유지보수 부담	.claude/rules/ 분리
각 파일 설명	코드를 읽으면 파악 가능	아키텍처만 설명
모호한 지시	무시될 가능성 높음	구체적으로 작성

좋은 예 vs 나쁜 예

❌ 나쁜 예: "좋은 코드를 작성하세요"
✅ 좋은 예: "2칸 들여쓰기, import는 알파벳 순으로 정렬"

❌ 나쁜 예: "테스트하세요"
✅ 좋은 예: "커밋 전 npm test 실행, 모든 테스트 통과 필수"

❌ 나쁜 예: "파일을 정리하세요"
✅ 좋은 예: "API 핸들러: src/api/handlers/, 모델: src/models/"

무엇을 넣어야 할까?

---

5. 프로젝트별 실전 예시

React + TypeScript 프론트엔드

# React 컴포넌트 라이브러리

## 빌드 및 테스트
- 개발: npm run dev
- 빌드: npm run build
- 테스트: npm test
- 린트: npm run lint
- 타입 체크: npm run type-check

## 코드 스타일
- TypeScript strict mode 활성화
- 컴포넌트 구조: src/components/이름/
  - index.tsx (export)
  - 이름.tsx (구현)
  - 이름.test.tsx (테스트)
- Props: 인터페이스 정의 필수
- any 타입 사용 금지

## Git 규칙
- 브랜치: feature/설명
- 커밋 전: lint + type-check + test 통과
- PR: squash merge, conventional commit

Python Django 백엔드

# Django REST API

## 실행
- 개발: python manage.py runserver
- 테스트: python manage.py test
- 마이그레이션: python manage.py migrate
- 린트: black . && flake8

## 코드 구조
- 앱별 디렉토리: apps/auth/, apps/payments/
- 모든 API: ViewSet + Serializer 사용
- dict 응답 금지 (Serializer 필수)

## 데이터베이스
- 마이그레이션 파일 직접 수정 금지
- 새 마이그레이션 생성으로 대체
- 프로덕션 전 staging 테스트 필수

## 보안
- @login_required 필수 확인
- .env 파일 읽기/수정 금지

Rust CLI 도구

# Rust CLI 프로젝트

## 빌드 및 테스트
- 빌드: cargo build --release
- 테스트: cargo test
- 린트: cargo clippy -- -D warnings
- 포맷: cargo fmt

## 코드 규칙
- unwrap() 금지 (Result/Option 처리 필수)
- anyhow 크레이트로 에러 처리
- 각 모듈에 #[cfg(test)] 포함
- Clippy 경고 모두 해결

프로젝트별 실전 예시

---

6. .claude/rules/로 규칙 분할

CLAUDE.md가 길어지면 .claude/rules/ 디렉토리로 분할할 수 있습니다.

디렉토리 구조

프로젝트/
├── CLAUDE.md              ← 핵심 지침 (간결하게)
└── .claude/rules/
    ├── code-style.md      ← 코드 스타일 규칙
    ├── testing.md          ← 테스트 규칙
    ├── security.md         ← 보안 요구사항
    ├── frontend/
    │   └── react.md        ← 프론트엔드 규칙
    └── backend/
        └── api-design.md   ← API 설계 규칙

경로별 규칙 (Path-specific Rules)

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

---
paths:
  - "src/api/**/*.ts"
  - "tests/**/*.test.ts"
---

# API 개발 규칙

- 모든 엔드포인트: 입력 검증 필수
- 표준 에러 포맷 사용
- OpenAPI 문서 포함

위 규칙은 src/api/ 폴더에서 작업할 때만 로드됩니다. 다른 디렉토리에서는 불필요한 컨텍스트를 소비하지 않습니다.

분할 기준

CLAUDE.md에 유지	.claude/rules/로 이동
빌드/테스트 명령	상세 코드 스타일
핵심 아키텍처	패키지별 규칙
금지 사항	테스트 가이드라인
워크플로우	보안 체크리스트

.claude/rules/로 규칙 분할

---

7. 자동 메모리 (Auto Memory)

Claude는 세션 중 배운 내용을 자동으로 메모리에 저장합니다. CLAUDE.md와 함께 작동하는 보조 시스템입니다.

Auto Memory가 저장하는 것

• 빌드 명령어 발견 ("npm run build:prod가 맞네")
• 코딩 패턴 발견 ("이 프로젝트는 const를 선호하네")
• 버그 패턴 ("이 부분에서 off-by-one 에러가 자주 발생")
• 아키텍처 노하우 ("미들웨어는 /middleware에 위치")

저장 위치

~/.claude/projects/<프로젝트명>/memory/
├── MEMORY.md          ← 매 세션마다 로드 (200줄 제한)
├── debugging.md       ← 디버깅 패턴
├── api-conventions.md ← API 설계 결정
└── [기타 주제별 파일]

CLAUDE.md vs Auto Memory

항목	CLAUDE.md	Auto Memory
작성자	사용자 (수동)	Claude (자동)
내용	규칙, 지침	발견한 패턴
로드 한도	전체 파일	200줄만
수명	영구	Claude가 변경 가능
공유	Git으로 팀 공유	개인 로컬만
용도	정책 수립	학습 보조

Auto Memory 관리

# /memory 커맨드로 관리
> /memory

# 비활성화 (settings.json)
{
  "autoMemoryEnabled": false
}

자동 메모리 (Auto Memory)

---

8. 고급 기능

파일 Import (@)

CLAUDE.md 안에서 다른 파일을 참조할 수 있습니다.

# 프로젝트 가이드

프로젝트 개요는 @README.md 참고

## npm 스크립트
@package.json의 scripts 섹션 참고

## Git 워크플로우
@docs/git-instructions.md

• @경로 형식으로 파일 내용을 해당 위치에 삽입
• 상대 경로, 절대 경로 모두 지원
• 최대 5단계 깊이까지 재귀 import 가능

심링크로 팀 규칙 공유

# 회사 공용 규칙 저장소
mkdir ~/company-claude-rules

# 각 프로젝트에서 심링크 연결
ln -s ~/company-claude-rules .claude/rules/shared

규칙 저장소를 업데이트하면 모든 프로젝트에 자동 반영됩니다.

CLAUDE.local.md (개인 설정)

팀과 공유하지 않을 개인 설정은 CLAUDE.local.md에 작성합니다.

# 개인 설정 (git에 커밋하지 않음)

- 샌드박스 URL: http://localhost:3000
- 디버그 모드: 항상 켜기
- 선호하는 에디터: VS Code

.gitignore에 CLAUDE.local.md를 추가하세요.

고급 기능

---

9. 작성 모범 사례 (Best Practices)

200줄 미만 유지

CLAUDE.md가 길수록:

• 컨텍스트 윈도우를 많이 소비
• Claude가 규칙을 무시할 가능성 증가
• 유지보수 부담 증가

초과 시: .claude/rules/로 분할하거나 @import를 사용하세요.

구체적으로 작성

나쁜 예	좋은 예
"좋은 코드를 작성해"	"2칸 들여쓰기, import 알파벳순"
"테스트해"	"커밋 전 npm test, 전체 통과 필수"
"보안에 신경 써"	".env 파일 읽기/수정 절대 금지"

검증 가능한 규칙만

✅ "모든 함수에 TypeScript 반환 타입 명시"
   → Claude가 확인 가능

❌ "효율적인 알고리즘을 사용해"
   → 모호해서 검증 불가

정기적 검토

매달 CLAUDE.md 검토:
□ 오래된 규칙 제거
□ 프로젝트 변화 반영
□ 충돌하는 규칙 통합
□ 200줄 미만인지 확인

작성 모범 사례 (Best Practices)

---

10. settings.json과의 관계

CLAUDE.md와 settings.json은 역할이 다릅니다.

항목	CLAUDE.md	settings.json
성격	권장사항 (조언)	강제 규칙
예시	".env 수정하지 마세요"	.env 읽기 물리적 차단
Claude 반응	따르려 노력하지만 보장 안 됨	물리적으로 불가능
용도	코딩 지침, 워크플로우	도구 권한, 보안 정책

함께 사용하는 예시

CLAUDE.md (왜 하면 안 되는지 설명):

## 보안 규칙
- .env 파일: 시크릿이 저장되어 있으므로 절대 읽지 마세요
- prod 데이터베이스: 직접 접근 금지

settings.json (물리적으로 차단):

{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Bash(curl * prod-db *)"
    ]
  }
}

CLAUDE.md는 "왜"를 설명하고, settings.json은 "실제로 차단"합니다. 둘을 함께 쓰면 가장 안전합니다.

---

11. 트러블슈팅

Claude가 규칙을 따르지 않아요

1. /memory로 파일이 로드되었는지 확인
2. 규칙이 구체적인지 검토 (모호하면 무시됨)
3. CLAUDE.md 길이 확인 (200줄 초과면 일부 무시)
4. 충돌하는 규칙이 없는지 확인

CLAUDE.md가 로드되지 않아요

1. 파일 위치 확인: 프로젝트 루트에 있는지?
2. 파일명 확인: CLAUDE.md (대소문자 정확히)
3. /memory로 로드 목록 확인
4. 인코딩: UTF-8인지 확인

/compact 후에 규칙이 사라져요

CLAUDE.md는 세션 대화가 아니라 별도 파일이므로 /compact의 영향을 받지 않습니다. 새 세션을 시작해도 다시 로드됩니다.

만약 사라진 것처럼 보인다면, Claude에게 "CLAUDE.md 규칙을 다시 확인해줘"라고 요청하세요.

---

마무리

CLAUDE.md 작성의 핵심을 정리하면:

1. 역할: Claude에게 프로젝트 규칙을 알려주는 지침 파일
2. 위치: 프로젝트 루트 CLAUDE.md (팀 공유) + ~/.claude/CLAUDE.md (개인)
3. 내용: 빌드 명령, 코드 스타일, 금지사항, 워크플로우
4. 원칙: 200줄 미만, 구체적, 검증 가능한 규칙만
5. 고급: .claude/rules/로 분할, @import 활용, Auto Memory 연동

처음에는 /init으로 자동 생성한 뒤, 프로젝트 특수 규칙을 하나씩 추가해 나가세요. CLAUDE.md를 잘 관리하면 Claude Code가 마치 오래 함께 일한 팀원처럼 프로젝트를 이해하고 작업합니다.

다음 편에서는 메모리 시스템 심화를 다룹니다. Auto Memory, 프로젝트 메모리, 세션 간 학습 메커니즘을 상세히 살펴봅니다.

---

이전 글: [4편] Claude Code 슬래시 커맨드 완전정리: 50개+ 명령어 총 가이드
다음 글: [6편] 메모리 시스템 심화: Auto Memory와 프로젝트 메모리

---

면책 조항: 본 글은 교육 목적의 정보 제공용이며, Claude Code의 기능 및 요금제는 Anthropic의 정책에 따라 변경될 수 있습니다. 최신 정보는 공식 문서(docs.anthropic.com)를 참고하세요.