/context와 InstructionsLoaded 훅을 사용하여 CLAUDE.md 파일이 실제로 로드되는지 확인하세요. 규칙 문구를 수정하기 전에 지연 로딩 (lazy-loading) 문제(중첩된 파일, @imports)를 먼저 해결하세요. 규칙이 컨텍스트 (context)에 포함되어 있음을 확인한 후에만 규칙을 다시 작성하세요.

당신은 규칙을 작성했습니다. 하지만 에이전트 (agent)는 이를 무시했습니다. 문구를 다시 작성하기 전에 — 해당 규칙이 컨텍스트 윈도우 (context window)에 아예 포함되었는지부터 확인하세요. 제 경험상 "Claude가 내 CLAUDE.md를 무시한다"는 보고의 대부분은 사실 로딩 문제이며, 로딩 문제는 몇 초 만에 확인할 수 있습니다.

제가 순서대로 수행하는 세 가지 확인 절차는 다음과 같습니다.

핵심 요약 (Key Takeaways)

• /context와 InstructionsLoaded 훅을 사용하여 CLAUDE.md 파일이 실제로 로드되는지 확인하세요.
• 규칙 문구를 수정하기 전에 지연 로딩 (lazy-loading) 문제(중첩된 파일, @imports)를 먼저 해결하세요.
• 규칙이 컨텍스트 (context)에 포함되어 있음을 확인한 후에만 규칙을 다시 작성하세요.

1. /context — 현재 세션의 진실 (ground truth)

세션에서 /context를 실행하고 Memory files 목록을 살펴보세요. 그 목록이 실제로 로드된 내용입니다. 디스크에 존재하는 것이나, 로드되었어야 하는 것이 아닙니다. 만약 파일이 그곳에 없다면, 아무리 프롬프트 문구를 수정해도 도움이 되지 않습니다.

/memory와 혼동하지 마세요. /memory 명령은 사용자 및 프로젝트 범위에 걸친 메모리 파일의 _위치 (locations)_를 나열합니다. 여기에는 아직 존재하지 않는 파일을 생성할 수 있도록 아직 존재하지 않는 파일에 대한 항목도 포함됩니다. 이 명령은 "지침이 어디에 존재할 수 있는가?"에 답합니다. 반면 /context는 "Claude가 지금 실제로 무엇을 읽고 있는가?"에 답합니다. 디버깅을 할 때는 오직 두 번째 질문만이 중요합니다.

2. 두 가지 지연 로딩 (lazy-loading) 동작 이해하기

두 가지 로딩 규칙이 "내 규칙이 사라졌다"는 혼란의 거의 대부분을 야기합니다:

중첩된 CLAUDE.md 파일은 필요할 때 로드됩니다. 작업 디렉터리보다 상위 디렉터리에 있는 CLAUDE.md 파일은 시작 시 전체가 로드됩니다. 하지만 하위 서브디렉터리에 위치한 CLAUDE.md는 Claude가 해당 서브트리 내의 파일을 실제로 읽을 때까지 로드되지 않습니다. 세션 초반에는 이 규칙이 사실상 존재하지 않으며, /context는 첫 파일 접근이 트리거될 때까지 누락된 상태를 보여줄 것입니다. 만약 어떤 규칙이 항상 적용되어야 한다면, 중첩된 CLAUDE.md가 아닌 루트 파일(또는 경로 범위가 없는 .claude/rules/ 파일)에 유지하세요.

Import에는 날카로운 모서리가 있습니다. @path/to/file 임포트는 해당 파일을 참조하는 파일과 함께 시작 시 로드되며, 최대 4단계까지 연결될 수 있습니다. 사람들이 실수하기 쉬운 두 가지 세부 사항이 있습니다:

• 임포트 파싱은 코드 스팬(code spans)과 감싸진 코드 블록(fenced code blocks)을 건너뜁니다. 백틱(```) 안에 있는 `@README`는 리터럴 텍스트이며, 백틱 밖에 있는 @README는 임포트입니다.

• session_start — 시작 시점에 즉시 로드됨

• nested_traversal — 서브디렉터리에서 CLAUDE.md가 지연 로드된 경우

• path_glob_match — Claude가 건드린 파일을 매칭한 경로 범위 규칙

• include — @path 임포트를 통해 가져온 경우

• compact — 컨텍스트 압축 후 다시 로드된 경우

.claude/settings.json에 최소한의 로거를 추가합니다:

{
  "hooks": {
    "InstructionsLoaded": [
...

이제 tail -f ~/.claude/instructions-loaded.log를 실행하면, 나중에 프롬프트가 세 번 지나간 후에 행동 변화를 통해 추론하는 대신, nested CLAUDE.md가 컨텍스트에 최종적으로 진입한 정확한 순간을 확인할 수 있습니다. 이 훅은 관찰 가능성만을 위한 것이므로(비동기적으로 실행되며 종료 코드는 무시됨), 아무것도 망가뜨릴 수 없습니다.

또한 로드 이유별로 매처를 사용하여 필터링할 수도 있습니다. 예를 들어, `

출처: dev.to

원래 게시일: gentic.news