제가 접하는 "Claude Code가 내 규칙을 무시한다"는 보고의 절반은 동일한 근본 원인을 가지고 있습니다. 바로 규칙이 Claude Code가 전혀 로드하지 않은 파일에 들어있다는 점입니다. 메모리 시스템은 특정 규칙에 따라 특정 순서로 특정 파일 세트를 읽어들이는데, 이 로딩 규칙 몇 가지가 혼동하기 쉽습니다. 다음은 2026-07-31에 공식 메모리 문서(code.claude.com/docs/en/memory)를 통해 확인된 전체 조회 순서입니다.

네 가지 메모리 범위 (Memory Scopes)

Claude Code는 다음 네 가지 위치에서 메모리를 병합하며, 범위가 가장 넓은 것부터 가장 좁은 순서대로 나열하면 다음과 같습니다:

사람들이 놓치는 두 가지 세부 사항:

• CLAUDE.local.md는 동일한 레벨에 있는 공유 CLAUDE.md 이후에 로드됩니다. 따라서 팀 파일을 건드리지 않고도 개인적인 오버라이드(Overrides) — 개인용 샌드박스 URL, 선호하는 테스트 필터 등 — 를 적용하기에 적합한 장소입니다.
• 관리 정책 파일은 Linux와 Windows에도 존재하며, 경로는 서로 다릅니다. 만약 팀원 중 누구도 작성하지 않은 규칙이 나타난다면, 먼저 그곳을 확인해 보세요.

실행 시 로드되는 것 vs. 요청 시 로드되는 것

이 부분은 "왜 로드되지 않았는가"에 대한 대부분의 혼란을 설명해 줍니다:

실행 시(At launch), Claude Code는 작업 디렉토리(Working directory)로부터 상위로 거슬러 올라가며 탐색합니다. repo/apps/web에서 실행하면 repo/apps/web/CLAUDE.md, repo/apps/CLAUDE.md, repo/CLAUDE.md 등을 순차적으로 로드하며, 루트(Root)에서 현재 작업 디렉토리(cwd)까지 모두 연결(Concatenated)됩니다. 작업 디렉토리에 더 가까운 지침일수록 컨텍스트(Context)의 뒷부분에 나타나며, 실제 작업에 가장 가깝게 배치됩니다.

하위 디렉토리의 CLAUDE.md 파일은 실행 시 로드되지 않습니다. repo/apps/web/tests/CLAUDE.md와 같은 파일(현재 작업 디렉토리(cwd)의 하위)은 Claude가 실제로 해당 서브트리(subtree) 내부의 파일을 읽을 때만 로드됩니다. 이는 설계된 방식입니다. 에이전트가 해당 위치로 이동하기 전까지는 토큰 비용을 지불하지 않고도 각 패키지에 고유한 컨벤션(conventions)을 부여할 수 있습니다. 하지만 이는 다음과 같은 의미이기도 합니다. 만약 레포지토리 루트에서 "내 규칙이 뭐야?"라고 물어보며 메모리 설정을 테스트한다면, 하위 디렉토리 파일들은 보이지 않는 것처럼 보일 것입니다. 파일이 고장 난 것이 아니라, 지연 로딩(lazy)되는 것입니다.

실행 시 발생하는 또 다른 놀라운 점은 --add-dir로 추가한 디렉토리의 CLAUDE.md는 로드되지 않는다는 것입니다. 이는 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1로 설정했을 때만 발생합니다.

임포트(Imports): @path 구문

모든 메모리 파일은 다른 파일을 불러올 수 있습니다:

프로젝트 개요는 @README.md를, 스크립트는 @package.json을 참조하세요.

# 개인 선호도
...

실무에서 중요한 규칙은 다음과 같습니다:

• 상대 경로는 현재 작업 디렉토리(cwd)가 아닌, 임포트를 포함하고 있는 파일을 기준으로 해석됩니다. apps/web/CLAUDE.md 내부의 @./shared/rules.md는 apps/web/shared/를 가리킵니다.
• 임포트는 실행 시 임포트하는 파일과 함께 로드됩니다. 거대한 CLAUDE.md를 임포트된 청크(chunks)로 나누는 것은 구조를 재구성할 뿐, 컨텍스트(context) 비용을 줄여주지는 않습니다.
• 최대 임포트 깊이는 4단계(hops)입니다. 깊은 체인은 그 단계를 넘어서면 조용히 해석을 중단합니다.
• 코드 스팬(code spans) 및 코드 블록 내부의 임포트는 무시됩니다. 즉, 코드 스니펫 내의 `@anthropic-ai/claude-code`는 파일 읽기를 트리거하지 않습니다.
• 프로젝트 디렉토리 외부에서 파일을 임포트하면 처음 한 번은 승인 대화 상자가 나타납니다. 따라서 악의적인 레포지토리가 사용자의 ~/.claude 파일을 컨텍스트로 몰래 가져가는 것을 방지할 수 있습니다.

AGENTS.md를 중복 없이 사용하기

Claude Code는 AGENTS.md를 기본적으로 읽지 않습니다. 문서화된 패턴은 프로젝트의 CLAUDE.md에 한 줄을 추가하는 것입니다:

@AGENTS.md

이를 통해 Claude Code가 일반적인 임포트 경로 (import path)를 통해 로드하는 동안에도, 멀티 툴 팀 (Codex, Cursor agents 등)을 위한 단일 진실 공급원 (one source of truth)을 유지할 수 있습니다. 심볼릭 링크 (symlink)도 작동하지만, Windows에서 심볼릭 링크를 생성하려면 관리자 권한이 필요하다는 주의 사항이 있습니다. 임포트 라인을 사용하는 방식은 이 문제를 완전히 피할 수 있습니다.

.claude/rules/ 내의 범위 지정 규칙 (Scoped rules)

하나의 거대한 (monolithic) CLAUDE.md 대신, 규칙을 .claude/rules/*.md로 나눌 수 있습니다. 탐색은 재귀적 (recursive)으로 이루어지며, 개별 규칙 파일은 경로 범위 (path-scoped)를 지정할 수 있어 Claude가 일치하는 파일에서 작업할 때만 적용되도록 할 수 있습니다. 메모리 파일을 약 200행 미만으로 유지하라는 문서화된 목표와 결합하면, 이는 대규모 저장소 (repo)의 컨벤션을 확장하는 합리적인 방법입니다. 즉, 항상 켜져 있는 작은 핵심 (core) 규칙과, 관련 있는 곳에서만 활성화되는 범위 지정 규칙을 사용하는 것입니다.

모노레포 (monorepos)의 경우 설정에 claudeMdExcludes가 있습니다. 이는 특정 CLAUDE.md 파일의 로드를 억제하는 글로브 (glob) 리스트입니다. 이는 모든 설정 레이어에서 작동하며, 배열은 레이어 간에 병합됩니다.

주의해야 할 세부 사항 (Small print that bite)

• HTML 주석 (<!-- ... -->)은 주입 (injection) 전에 제거됩니다. 토큰을 소비하지 않아야 하는 유지 관리자용 노트에 유용합니다. 하지만 코드 블록 (code blocks) 내부에서는 주석이 보존된다는 점을 기억하세요. 따라서 주석 처리된 예시는 그 무게만큼의 비용이 여전히 발생합니다.
• 자동 메모리 (Auto memory)에는 예산이 있습니다. /memory 명령어로 이를 토글할 수 있으며 (설정의 autoMemoryEnabled), 매 세션마다 MEMORY.md의 처음 200행 또는 25KB만 로드됩니다. 만약 에이전트가 작성했던 내용을 "잊어버린다면", 해당 내용이 그 행 수 아래로 내려갔는지 확인하세요.

60초 디버그 체크리스트

규칙이 적용되지 않을 때:

1. 파일이 네 가지 범위 (scopes) 중 하나에 있습니까, 아니면 현재 작업 디렉토리 (cwd) 아래에 있습니까? cwd 아래의 파일은 지연 로딩 (lazily)됩니다.
2. 하위 디렉토리에서 Claude Code를 시작했습니까? 상위 디렉토리의 파일은 로드되지만, 형제 디렉토리의 파일은 로드되지 않습니다.
3. 규칙이 4단계 (hops)보다 더 깊은 임포트 체인 (import chain)을 거칩니까?
4. 임포트가 실수로 코드 펜스 (code fence) 안에 들어 있습니까?
5. 모노레포의 경우: 파일이 claudeMdExcludes 글로브에 일치합니까?
6. 코드 블록 외부의 HTML 주석으로 감싸져 있습니까? 그렇다면 제거되었습니다.

이러한 사례 하나하나가 실제로