CLAUDE.md 가이드: 무엇이고 어떻게 작성하나 (템플릿 포함, 2026)

Jasmine(Claude Code를 매일 쓰고, 실제 프로젝트를 위해 CLAUDE.md 파일을 쓰고 다듬는 개발자).

CLAUDE.md란?

Claude Code가 이 프로젝트는 npm이 아니라 pnpm을 쓴다는 걸 자꾸 "잊거나", 기존 파일을 수정하지 않고 새 파일을 만들어 버려서 짜증났던 적이 있다면, 바로 그때 빠져 있던 게 CLAUDE.md예요.

CLAUDE.md는 프로젝트 루트에 두는 Markdown 파일로, 세션이 시작되는 순간 Claude Code가 자동으로 컨텍스트에 읽어들여 프로젝트 전체에 적용되는 지속적인 시스템 지침으로 작동해요. 다시 말해, 새 세션을 열 때마다 "이 프로젝트는 TypeScript를 써, 테스트는 명령어 X로 실행해, 디렉터리 Y는 건드리지 마"라고 다시 입력하는 대신, 그 규칙을 CLAUDE.md에 한 번만 적어 두는 거예요. 에이전트는 이미 코드베이스를 아는 동료가 건네는 브리핑을 읽듯이 그걸 읽어요.

핵심 구분: CLAUDE.md는 매번 붙여넣기를 기억해야 하는 프롬프트가 아니고, 사람 독자를 위한 문서도 아니에요. 에이전트를 위한 컨텍스트로, 짧고 명령형이며 Claude가 올바른 판단을 내리도록 돕는 데 초점을 맞춰 작성해요. 구체적이고 정확할수록 에이전트가 덜 흔들려요. Claude Code가 무엇인지 아직 잘 모르겠다면, 먼저 Claude Code가 무엇인지를 읽고 여기로 돌아오세요.

다른 방식으로 그려 볼게요. 새 개발자를 온보딩할 때 매일 아침 모든 걸 다시 설명하고 싶지는 않잖아요. 온보딩 페이지 하나를 써 두면 그 사람이 읽고 스스로 일하게 되죠. CLAUDE.md가 바로 그 온보딩 페이지예요——다만 에이전트용이고, 모든 세션마다 자동으로 다시 읽혀요. 이 파일에 투자할 가치가 있는 이유도 그거예요. 한 번 잘 써 두면 이후 이어지는 수백 번의 세션에 걸쳐 효과가 쌓여요. Anthropic의 베스트 프랙티스 가이드에 따르면, 첫 시도에 완벽하게 쓰려 하기보다 CLAUDE.md를 시간을 두고 조금씩 다듬는(살아 있는 프롬프트처럼 다루는) 편이 눈에 띄게 더 잘 작동해요.

CLAUDE.md는 어떻게 작동하나요? (왜 에이전트가 따르는가)

원리는 정말 단순해요. 프로젝트 디렉터리 안에서 세션을 열면, Claude Code가 CLAUDE.md 파일을 찾아 여러분의 첫 프롬프트보다 먼저 컨텍스트 맨 앞에 읽어들여요. 여러 계층이 한꺼번에 로드돼요.

• 프로젝트 루트 - ./CLAUDE.md. 저장소 전체에서 공유하는 규칙(프로젝트에 참여하는 모두에게 로드됨).
• 개인 파일 - ~/.claude/CLAUDE.md. 모든 프로젝트에 적용되는 여러분 자신의 선호 설정.
• 상위/하위 디렉터리 - Claude Code는 디렉터리 트리를 위로 훑고, 작업 중인 하위 디렉터리 안의 CLAUDE.md도 읽어요. 그래서 특정 모듈에만 해당하는 규칙을 그 모듈 바로 옆에 둘 수 있어요.

이 내용이 컨텍스트 맨 앞에 놓이기 때문에 초두 효과(primacy bias)의 영향을 받아요——모델은 앞에 나오는 것에 더 강하게 "귀 기울이는" 경향이 있거든요. 그래서 가장 중요한 제약("하지 마" 경계)은 파일 맨 위에 두어야 하고, 긴 문단 중간에 묻어 두면 안 돼요.

솔직한 주의점 하나. CLAUDE.md는 강력한 Claude Code 컨텍스트를 만들지만, 깨지지 않는 절대 법칙은 아니에요. 컨텍스트가 가득 차거나 파일이 너무 길어지면 신호가 옅어지고 에이전트가 놓칠 수 있어요. 에이전트가 실제로 읽었는지 확인하는 가장 빠른 방법은 바로 물어보는 거예요. "CLAUDE.md에 따르면 테스트 실행 명령어가 뭐야?"——정확히 답하면 여러분의 프로젝트 메모리가 컨텍스트에 들어간 거예요.

CLAUDE.md의 3가지 종류와 두는 위치

파일이 하나뿐이라고 여기는 사람이 많지만, 실제로는 스코프가 세 가지예요. 각각을 어디에 두는지 알면 모든 걸 한 파일에 욱여넣지 않아도 돼요.

CLAUDE.local.md는 프로젝트별 개인 메모용으로, 비공개이자 미커밋 파일이에요——나만 필요한 샌드박스 URL이나 로컬 테스트 데이터를 넣죠. 이 글을 쓰는 시점(2026-08-20)의 공식 문서에 따르면, 이 파일은 일부 오래된 가이드가 주장하듯 폐기(deprecated)된 게 아니라 여전히 완전히 지원돼요——CLAUDE.md와 나란히 로드되고 똑같이 취급되며, 여러분은 .gitignore에 추가하기만 하면 돼요. 같은 프로젝트의 여러 워크트리를 오가며 작업하고 그 사이에 개인 메모를 공유하고 싶다면, 문서는 각 워크트리에 내용을 복제하는 대신 홈 디렉터리에서 @~/.claude/my-project-instructions.md처럼 임포트하기를 권해요——이 문법은 버전에 따라 바뀔 수 있으니 의존하기 전에 다시 확인하세요. "CLAUDE.md를 어디에 두지?"에 대한 짧은 답을 원한다면: 팀 규칙은 저장소 루트에, 개인 선호는 사용자 파일에, 미커밋 메모는 CLAUDE.local.md에, 모듈별 예외는 하위 디렉터리에 두세요.

CLAUDE.md에 무엇을 담아야 하나요? (6개 핵심 섹션)

이게 가장 중요한 질문이에요——그리고 부실한 파일 대부분은 엉뚱한 걸 담아서 실패해요. ROI 높은 순으로 정렬한, 가질 만한 여섯 섹션은 다음과 같아요.

1. 명령어(ROI 최고). 테스트, 빌드, lint, 개발 서버 실행 방법. 에이전트가 명령어를 가장 자주 틀리기 때문에, 여기서 시간을 가장 많이 아껴요. 예: pnpm test, pnpm build, pnpm lint.
2. 기술 스택 + 버전. 언어, 프레임워크, 패키지 매니저, DB. 예: "Next.js 15(App Router), TypeScript strict, pnpm, PostgreSQL + Prisma". 에이전트가 낡은 API에 손대는 걸 막아 줘요.
3. 디렉터리 구조 - 항목당 한 줄. 예: "app/ 라우트, components/ UI, lib/ 공용 헬퍼". 새 파일을 어디에 둘지 에이전트가 알 정도면 충분해요.
4. 코드 규약. 네이밍, import 순서, 에러 처리, 테스트 스타일. 틀리기 쉬운 것들을 짚어 주고, 스타일 가이드 전체를 복사하지는 마세요.
5. "하지 마(do NOT)" 경계. 가장 큰 차이를 만드는 섹션이고, 맨 위 가까이에 두어야 해요. 예: "기존 파일을 수정할 수 있으면 새 파일을 만들지 마", "요청받지 않으면 커밋하지 마", "이미 적용된 migrations/ 폴더는 건드리지 마".
6. 상세 문서로 가는 @path 임포트. 긴 문서를 인라인으로 붙여넣는 대신 그쪽을 가리키세요: @docs/architecture.md. 이렇게 하면 메인 파일을 가볍게 유지하면서도, 필요할 때 에이전트가 세부로 들어갈 길을 남길 수 있어요(점진적 공개). 사람들이 자주 틀리는 점 몇 가지: 상대 경로는 여러분의 cwd가 아니라 임포트하는 파일을 기준으로 해석돼요. 임포트 중첩은 4단계까지이고, 그보다 깊으면 무시돼요. 경로를 임포트 없이 문자 그대로 언급하려면 백틱으로 감싸세요. 예: `@README`.

걸러내는 규칙: 어떤 줄이 에이전트가 다른 결정을 내리도록 돕지 않는다면 지우세요. CLAUDE.md는 README가 아니에요. README는 사람 독자에게 프로젝트를 설명하고, CLAUDE.md는 에이전트에게 어떻게 행동할지 알려 줘요. 목적이 둘로 다르니 섞지 마세요. 섞으면 에이전트가 무엇을 할지 정할 때 실제로는 필요 없는 내용으로 파일이 부풀어요.

표준 CLAUDE.md 템플릿(복붙)

아래는 전형적인 Next.js + TypeScript 프로젝트용 완성된, 작동하는 템플릿이에요. 이것이야말로 많은 가이드가 빠뜨리는 것, 즉 그대로 붙여 바로 쓰고 이후 자기 프로젝트에 맞게 덜어 낼 수 있는 파일이에요.

이 템플릿을 복사한 뒤 프로젝트에 맞게 조정하세요: 기술 스택, 명령어, 디렉터리 구조를 여러분 것으로 바꾸세요. "하지 마" 섹션은 맨 위에 그대로 두고요.

# CLAUDE.md

Web app for managing clinic appointment scheduling. Priority: correct business logic > coding speed.

## Do NOT (read first)
- Do NOT create a new file if you can edit an existing one.
- Do NOT commit/push unless explicitly asked.
- Do NOT edit files in `prisma/migrations/` that already ran - create a new migration.
- Do NOT use `any` in TypeScript. Do NOT disable lint to get past errors.

## Tech stack
- Next.js 15 (App Router) + TypeScript (strict)
- pnpm (do NOT use npm/yarn)
- PostgreSQL + Prisma
- Tailwind CSS + shadcn/ui
- Vitest (unit) + Playwright (e2e)

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test` # single file: `pnpm test path/to/file`
- Build: `pnpm build`
- Lint: `pnpm lint`
- DB: `pnpm prisma migrate dev`

## Directory structure
- `app/` - routes (App Router)
- `components/` - reusable UI
- `lib/` - shared helpers, no JSX
- `server/` - server-side logic, DB queries
- `prisma/` - schema + migrations

## Code conventions
- Components: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE.
- Prefer named exports; absolute imports via the `@/` alias.
- Error handling: throw `AppError` (see `lib/errors.ts`), never swallow errors silently.
- Every new feature ships with a test.

## Workflow
- Before calling anything done: run `pnpm lint` and `pnpm test`, fix all errors.
- Large changes: describe a short plan before editing many files.

## Detailed docs (import when needed)
@docs/architecture.md
@docs/api-conventions.md

할 것과 하지 말 것: 틀린 예 → 맞는 예

에이전트가 따르는 파일과 무시하는 파일의 차이는 보통 길이가 아니라 표현에 있어요. 실제 전/후 사례 몇 가지예요.

황금률: 프로젝트에 대해 아직 아무것도 모르는 똑똑한 신입 개발자에게 브리핑하듯 쓰세요——구체적으로, 명령형으로, 짧게. 모호한 줄("깨끗한 코드를 써라", "베스트 프랙티스를 따라라")은 거의 쓸모없어요. 에이전트가 측정할 수 없으니까요. "깨끗한 코드를 써라"는 "함수는 최대 40줄, 넘으면 분할"로, "에러를 신중히 처리해라"는 "AppError를 throw하고 빈 try/catch는 금지"로 바꾸세요. 측정 가능한 것이야말로 에이전트가 따를 수 있는 거예요. 파일에서 참조하고 싶은 Claude Code 명령어 전체를 보려면 Claude Code 명령어 치트시트를 확인하세요.

CLAUDE.md를 가볍고 토큰 효율적으로 유지하기

흔한 오해가 있어요: 파일이 길수록 에이전트가 프로젝트를 더 "이해한다"는 거예요. 사실은 반대예요. CLAUDE.md는 모든 세션의 컨텍스트 창을 잡아먹고, 부풀수록 중요한 한 줄이 수십 개의 잡음 속에 파묻혀요——신호가 얇아지고, 하필 여러분이 가장 필요로 한 바로 그것을 에이전트가 놓치기 쉬워져요. 이건 단순한 직관이 아니에요. 그 근거는 AGENTS.md/CLAUDE.md 컨텍스트 파일이 정말 작동하는지를 참고하세요.

실무 경험칙: 대략 200줄을 목표로, 대형 프로젝트라면 상한은 대략 300~500줄이에요. 그걸 크게 넘어가면 무언가를 떼어 내야 한다는 신호예요. CLAUDE.md를 최적으로 유지하는 방법:

• 임포트를 통한 점진적 공개. 메인 파일은 "결정을 위한 목차"로 유지하고, 긴 세부(아키텍처, API 규약)는 별도 파일로 밀어내 @docs/...로 가리키세요.
• 행동을 바꾸지 않는 건 잘라내기. 프로젝트 연혁, 홍보 문구, 장황한 설명 — 전부 버리세요.
• 중복 병합. 기술 스택에서 이미 "pnpm을 써라"라고 했다면 다른 세 곳에서 반복할 필요 없어요.
• ROI로 우선순위. 명령어와 경계는 맨 위에, "알아 두면 좋은" 내용은 맨 아래나 임포트로 옮기세요.

.claude/rules/로 경로별 규칙 분할하기

프로젝트가 커지면 모든 규약을 점점 길어지는 하나의 CLAUDE.md에 욱여넣는 방식은 한계에 부딪혀요. 대신 Claude Code에서는 지침을 .claude/rules/ 아래 여러 작은 파일로 나눌 수 있고, 각 파일이 한 영역을 맡아요.

.claude/rules/
├── code-style.md
├── testing.md
└── security.md

각 규칙 파일에 YAML 프론트매터를 달아 paths: 필드로 로드 시점을 좁힐 수 있어요.

---
paths:
  - "src/api/**/*.ts"
---
Validate all input with Zod before writing to the DB.

paths:가 없는 규칙(스코프 없음)은 ./CLAUDE.md와 같은 우선순위로 매 세션 로드돼요. paths:가 있는 규칙은 Claude가 그 글롭에 맞는 파일을 열 때만 로드돼요——이게 바로 컨텍스트를 아끼는 이유예요. CSS를 편집하는 동안 API 라우트 규약에 토큰을 치르지 않으니까요. ~/.claude/rules/는 개인용이고, 여러분의 모든 프로젝트에 적용되며, 프로젝트 레벨 규칙보다 먼저 로드돼요.

이건 더 넓은 토큰 관리 전략과 이어져요——.claude/rules/가 더 큰 토큰 예산 그림에서 어디에 들어가는지는 Claude Code에서 컨텍스트와 메모리 관리하기를 참고하세요.

빠른 팁: /init과 # 키

CLAUDE.md를 처음부터 쓸 필요는 없어요. 두 가지 내장 도구가 작업을 훨씬 빠르게 해 줘요.

• /init - 이 명령어를 프로젝트에서 실행하면 Claude Code가 저장소를 스캔해 시작용 CLAUDE.md를 생성해 줘요(기술 스택, 명령어, 구조를 추측해서). 그대로 받아들이지 말고 초안으로 여기고, 위의 여섯 핵심 섹션까지 다듬어 내세요.
• # 키 - 작업 중 #에 이어 메모를 입력하면 Claude Code가 그것을 CLAUDE.md에 저장할지 제안해요(프로젝트 파일 또는 사용자 파일을 고를 수 있어요). 기록할 가치가 있는 규약을 발견한 순간, 세션 도중에 프로젝트 메모리를 추가하는 방법이에요——에디터를 열려고 멈출 필요 없이요.

이제 막 시작한다면 가장 군더더기 없는 흐름은 이래요: /init 실행 → 위 템플릿까지 파일 다듬기 → # 키로 시간을 두고 키우기. Claude Code를 시작하는 10단계가 이 전체 흐름을 안내해요.

키트에 준비된 CLAUDE.md 표준(AgentKit)

좋은 CLAUDE.md를 직접 쓰려면 몇 번의 시행착오가 필요해요. 지름길을 원한다면, AgentKit 번들(표준 CLAUDE.md 규약 포함) 같은 일부 키트는 CLAUDE.md 규약을 규칙/스킬과 함께 일관된 표준으로 묶어 줘서 백지에서 시작하지 않아도 돼요. 여러분 프로젝트의 명령어와 경계를 선언하는 일을 대신해 주지는 않지만, 발판 작업과 프로젝트마다 반복되는 규약은 아껴 줘요——AgentKit 사용해 보기(링크로 20% 할인)로 샘플 구조를 보고 여러분에게 맞는 부분만 챙기세요.

자주 묻는 질문(FAQ)

CLAUDE.md 파일명은 대소문자를 구분하나요?

네. 이름 부분을 전부 대문자로 해서 정확히 CLAUDE.md로 지으세요. 대소문자를 구분하는 시스템(Linux, CI에서 흔함)에서는 claude.md 같은 잘못된 이름이면 Claude Code가 파일을 인식하지 못할 수 있어요.

CLAUDE.md를 git에 커밋해야 하나요?

프로젝트 루트 파일은 네——공유 규약이니 커밋하면 팀 전체가 같은 컨텍스트로 작업해요. 반면 ~/.claude/CLAUDE.md는 개인용이라 저장소에 넣지 않아요. 프로젝트별 개인 메모는 커밋이 아니라 사용자 파일이나 임포트에 두는 게 맞아요.

Claude가 CLAUDE.md를 따르지 않으면요?

보통 세 가지 원인 중 하나예요: 파일이 너무 길어 신호가 옅어졌거나, 중요한 규칙이 중간에 묻혔거나, 컨텍스트가 이미 가득 찼거나. 해결책: 파일을 줄이고, "하지 마" 제약을 맨 위로 옮기고, 특정 규칙에 대해 에이전트에게 물어 정확히 답하는지 확인하세요.

CLAUDE.md가 Cursor나 다른 도구에서도 작동하나요?

CLAUDE.md는 Claude Code의 규약이에요. 다른 도구는 자체 컨텍스트 파일(예: AGENTS.md 또는 그 도구의 규칙 파일)을 써요. 작성한 내용은 재사용할 수 있는 경우가 많지만, 파일명과 로딩 방식은 도구마다 달라요.

CLAUDE.md는 얼마나 길어야 하나요?

대략 200줄을 목표로, 대형 프로젝트는 상한 300~500줄이에요. 줄 수보다 신호 품질을 우선하세요: 에이전트의 판단을 바꾸는 것만 남기고 나머지는 임포트 파일로 밀어내세요.

프로젝트 파일은 ~/.claude/CLAUDE.md와 어떻게 다른가요?

프로젝트 파일(./CLAUDE.md)은 저장소와 팀 전체에 적용되는 규약을 담고 git에 커밋해요. 사용자 파일(~/.claude/CLAUDE.md)은 여러분의 개인 선호를 담고 모든 프로젝트에 적용되며 저장소 밖에 머물러요. 둘 다 있으면 Claude Code가 둘을 동시에 로드해요.

결론과 다음 단계

CLAUDE.md는 Claude Code로 할 수 있는 가장 작고 가장 수익률 높은 투자예요: 한 번 써 두면 에이전트가 매 세션마다 여러분의 규약을 따라요. 위 템플릿을 복사해 프로젝트에 맞게 덜어 내고, "하지 마" 제약을 맨 위에 두고, 파일을 가볍게 유지하세요. 이제 막 시작한다면 초보자를 위한 10단계를 읽으세요. 빠른 명령어 조회가 필요하면 Claude Code 명령어 치트시트를 키보드 옆에 두세요.