컨텍스트 엔지니어링 실패모드 위키

Claude Code — CLAUDE.md 메모리 계층

9 min read

상위: 08_00_MOC

Claude Code — CLAUDE.md 메모리 계층

핵심 명제: “context, not enforced configuration”

CLAUDE.md의 본질은 공식 문서의 한 문장에 압축돼 있다.

“Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” — How Claude remembers your project, Anthropic

트러블슈팅 절은 여기에 한 가지 설명을 덧붙인다.

“CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there’s no guarantee of strict compliance, especially for vague or conflicting instructions.” — 동일 문서

실무로 옮기면 이렇다. CLAUDE.md에 “절대 main에 직접 푸시하지 말 것”이라고 적어도 그것은 부탁에 그친다. 강제하려면 PreToolUse 훅이나 permissions.deny를 써야 한다. 이 구분을 놓치면 04 충돌과 01 오염 실패모드를 끝내 막지 못한다.

파일 위치 4계층

공식 문서가 제시하는 계층 표다. 로드 순서는 넓은 범위에서 좁은 범위로 간다.

범위위치공유 대상
Managed policymacOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md		조직 전체 — 개인 설정으로 제외 불가
User instructions~/.claude/CLAUDE.md나의 모든 프로젝트
Project instructions./CLAUDE.md 또는 ./.claude/CLAUDE.md팀 전체 (버전관리)
Local instructions./CLAUDE.local.md나만 (.gitignore 권장)

로드 메커니즘은 다음과 같다.

  • CWD에서 파일시스템 루트까지 거슬러 올라가며 각 디렉토리의 CLAUDE.md와 CLAUDE.local.md를 발견하는 대로 수집한다.
  • 수집한 파일은 루트에서 CWD 순으로 컨텍스트에 이어 붙인다(concatenate).
  • 같은 디렉토리 안에서는 CLAUDE.md 뒤에 CLAUDE.local.md가 붙는다.
  • 하위 디렉토리의 CLAUDE.md는 시작 시점에 로드되지 않는다. 해당 디렉토리의 파일을 Claude가 처음 읽을 때 온디맨드로 로드된다.

managed policy의 특권은 분명하다. claudeMdExcludes 같은 개인 설정으로도 제외할 수 없으며, IT·DevOps 조직의 정책 배포를 위한 장치다.

효과적인 지시 작성 원칙

공식 문서의 권고는 세 가지로 정리된다.

크기. 파일당 200줄 이하를 권한다. 길어질수록 컨텍스트 소비가 늘고 준수율은 떨어진다.

“Files over 200 lines consume more context and may reduce adherence. Use path-scoped rules so instructions load only when Claude works with matching files.” — How Claude remembers your project

구체성. 검증할 수 있는 지시만 적는다.

  • “Use 2-space indentation” ✅ — “Format code properly” ❌
  • “Run npm test before committing” ✅ — “Test your changes” ❌
  • “API handlers live in src/api/handlers/” ✅ — “Keep files organized” ❌

충돌 처리.

“If two rules contradict each other, Claude may pick one arbitrarily.” — 동일 문서

04 충돌 실패모드가 그대로 드러나는 대목이다. 해법은 주기적 감사, 그리고 모노레포에서 claudeMdExcludes를 쓰는 것이다.

HTML 블록 주석은 토큰을 아끼는 팁이다.

<!-- 유지보수 담당: DevOps팀, 최종 수정: 2026-06 -->

블록 레벨 HTML 주석은 컨텍스트로 주입되기 전에 제거된다. 반면 코드 블록 안의 주석은 보존된다. 덕분에 관리자 메모를 토큰 소비 없이 남길 수 있다.

@import 문법

See @README for project overview and @package.json for available npm commands.
 
# Additional Instructions
- git workflow @docs/git-instructions.md

여기에 놓치기 쉬운 함정이 있다. "imported files still load and enter the context window at launch". 즉 파일을 쪼개도 토큰은 절약되지 않는다. @import는 어디까지나 가독성과 구조화를 위한 장치다.

재귀 임포트는 최대 4홉까지 허용한다. 백틱으로 감싸면 임포트가 아니라 리터럴 텍스트로 처리된다(예: `@README`).

Path-scoped Rules (.claude/rules/)

특정 파일 경로에 매칭될 때만 컨텍스트에 로드되는 조건부 규칙.

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.{ts,tsx}"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

동작 방식은 단순하다. paths 패턴에 매칭되는 파일을 Claude가 읽는 순간 로드되며, 도구를 호출할 때마다 다시 불러오지는 않는다.

/compact 이후의 소실에도 주의해야 한다. path-scoped 규칙과 하위 디렉토리의 중첩 CLAUDE.md는 컴팩션 요약에 담긴 뒤 사라지고, 해당 디렉토리 파일을 다시 읽을 때 복원된다.

“Path-scoped rules and nested CLAUDE.md files load into message history when their trigger file is read, so compaction summarizes them away with everything else.”

paths가 없는 규칙은 세션 시작 시 프로젝트 루트 CLAUDE.md와 동급으로 무조건 로드된다.

claudeMdExcludes

모노레포에서 관련 없는 CLAUDE.md를 제외:

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

.claude/settings.local.json에 추가하면 개인 로컬 범위에서만 제외된다. 여러 settings 레이어에서 설정할 수 있고 배열은 서로 병합된다. 다만 managed policy CLAUDE.md는 제외할 수 없다.

managed-settings.json의 claudeMd 키

별도 파일을 두지 않고도 managed settings JSON에 지시 내용을 직접 내장할 수 있다.

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

단 user, project, local 설정에서는 이 키가 무시되고, managed와 policy 설정에서만 동작한다.

CLAUDE.md vs 다른 메커니즘 선택 기준

공식 문서가 제시하는 도구 선택 기준:

요구사항사용 도구
매 세션 항상 필요한 규칙CLAUDE.md (루트, paths 없이)
특정 파일 유형에만 적용.claude/rules/ path-scoped 규칙
작업별 절차·워크플로우Skills (온디맨드 로드)
코드 커밋 전 자동 실행Hooks
특정 동작 강제 차단permissions.deny 또는 PreToolUse Hook
조직 전체 강제 정책Managed policy CLAUDE.md

함정 모음

  1. 세션 중 편집은 곧바로 반영되지 않는다. CLAUDE.md를 고쳐도 현재 세션에는 적용되지 않으며, /clear나 /compact, 재시작을 거쳐야 반영된다.
  2. 200줄을 넘으면 준수율이 떨어진다. 길어질수록 컨텍스트 소비가 늘고 준수율은 낮아진다.
  3. @import는 토큰을 아끼는 수단이 아니다. 임포트한 파일도 시작 시점에 전부 로드된다.
  4. system prompt가 아니다. user message로 주입되므로 강제력이 100%는 아니다.
  5. 충돌하면 임의로 선택한다. 두 규칙이 상충하면 Claude가 그중 하나를 임의로 고른다.
  6. /init 재실행은 덮어쓰지 않는다. CLAUDE.md가 이미 있으면 개선안을 제안한다.

참고문헌

관련 노트

그래프 뷰

백링크