"CLAUDE.md 작성 가이드 2026 — 넣어야 할 것 · 넣지 말아야 할 것 · 안티패턴"

-

공식 문서 기준 4가지 위치, 로딩 규칙, 200줄 상한, @import 구문, .claude/rules/까지

핵심 요약

  • 대상 독자: /init으로 CLAUDE.md는 만들어봤지만 뭘 채워야 할지 애매한 사용자.
  • 얻을 것: 공식 /memory 문서 기준 CLAUDE.md의 4가지 위치·로딩 규칙·무엇을 넣고 뺄지·효과적 작성 3원칙·@import·.claude/rules/ 분리·안티패턴 5가지.
  • 선행 조건: Claude Code 설치 완료 (설치 완전판), 슬래시 커맨드 기초 (총정리).

1. CLAUDE.md는 무엇인가

Claude Code는 세션 간 지식을 이어주는 두 메모리 시스템을 가진다.

CLAUDE.md Auto Memory
누가 쓰는가 사용자 Claude 스스로
무엇이 들어가는가 지침·규칙 학습·패턴
범위 프로젝트 / 사용자 / 조직 작업 트리별
로드 시점 매 세션 시작 매 세션 시작 (첫 200줄 또는 25KB)
적합한 용도 코딩 표준, 워크플로, 아키텍처 빌드 명령, 디버깅 인사이트, 사용자 선호

CLAUDE.md는 사용자가 직접 써서 Claude의 행동을 유도하는 파일이고, Auto Memory는 Claude가 사용자 피드백을 반영해 자동으로 누적하는 파일이다. 둘 다 시스템 프롬프트가 아니라 컨텍스트로 주입된다 — 강제 설정이 아니라 참고 자료다. 따라서 구체적이고 간결할수록 Claude가 잘 따른다.

이 글은 CLAUDE.md에 집중한다.

2. CLAUDE.md가 놓일 수 있는 4곳

범위 경로 용도 공유 대상
Managed policy macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md		 조직 전체 정책 (IT/DevOps가 배포) 조직 모든 사용자
Project ./CLAUDE.md 또는 ./.claude/CLAUDE.md 팀 공유 프로젝트 지침 버전 관리로 팀 전체
User ~/.claude/CLAUDE.md 모든 프로젝트에 적용되는 개인 선호 본인만
Local ./CLAUDE.local.md 프로젝트별 개인 메모 (.gitignore 필수) 본인만 (현재 프로젝트)

우선순위는 더 구체적인 곳이 더 높다 — 프로젝트 > 사용자 > 조직. 단, 각 위치의 내용이 override가 아니라 concatenate된다는 점에 주의. 같은 디렉터리 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙는다 (나중에 읽히므로 충돌 시 개인 메모 우선).

3. 로딩 규칙 — 디렉터리 트리를 어떻게 타는가

Claude Code는 현재 작업 디렉터리에서 상위로 올라가며 각 디렉터리의 CLAUDE.md·CLAUDE.local.md를 전부 읽는다. 예:

/home/me/monorepo/          ← CLAUDE.md (공용)
├── foo/                    ← CLAUDE.md (foo 팀)
│   └── bar/                ← CLAUDE.md (bar 기능)
│       (working directory)

이 상태로 Claude를 실행하면 3개 파일 전부 순서대로 concat되어 컨텍스트에 들어간다.

3.1 하위 디렉터리는 on-demand

반대로 하위 디렉터리의 CLAUDE.md는 launch 시 로드되지 않는다. Claude가 그 서브디렉터리의 파일을 실제로 읽을 때 로드된다. 이 덕분에 모노레포에서도 관련 없는 서브 프로젝트 지침이 컨텍스트를 오염시키지 않는다.

3.2 --add-dir은 기본 로드하지 않음

--add-dir로 추가한 디렉터리는 파일 접근만 허용할 뿐 CLAUDE.md는 자동 로드하지 않는다. 로드하려면 환경변수로:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

3.3 모노레포에서 타팀 CLAUDE.md 제외

자동 로드되는 상위 CLAUDE.md가 내 작업과 무관하다면 .claude/settings.local.json에 제외 규칙:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

단, managed policy CLAUDE.md는 제외할 수 없다 (조직 정책 보장).

4. 무엇을 넣고 무엇을 빼야 하는가

공식 문서의 권장은 단호하다. CLAUDE.md는 세션마다 토큰을 소비하므로 불필요한 내용은 adherence를 떨어뜨린다.

✅ 넣어야 할 것 ❌ 넣지 말아야 할 것
Claude가 추측 불가능한 bash 명령 (예: pnpm dev, make seed-db) Claude가 코드만 읽어도 알 수 있는 것 (package.json에 있는 script 나열)
언어 기본값과 다른 코드 스타일 규칙 표준 언어 컨벤션 (Claude가 이미 아는 것)
테스트 실행법과 선호 테스트 러너 긴 API 문서 (외부 docs 링크로 충분)
레포 에티켓 (브랜치 네이밍, PR 컨벤션) 자주 바뀌는 정보 (버전 번호, 연락처 등)
프로젝트 특유의 아키텍처 결정 긴 설명·튜토리얼
개발 환경의 기벽 (필수 환경변수 등) 파일 단위 코드베이스 설명
흔한 함정·non-obvious 동작 "깨끗한 코드를 작성하라" 같은 당연한 얘기

각 줄에 대해 묻는다: "이걸 빼면 Claude가 실수할 가능성이 생기나?" 아니라면 제거한다. 불어난 CLAUDE.md는 중요한 규칙을 묻어버린다.

5. 효과적 작성 3원칙

공식 best practices 페이지가 명시한 3가지.

5.1 크기 — 200줄 이하

목표는 CLAUDE.md 당 200줄 이하. 초과하면 컨텍스트 소모 증가 + adherence 감소. 공식 문서는 "Claude가 규칙을 반복해서 어긴다면 파일이 너무 길어서 규칙이 묻힌 것"이라고 설명한다.

이 규칙은 CLAUDE.md에만 적용. 반면 MEMORY.md는 첫 200줄 또는 25KB까지만 로드되며 그 이상은 무시된다 (Auto Memory는 자체적으로 topic 파일로 쪼개서 관리).

5.2 구조 — 헤더와 bullet으로 묶기

- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

- Typecheck after a series of changes
- Prefer running single tests, not the whole suite

스캔 가능한 구조가 dense paragraph보다 훨씬 잘 따라진다.

5.3 구체성 — 검증 가능한 수준으로

공식 예시:

애매함 (❌) 구체적 (✅)
"Format code properly" "Use 2-space indentation"
"Test your changes" "Run npm test before committing"
"Keep files organized" "API handlers live in src/api/handlers/"

강조가 필요하면 IMPORTANT: 또는 YOU MUST 같은 단어를 덧붙이면 adherence가 올라간다 (공식 권장).

6. @import 구문

CLAUDE.md는 다른 파일을 import할 수 있다. @path/to/file.

See @README.md for project overview and @package.json for available npm commands.

- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
  • 상대 경로는 파일이 있는 디렉터리 기준 (작업 디렉터리 아님).
  • 절대 경로 사용 가능.
  • 재귀 import 허용, 최대 5 hop.
  • import된 파일도 launch 시 로드되므로 컨텍스트 절약이 아니라 파일 조직용. 용량을 진짜 줄이려면 .claude/rules/의 path-scoped 규칙을 쓴다.
  • 첫 import 시 승인 다이얼로그가 뜬다. 거절 후 변경 의사 시 해당 파일을 다시 수정하고 재승인.

7. AGENTS.md와 공존 (Codex 등)

Claude Code는 AGENTS.md를 직접 읽지 않는다. 레포가 이미 AGENTS.md를 쓰고 있다면 CLAUDE.md에서 import하는 방식으로 공유한다.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

이러면 Claude는 AGENTS.md를 먼저 읽고, 그 뒤에 Claude 전용 섹션을 덧붙인다. Codex와 중복 유지 비용 없이 한 소스로 운영 가능.

8. .claude/rules/ — 대형 프로젝트 분리

CLAUDE.md 하나에 모든 규칙을 넣기 어려울 때 .claude/rules/ 디렉터리에 주제별로 쪼갠다.

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

.claude/rules/의 모든 .md는 재귀적으로 탐색된다. 서브디렉터리(frontend/, backend/) 가능.

8.1 path-scoped 규칙

각 rule 파일에 paths frontmatter를 주면 특정 파일 패턴에만 적용된다. 해당 경로의 파일을 Claude가 읽을 때만 로드되므로 평소엔 컨텍스트 소비 없음.

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

- All endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

복수 패턴 + brace expansion:

paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"

paths가 없는 규칙은 항상 로드 — .claude/CLAUDE.md와 같은 우선순위.

8.2 프로젝트 간 공유 (symlink)

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

여러 프로젝트에 공용 규칙을 링크. 순환 심링크는 자동 감지.

8.3 사용자 레벨 규칙

~/.claude/rules/에 두면 모든 프로젝트에 적용. 우선순위는 프로젝트 > 사용자.

9. 안티패턴 5가지

9.1 비대한 파일

200줄 넘는 CLAUDE.md. 중요한 규칙이 장문에 묻혀서 adherence 급락. - 해결: 가지치기. "이 줄을 빼면 실수가 생기나?" 없으면 삭제. 오래된 규칙 정기 리뷰.

9.2 모순된 규칙

나쁜 예: "Use 2-space indentation" + 다른 파일에 "Follow Google style guide" (4-space). Claude가 임의로 선택. - 해결: 주기적으로 상위 CLAUDE.md + 중첩 CLAUDE.md + .claude/rules/ 전체를 훑어서 모순 제거.

9.3 "깨끗하게 작성하라" 같은 당연한 헤징

가치 없는 일반론은 구체적 규칙을 희석시킨다. - 해결: Claude가 기본적으로 잘하는 것은 적지 않는다. 왜 이 규칙이 필요한지 자문.

9.4 작업 절차를 CLAUDE.md에 넣기

"배포하려면 1) 테스트 2) 빌드 3) 푸시…" 같은 다단계 절차는 세션마다 토큰을 먹는다. - 해결: Skill(/deploy)로 이동. CLAUDE.md는 사실·규칙 위주.

9.5 /compact 후 사라진 지침 의심

프로젝트 루트 CLAUDE.md는 /compact 후에도 자동 재삽입된다 (공식 명시). 서브디렉터리 CLAUDE.md는 재삽입 안 되며 해당 디렉터리 파일을 다시 읽을 때 로드. - 해결: 대화에서만 준 지침이 사라졌다면 CLAUDE.md에 옮긴다. 중첩 CLAUDE.md는 /compact 전제로 설계하지 말 것.

10. 시작하기 — /init으로 초안 만들기

/init

Claude가 코드베이스를 분석해 빌드 명령·테스트 방법·코딩 컨벤션을 감지한 CLAUDE.md 초안을 만든다. 이미 CLAUDE.md가 있으면 개선 제안 모드로 동작.

환경변수로 인터랙티브 다단계 모드:

CLAUDE_CODE_NEW_INIT=1 claude

이 모드는 CLAUDE.md + 스킬 + 훅 중 무엇을 세팅할지 묻고, 서브에이전트가 코드베이스를 탐색한 뒤 follow-up 질문으로 갭을 메운다. 쓰기 전에 reviewable proposal로 확인.

생성 후에는 코드처럼 다룬다: 문제 생기면 리뷰, 주기적으로 pruning, Claude 동작이 바뀌는지 보고 테스트.

11. 진단 — /memory와 InstructionsLoaded 훅

11.1 /memory — 무엇이 로드됐는지 보기

세션에서 /memory를 실행하면 현재 세션에 로드된 모든 CLAUDE.md, CLAUDE.local.md, rules 파일 목록이 뜬다. 목록에 없다면 Claude가 그 파일을 읽지 않는 상태라는 뜻 — 위치 확인이 1차 점검.

11.2 InstructionsLoaded 훅 — 디버깅 시 이벤트 로깅

path-scoped 규칙이나 서브디렉터리 lazy load가 의도대로 동작하는지 확인하려면 훅 사용:

{
  "hooks": {
    "InstructionsLoaded": [
      {"type": "command", "command": "echo $CLAUDE_INSTRUCTIONS_PATH >> /tmp/claude-rules.log"}
    ]
  }
}

훅 전체 가이드는 다음 편에서 다룬다.

12. 반대 시나리오 — 이 가이드가 맞지 않는 경우

  • 프롬프트에만 지침을 주는 워크플로 → CLAUDE.md 없이도 --append-system-prompt 또는 --append-system-prompt-file로 넘기면 시스템 프롬프트 레벨에서 작동. 단, 매 호출마다 인자로 넘겨야 하므로 스크립트·자동화에 적합.
  • 엔터프라이즈 정책 강제가 필요 → CLAUDE.md는 권고일 뿐 강제 아님. 실제 차단이 필요하면 managed settings의 permissions.deny, sandbox.enabled로 기술적 enforcement를 설정. CLAUDE.md는 "하지 마" 지침이 아니라 "이렇게 해" 가이드로 쓴다.
  • 조직 정책은 CLAUDE.md, 기술 강제는 settings → 공식 문서가 명확히 분리한다:
관심사 어디에
특정 도구·경로 차단 Managed settings permissions.deny
샌드박스 격리 강제 Managed settings sandbox.enabled
인증 방법·조직 락 forceLoginMethod, forceLoginOrgUUID
코드 스타일·품질 가이드 Managed CLAUDE.md
데이터 처리·컴플라이언스 리마인더 Managed CLAUDE.md

13. 다음 단계

CLAUDE.md 기반이 잡혔다면:

  1. Claude Code 설치 완전판 — 아직 설치 전이면 먼저.
  2. 슬래시 커맨드 총정리 — /init, /memory, /compact 등 이 글에서 언급된 명령 전체 목록.
  3. Claude Code 훅(Hooks) 완전 가이드 — 생명주기 4종 × 실제 스크립트 — CLAUDE.md가 권고라면 훅은 강제 (예정).

참고

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 3/15 편입니다. last verified: 2026-04-25 (Claude Code 공식 Memory + Best Practices 기준).

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »