09. CLAUDE.md 메모리 파일

CLAUDE.md란

매 Claude Code 세션은 빈 컨텍스트 윈도우로 시작합니다. CLAUDE.md는 그 빈 칠판에 세션마다 자동으로 적히는 영구 지침입니다. 디렉터리에 이 파일이 있으면, 첫 프롬프트를 입력하기도 전에 그 내용이 컨텍스트에 로드되어 Claude가 "이 프로젝트가 무엇이고, 어떻게 일해야 하는지"를 알고 시작합니다.

비유하자면, 새 팀원에게 건네는 온보딩 브리프입니다. CLAUDE.md가 없으면 Claude는 매번 눈을 가린 채 프로젝트에 들어옵니다 — 구조도, 컨벤션도, 테스트 실행법도 모른 채.

📌 핵심: 한 시간 들여 좋은 CLAUDE.md를 쓰면, 같은 설명을 반복하는 수많은 시간을 아낍니다. 개인 개발자에게 가장 ROI가 높은 설정입니다.

무엇을 넣을까: WHAT-WHY-HOW

CLAUDE.md는 그냥 마크다운 파일입니다. 특별한 문법이 없어 제목·목록·코드블록·표를 자유롭게 씁니다. 넣을 가치가 있는 것과 없는 것:

📌 모든 규칙은 "위반 가능"해야 합니다. "named export를 쓰고 default export는 쓰지 마"는 따르거나 어길 수 있는 actionable한 규칙입니다. "좋은 코드를 써라"는 위반할 수조차 없으니 적을 필요가 없습니다.

⚠️ 흔한 실수: CLAUDE.md를 Claude가 스스로 알아낼 것들로 채우기. 성격 지시("단계적으로 생각해")는 Claude가 이미 하려는 일이라 지침 예산만 잡아먹습니다. 한 세션 작업하면 Claude가 알아낼 테스트 유틸 위치 같은 건 자동 메모리에 맡기세요(→ 10장).

분량 한계: 적을수록 강하다

이건 직관에 반하지만 중요합니다. 모델이 한 컨텍스트에서 안정적으로 따를 수 있는 지침은 대략 150~200개입니다. 그런데 Claude Code 자체 시스템 프롬프트가 이미 그중 약 50개를 차지합니다. 즉 당신의 CLAUDE.md가 쓸 수 있는 실효 슬롯은 100~150개 정도입니다.

flowchart LR
    A[모델의 지침 수용량<br/>~150-200개]:::know --> B[시스템 프롬프트 ~50개 차지]:::danger
    B --> C[CLAUDE.md 실효 예산<br/>~100-150개]:::result
    C --> D{200줄 넘으면}:::agent
    D -->|초과분| E[Claude가 일부를<br/>'붙잡지 못함']:::danger

    classDef know fill:#CE93D8,stroke:#8E24AA,color:#000
    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000

💡 중요한 규칙은 맨 위에. Claude는 위쪽 내용에 더 주의를 기울입니다. 구조를 "가장 중요한 규칙 먼저"로 잡으세요.

예시: 좋은 프로젝트 CLAUDE.md 골격

# Project: My App

## Tech Stack
- Frontend: React 18 + TypeScript (strict mode)
- Backend: Node.js + Express
- DB: PostgreSQL + Prisma
- Test: Vitest(unit), Playwright(E2E)

## Commands
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트/타입체크: `npm run lint && npm run typecheck`

## Code Style
- named export 사용, default export 금지
- 함수형 컴포넌트 + 훅
- 파일 300줄 이하 — 넘으면 분할

## Architecture
- 기능 기반 폴더 구조 (feature-based)
- 새 API는 src/api/ 아래, 라우트는 routes/
- src/legacy/ 는 절대 수정 금지

## Workflow
- 커밋 메시지 접두사: feat: / fix: / chore:
- 작업 끝나면 항상 린트+타입체크 실행

한계 인식: 메모리는 강제가 아니다

⚠️ 매우 중요: CLAUDE.md(와 자동 메모리)는 Claude가 컨텍스트로 취급하는 지침이지, 강제되는 설정이 아닙니다. 공식 문서도 명시하듯, 규칙 준수율은 대략 70% 수준입니다 — 안내일 뿐 명령이 아니기 때문입니다.

그래서 "무슨 일이 있어도 반드시" 지켜야 하는 것(예: 절대 rm -rf 금지, 매 커밋 전 특정 검사)은 CLAUDE.md가 아니라 다른 메커니즘을 써야 합니다:

예: "절대 rm -rf 쓰지 마"를 CLAUDE.md에 적으면 컨텍스트 압박에 잊힐 수 있지만, PreToolUse 훅으로 막으면 매번 결정 시점에 발동합니다.

모듈화: import와 path-scoped 규칙

파일이 커지면 @ import로 쪼갤 수 있습니다.

# 프로젝트 개요
@README.md
@docs/architecture.md
@~/.claude/my-personal-rules.md   # 절대 경로·홈 디렉터리도 가능

• 상대·절대 경로 모두 지원, 재귀 import 가능(최대 깊이 제한 있음).
• 외부 위치에서 처음 import할 땐 보안 승인 대화가 뜹니다.
• 코드블록·코드스팬 안의 @는 import로 해석되지 않아, 예시로 문서화해도 안전합니다.

또한 큰 모노레포라면, 특정 하위 디렉터리에서 파일을 읽을 때만 로드되는 path-scoped 규칙(예: .claude/rules/*.md)으로 "이 부분에서만 중요한 규칙"을 분리할 수 있습니다. 이렇게 하면 항상 상주할 필요 없는 지침이 평소엔 예산을 쓰지 않습니다.

CLAUDE.md 관리 팁

• 추가하기: 세션 중 "이걸 CLAUDE.md에 추가해"라고 하면 Claude가 흐름을 끊지 않고 파일을 갱신합니다.
• 점검하기: /memory로 로드된 모든 메모리 파일을 보고 편집할 수 있습니다.
• 디버깅: Claude가 규칙을 무시하는 것 같으면 /memory부터 확인하세요. 해당 규칙이 아직 안 읽힌 하위 디렉터리의 path-scoped 파일에 있을 수 있습니다.

이 장에서 배운 것

• CLAUDE.md는 매 세션 자동 로드되는 영구 지침으로, 개인 개발자에게 가장 ROI가 높은 설정이다.
• WHAT-WHY-HOW를 담되, 비밀·린터가 처리하는 스타일·Claude가 아는 일반 지식은 뺀다. 모든 규칙은 "위반 가능"해야 한다.
• 실효 지침 예산은 대략 100~150개. 고신호 파일은 80~120줄, 중요한 건 맨 위에.
• CLAUDE.md는 강제가 아니라 안내(약 70% 준수). 반드시 지켜야 할 건 Hook·deny 규칙으로.
• @ import로 모듈화하되 컨텍스트는 절약되지 않으며, path-scoped 규칙으로 부분 한정 지침을 분리한다.

✍️ 확인 문제

1. CLAUDE.md에 "시니어 개발자처럼 생각해"를 적는 것이 비효율적인 이유는 무엇인가요?
2. "무슨 일이 있어도 반드시 지켜야 하는 규칙"은 왜 CLAUDE.md가 아니라 Hook이나 deny 규칙으로 처리해야 하나요?
3. CLAUDE.md를 200줄 넘게 쓰면 어떤 일이 생기나요?

다음 장: 10. 자동 메모리와 설정 파일 — Claude가 스스로 배우는 메모리와 설정 계층.