CLAUDE.md — 프로젝트의 두뇌
단일 markdown 파일로 Claude에게 영구 context 주기
⏱ 예상 ~4분
01 · 읽기
새 Claude Code session 을 열 때마다 Claude 는 백지에서 시작해요. 지난 대화도, 코드 스타일도, 프로젝트 관례도, 어떤 프레임워크를 쓰는지도 기억하지 않아요. 매번 모든 걸 다시 설명해야 하죠.
CLAUDE.md 가 이걸 해결해요. Claude가 모든 session 시작에 읽는 markdown 파일 — 프로젝트의 영구 지시서예요.
💡 상상해 봐요CLAUDE.md 를 새 팀원의 onboarding 문서라고 생각해요. 매일 아침 팀 관례를 설명하는 대신 한 번 써두는 거예요. CLAUDE.md 가 바로 그 문서고, Claude 는 "일을 시작"할 때마다 그걸 읽어요.
핵심 정리
- 모든 Claude Code session 은 처음부터 시작해요 — 과거 대화를 기억 안 해요
- CLAUDE.md 는 모든 session 시작에 자동 로드돼요
- 프로젝트 규칙, 관례, 중요한 context 를 Claude에게 알려줘요
- 그냥 markdown 파일이에요 — 다른 파일처럼 편집하면 돼요
02 · 읽기
CLAUDE.md 는 세 곳에 둘 수 있고, 각각 scope 가 달라요.
Project level — CLAUDE.md 를 repo root (또는 .claude/CLAUDE.md) 에 둬요. git 으로 팀과 공유해요. 프로젝트 관례, build 명령, 아키텍처 패턴에 써요.
User level — ~/.claude/CLAUDE.md 에 둬요. 개인용이고 모든 프로젝트에 적용돼요. 개인 선호도에 써요.
서브디렉터리 — 서브디렉터리의 CLAUDE.md 파일은 Claude가 그 디렉터리의 파일을 읽을 때 필요에 따라 로드돼요. 모듈별 지시에 적합해요.
핵심 정리
- Project level (./CLAUDE.md): 팀과 공유, git 에 commit
- User level (~/.claude/CLAUDE.md): 개인용, 모든 프로젝트에
- 서브디렉터리 CLAUDE.md: 특정 모듈에 필요시 로드
- 충돌 시 프로젝트 규칙이 사용자 규칙을 덮어써요
03 · 코드 예제
좋은 CLAUDE.md 는 build 명령, 코드 스타일, 아키텍처, 프로젝트별 관례를 포함해요. 아래는 실제 예시예요.
예시 CLAUDE.md
# Build & Test
- `npm run dev` — start frontend dev server
- `npm run build` — TypeScript check + production build
- `npm test` — run tests (Vitest)
# Code Style
- TypeScript strict mode, ES modules (import/export)
- 2-space indentation, single quotes
- Functional React components, no class components
# Architecture
- API routes in `server/src/routes/`
- Database schema in `server/src/db/schema.ts`
- Frontend components in `src/components/`
# Important
- The `--color-purple` CSS variable is actually orange (#FF6B35)
- Auth cookies use sameSite: 'none' for cross-origin
무엇이 포함됐는지 보세요. Claude가 코드만 읽어서는 알아낼 수 없는 것들이에요. Build 명령, 특이한 명명 관례, cross-origin 관련 잔재. Claude가 둘러보면 알 수 있는 건 빼세요 — 명백하지 않은 것에 집중하세요.
04 · 코드 예제
CLAUDE.md 가 커지면 import 와 rules 디렉터리로 집중된 파일들로 쪼갤 수 있어요.
@import 가 있는 CLAUDE.md
# Project Overview
See @README.md for project description
See @specs/ARCHITECTURE.md for system design
# Code Style
@docs/code-style.md
Rules 디렉터리 구조
.claude/
├── CLAUDE.md (main instructions)
└── rules/
├── api-design.md (API conventions)
├── testing.md (test patterns)
└── security.md (security rules)
@ 접두사가 다른 파일의 내용을 CLAUDE.md 로 import 해요. .claude/rules/ 디렉터리는 주제별 규칙을 담고, Claude가 자동 로드해요. 메인 CLAUDE.md 는 깔끔하게 유지하면서 Claude에게 자세한 도메인 지식 접근권을 줘요.
05 · 퀴즈
팀의 모든 개발자가 따라야 할 프로젝트 관례가 있어요. CLAUDE.md 를 어디에 두고 팀과 공유해야 할까요?
- 내 홈 디렉터리 (~/.claude/CLAUDE.md)
- Repo root (./CLAUDE.md), git 에 commit
- README 에 링크된 Google Doc
- Slack 채널의 고정 메시지
06 · 빈칸 채우기
다른 파일을 CLAUDE.md 로 import 하려면 경로 앞에 _____ 를 붙여요
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.