CLAUDE.md 완벽 가이드 2026 — AI가 내 규칙을 기억하게 만드는 법

Claude Code를 처음 쓸 때 제일 답답한 게 뭔지 아세요? 어제 분명히 "TypeScript에서 any 쓰지 마"라고 했는데, 오늘 새 세션 열면 또 any가 나와 있어요. 매 세션마다 같은 말을 반복해야 하는 상황. 이게 싫어서 찾은 게 바로 CLAUDE.md입니다.

CCLAUDE.md 란?

 

CLAUDE.md가 뭔지 정확히 알고 시작하자

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 마크다운 파일입니다. 공식 문서 표현을 빌리면 "context, not enforced configuration"인데, 쉽게 말하면 "AI한테 보내는 영구 메모"예요.

여기에 코딩 표준, 아키텍처 결정, 선호 라이브러리를 적어두면 Claude가 매번 그걸 읽고 일을 시작합니다. 세션이 끊겨도 규칙은 살아있어요.

그럼 언제 뭔가를 추가해야 할까요? 공식 문서에서 권장하는 타이밍이 딱 세 가지입니다. Claude가 같은 실수를 두 번 반복했을 때, 코드 리뷰에서 "이건 Claude가 알았어야 하는 거잖아" 싶은 피드백이 나왔을 때, 그리고 지난 세션이랑 똑같은 교정을 또 타이핑하고 있을 때. 이 세 상황이 오면 그냥 CLAUDE.md에 박아버리면 됩니다.

 

CLAUDE.md 파일이 있는 위치 — 5단계 계층 구조

파일 하나가 아닙니다. Claude Code는 5단계로 나뉜 계층 구조를 읽어요. 더 좁은 범위의 파일이 더 나중에 읽혀 우선 적용되는 방식입니다.

단계	위치	공유 대상
Managed Policy	Windows: C:\Program Files\ClaudeCode\CLAUDE.md	조직 전체
User	~/.claude/CLAUDE.md	나 혼자, 모든 프로젝트
Project	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 전체 (git 커밋)
Local	./CLAUDE.local.md	나 혼자 (gitignore)
서브디렉토리	./apps/web/CLAUDE.md	해당 서브트리만

저도 처음엔 프로젝트 루트에 하나만 만들면 된다고 생각했는데, 계층 구조를 이해하고 나서 완전히 달라졌어요. User 레벨에는 제 개인 코딩 습관(탭 대신 스페이스, 커밋 메시지 형식 등)을 넣고, Project 레벨에는 팀 공통 규칙을, Local 레벨에는 저만 쓰는 개인 설정을 분리했습니다.

한 가지 중요한 특성이 있어요. 서브디렉토리에 있는 CLAUDE.md는 지연 로딩됩니다. Claude가 그 디렉토리 파일을 실제로 열 때만 로드돼요. 그래서 apps/api/CLAUDE.md에 적어둔 내용은 Claude가 그 폴더를 건드릴 때부터 적용됩니다.

CLAUDE.md 5단계 계층 구조를 시각화한 다이어그램 — 피라미드 형태로 Managed Policy(최상단)부터 서브디렉토리(최하단)까지

CLAUDE.md 실전 작성법 — 구체적이어야 통한다

핵심은 구체성입니다. "코드를 깔끔하게 유지해"는 Claude한테 아무 의미가 없어요. "2스페이스 들여쓰기 사용"처럼 검증 가능한 형태여야 합니다.

파일 크기도 중요해요. 200줄 이하로 유지해야 하고, 실제로는 80~120줄이 최적입니다. 길어질수록 준수율이 급락한다는 게 현실이에요.

제가 쓰는 필터가 하나 있습니다. "이 줄을 지우면 Claude가 잘못할까?" — No라면 그냥 지웁니다. 규칙이 많다고 좋은 게 아니에요.

아래가 실제 프로젝트에 적용 중인 CLAUDE.md 예시입니다:

# Project: my-app

## Commands
- Build: `pnpm build` (Turbopack 사용 — Webpack 플래그 미적용)
- Test: `pnpm test --run` (Vitest, Jest 아님)
- Lint: `pnpm lint` (경고도 CI 실패 처리)

## 규칙
- 서버 컴포넌트가 기본값. 폼/대화형 UI만 'use client' 추가
- DB 접근은 lib/db/ 헬퍼만 사용 — 라우트 직접 SQL 금지

## 안티패턴
- 새 의존성 추가 전 PR 댓글 먼저 작성
- `any` 금지 — `unknown` 사용 후 타입 좁히기

Commands 섹션에서 중요한 건 "어떤 명령어 쓰는지"뿐 아니라 "어떤 걸 쓰면 안 되는지"도 명시하는 거예요. Vitest 프로젝트인데 jest 명령어 날리는 실수, 생각보다 자주 일어납니다.

 

CLAUDE.md @import로 파일 나누기 — 조직화 목적

CLAUDE.md가 커지면 분리하고 싶어지는데, @ 문법으로 가능합니다.

# Project Rules

@.claude/rules/code-style.md
@.claude/rules/testing.md

See @README for project overview.

.claude/rules/ 디렉토리에 역할별로 파일을 나눌 수 있어요. 더 나아가 YAML frontmatter로 경로 스코프도 지정됩니다:

---
paths:
  - "src/api/**/*.ts"
---
# API 개발 규칙

paths가 있으면 해당 파일 패턴에서만 적용되고, 없으면 전체 적용이에요. 단, 주의할 점이 있습니다. @import로 분리해도 컨텍스트 절약이 되지 않아요. 조직화 목적으로만 씁시다.

HTML 주석(<!-- 노트 -->)은 컨텍스트 주입 전에 제거되니까 토큰 절약 꼼수로 쓸 수 있긴 한데, 관리가 불편해서 저는 잘 안 씁니다.

.claude/rules/ 디렉토리 구조를 보여주는 파일 트리 스크린샷

 

Auto Memory — Claude가 스스로 기억을 관리하는 방식

Claude Code v2.1.59부터 자동 메모리 기능이 생겼습니다. Claude가 빌드 명령, 디버깅 인사이트 같은 걸 직접 기록해요.

저장 위치는 ~/.claude/projects/<project>/memory/이고, MEMORY.md 파일을 매 세션 첫 200줄 또는 25KB 로드합니다. CLAUDE.md랑 다른 점은 /compact 명령어로 컨텍스트 압축을 해도 CLAUDE.md는 자동 재주입되지만, 서브디렉토리 CLAUDE.md는 재주입이 안 된다는 거예요.

버전 확인부터 하세요. v2.1.59 미만이면 이 기능 없습니다.

 

/init 명령어로 초안 자동 생성

처음 만드는 게 막막하면 /init 명령어 쓰면 됩니다. Claude가 프로젝트를 분석해서 CLAUDE.md 초안을 자동으로 만들어줘요. 단, 자동 생성 결과를 그대로 쓰면 안 됩니다. 반드시 직접 편집해야 해요. 자동 생성본엔 너무 일반적인 내용이 많이 들어가거든요.

Claude Code 터미널에서 /init 명령어 실행 후 CLAUDE.md가 생성되는 과정

CLAUDE.md가 무시될 때 점검 리스트

직접 써보고 가장 많이 겪은 문제들입니다.

원인	해결법
파일 길이 초과	200줄 이하로 축소
모호한 표현	구체적이고 검증 가능하게 재작성
이유 없는 규칙	각 규칙에 한 문장 이유 추가
컨텍스트 압축	/clear 또는 새 세션 시작
파일명 오류	CLAUDE.md 대소문자 확인

파일명 오류가 생각보다 많아요. claude.md로 소문자로 만들어도 macOS에서는 동작하는데 리눅스 환경에서는 안 읽히는 경우가 있거든요. 대문자로 통일하세요.

 

CLAUDE.md vs Cursor .cursorrules — 뭐가 다를까

Cursor도 쓰는 분들이 궁금할 텐데, 간단히 비교하면 이렇습니다:

항목	CLAUDE.md	.cursor/rules/
지원 도구	Claude Code 전용	Cursor IDE 전용
계층 구조	5단계	Team>Project>User
@import	지원 (최대 4단계)	미지원
로컬 파일	CLAUDE.local.md	별도 없음
조직 정책	Managed Policy 지원	미지원

두 파일은 같은 저장소에 공존할 수 있어요. 충돌 없이 각자 동작합니다.

 

CLAUDE.md 자주 묻는 질문 (FAQ)

Q. CLAUDE.md에 민감한 API 키나 패스워드를 적어도 되나요?
A. 절대 안 됩니다. CLAUDE.md는 보통 git에 커밋되기 때문에 민감 정보가 그대로 올라갑니다. API 키 같은 건 .env 파일에 두고 gitignore 처리하세요. CLAUDE.local.md는 팀과 공유되지 않는 로컬 파일이지만, 여기서도 민감 정보는 피하는 게 맞습니다.

Q. CLAUDE.md가 너무 길어지면 어떻게 정리하나요?
A. 200줄 기준으로 잘라야 합니다. 역할별로 .claude/rules/ 하위에 파일을 나누고 @import로 불러오는 방식이 좋아요. 그래도 길면 "이 줄이 없으면 Claude가 실수할까?"를 기준으로 줄을 쳐냅니다.

Q. 서브디렉토리 CLAUDE.md는 언제 로드되나요?
A. Claude가 해당 디렉토리의 파일을 실제로 열 때 로드됩니다. 세션 시작 시 전부 로드되는 게 아니에요. 그래서 apps/api/ 폴더를 건드리기 전까지는 그 안의 CLAUDE.md가 적용되지 않습니다.

Q. /compact 후 CLAUDE.md 내용도 사라지나요?
A. 프로젝트 루트 CLAUDE.md는 /compact 후에도 자동으로 재주입됩니다. 서브디렉토리 CLAUDE.md는 재주입이 안 되므로, 중요한 규칙은 루트 파일에 두는 게 안전합니다.

 

CLAUDE.md, 지금 바로 만들어보는 게 빠릅니다

이론만 보면 복잡해 보이지만, 실제로는 간단해요. 지금 쓰는 프로젝트 루트에 CLAUDE.md 파일 하나 만들고, Commands 섹션 세 줄, Rules 섹션 다섯 줄부터 시작하세요. 쓰다 보면 추가할 게 자연스럽게 생겨요.

저는 처음 만든 CLAUDE.md가 12줄이었는데, 지금은 95줄짜리가 됐습니다. 그 사이에 "또 같은 말 하네" 싶었던 순간마다 한 줄씩 추가한 거예요.