CLAUDE.md 문제 해결

확인 날짜 안내

기본은 공식 문서 수집일(2026-10-18, 원본 날짜 미상) 기준이고, 블로그 Steering Claude Code에서 온 문장에는 (2026-06-18 기준)을 적었다. 2026-10-21 점검: (2026-06-18 기준) 표시 문장 중 변하는 사실은 이후 수집한 공식 문서가 모두 확인한다(PreToolUse 종료 코드 2 차단은 Claude Code 훅 가이드, 방법별 컴팩션 동작은 Claude Code 컨텍스트 창의 "What survives compaction" 표, --append-system-prompt는 Claude Code 메모리). 나머지("절대 하지 마라"는 장치를 바꾸라, 덧붙이기도 지시가 많을수록 덜 따른다)는 권고라 날짜 계산에서 뺐다. 그래서 페이지 확인 날짜를 2026-06-18에서 2026-10-18로 올렸다. 문장 옆 (2026-06-18 기준) 표시는 블로그 발행일 기록으로 남긴다.

메모리(CLAUDE.md)와 자동 메모리(Auto memory)가 기대대로 동작하지 않을 때의 점검 순서다. 원본 "Troubleshoot memory issues"를 증상별로 옮겼다. Claude Code 메모리

준비물(필요한 것)#

증상 1: Claude가 CLAUDE.md를 따르지 않는다#

전제: CLAUDE.md 내용은 시스템 프롬프트(용어 사전) 뒤의 사용자 메시지로 전달된다. Claude는 읽고 따르려 하지만, 특히 모호하거나 충돌하는 지시는 엄격히 지켜진다는 보장이 없다. Claude Code 메모리

1. /context를 실행해 Memory files 목록에 시작 때 로드돼야 할 CLAUDE.md·CLAUDE.local.md가 있는지 본다. 없으면 Claude는 그 파일을 볼 수 없다. /memory로 파일을 열어 고친다.
2. Instruction file not loaded 알림이 보이면 공식 오류 문서의 해당 항목을 확인한다.
3. 하위 디렉터리의 CLAUDE.md는 시작 때가 아니라 필요할 때 로드되므로 Memory files에 나오지 않는다. 로드되면 터미널에 경로와 함께 Loaded 줄이 뜬다. 새 파일을 시험하려면 Claude에게 쓰게 하지 말고 셸에서 직접 만든 뒤, 그 하위 디렉터리의 파일을 읽어 달라고 한다.
4. 파일이 이 세션에서 로드되는 위치에 있는지 확인한다(→ 메모리(CLAUDE.md)의 네 가지 범위).
5. 지시를 더 구체적으로 고친다. "format code nicely"보다 "Use 2-space indentation"이 잘 통한다.
6. 여러 CLAUDE.md에 같은 행동에 대한 다른 지시가 있는지 찾는다. 있으면 Claude가 하나를 임의로 고를 수 있다.
7. Claude Code가 스스로 넣는 지침과 겹치는지 본다. CLAUDE.md에 커밋·PR 규칙을 두었다면 includeGitInstructions로 내장 지침을 끄고, 서명 문구는 attribution으로 정한다.

근거: Claude Code 메모리

방금 고친 내용이 반영되지 않는다면 (2026-10-26 기준): 프로젝트 루트와 사용자 수준 CLAUDE.md는 세션 시작 때 한 번 읽어 둔다. 세션 중에 고친 내용은 다음 /clear, /compact, 재시작 때 들어가고, 그 전까지 Claude는 시작 때 읽은 판으로 일한다. 하위 디렉터리 CLAUDE.md와 paths: rules는 아직 로드되기 전이면 고친 내용이 반영된다. Claude Code 프롬프트 캐싱 → 프롬프트 캐싱

반대 증상: 쓰지 않은 규칙을 Claude가 따른다 (2026-10-18 기준). 커밋에 Co-Authored-By 줄을 붙이는 것처럼 내가 쓰지 않은 규칙을 따르면 system reminder에서 왔을 수 있다. Claude Code는 대화에 CLAUDE.md 파일, 출력 스타일 지시, 앞서 읽은 파일이 디스크에서 바뀌었다는 알림, 커밋·PR 서명 줄을 스스로 더한다. 서명 줄은 attribution으로 바꾸거나 없애고, 내장 커밋·PR 지침은 includeGitInstructions: false로 끈다. 나머지 스위치는 원본이 Agent SDK 문서로 넘긴다. Claude Code 작동 방식

그래도 안 되면 장치를 바꾼다.

• 커밋 전마다, 파일 편집 후마다처럼 특정 시점에 반드시 돌아야 하는 일은 훅으로 쓴다. 훅은 고정된 생명주기 이벤트에 셸 명령으로 실행되고 Claude의 판단과 상관없이 적용된다. Claude Code 메모리
• (2026-06-18 기준) 지키지 못한 것이 "절대 하지 마라" 규칙이라면 지시를 더 다듬기보다 장치를 바꾼다. 블로그 글은 Claude가 압박, 긴 세션, 모호한 상황, 작업 중 읽은 파일의 프롬프트 인젝션 때문에 프롬프트 규칙을 못 지킬 수 있다며, 결정론적 강제 수단으로 훅과 권한을 든다. PreToolUse 훅은 종료 코드 2로 호출을 막는다. Steering Claude Code → 권한 모드
• 시스템 프롬프트 수준 지시가 필요하면 시작 때 --append-system-prompt를 넘긴다. 대화형보다 스크립트·자동화에 맞다. Claude Code 메모리 (블로그 평가, 2026-06-18 글) 이 방법도 지시를 많이 줄수록, 특히 모순되면 덜 엄격하게 따른다. Steering Claude Code
• 어떤 CLAUDE.md와 규칙 파일이 언제, 왜 로드됐는지 기록하려면 InstructionsLoaded 훅을 쓴다. 경로별 규칙이나 하위 디렉터리의 지연 로드를 디버깅할 때 유용하다. Claude Code 메모리

증상 2: AGENTS.md가 로드되지 않는다#

보통 원인은 프로젝트 경로 어딘가의 CLAUDE.md다. 기본값에서는 작업 디렉터리나 그 위에 CLAUDE.md·CLAUDE.local.md가 없을 때만 AGENTS.md를 읽는다. 순서대로 확인한다. Claude Code 메모리

1. 작업 디렉터리나 그 위에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 있는지 찾는다(~/.claude/CLAUDE.md는 제외). 있으면 Project instructions를 claude-md-and-agents-md로 바꾸지 않는 한 그것을 대신 읽는다.
2. claude --version으로 v2.1.277 이상인지 확인한다. v2.1.281 전에는 Amazon Bedrock이나 텔레메트리를 끈 세션 등에서 AGENTS.md를 못 읽었으니 v2.1.281 이상으로 올린다.
3. /config에서 Project instructions가 claude-md나 managed-only가 아닌지 본다. 설정 자체가 안 보이면 AGENTS.md를 읽을 수 없는 세션이다.

• 읽혔는지 확인: /memory 목록에서 AGENTS.md 경로를 찾는다. v2.1.280 전에는 직접 읽은 AGENTS.md가 /memory·/context에 나오지 않았으므로, Claude에게 프로젝트 지시가 뭐라고 하는지 물어본다. Claude Code 메모리
• 해결: 찾은 CLAUDE.md를 유지하고 싶거나 AGENTS.md를 못 읽는 세션이면, AGENTS.md 옆에 그것을 import하는 CLAUDE.md를 둔다. Claude Code 메모리 → AGENTS.md와 CLAUDE.md 함께 쓰기
• 지시가 AGENTS.override.md에 들어 있다면: Claude Code는 이 파일을 읽지 않는다. Claude Code 메모리 (2026-10-18 기준) Codex는 같은 디렉터리의 AGENTS.md 대신 이 파일을 쓴다. Codex AGENTS.md 가이드 두 도구의 탐색 규칙 비교는 AGENTS.md와 CLAUDE.md 함께 쓰기, Codex 쪽 문제 해결은 Codex.

증상 3: 자동 메모리가 무엇을 저장했는지 모르겠다#

/memory를 실행해 자동 메모리 폴더를 열면 저장된 내용을 볼 수 있다. 모두 일반 마크다운이라 읽고 고치고 지울 수 있다. Claude Code 메모리 → 자동 메모리(Auto memory)

증상 4: CLAUDE.md가 너무 크다#

• 200줄을 넘는 파일은 컨텍스트를 더 쓰고 준수가 떨어질 수 있다. 4 MiB를 넘는 파일은 건너뛴다. Claude Code 메모리
• 권장 길이를 넘는 파일이 있으면 시작 때와 /status에서 경고가 뜬다. 파일마다는 권장 길이 안이어도 합계가 한도를 넘으면 경고가 뜨며, CLAUDE.md·규칙 파일·@path import가 각각 별도 파일로 계산된다. Claude Code 메모리
• 해결: 경로별 규칙으로 맞는 파일을 다룰 때만 로드되게 하거나, 매 세션 필요하지 않은 내용을 덜어 낸다. @path import로 쪼개는 것은 정리에는 도움이 되지만 컨텍스트를 줄이지 않는다. /doctor로 줄일 제안을 받는다. Claude Code 메모리 → CLAUDE.md 작성·구성

증상 5: /compact 뒤에 지시가 사라진 것 같다#

• 프로젝트 루트 CLAUDE.md는 컴팩션 뒤에도 남는다. /compact 후 디스크에서 다시 읽어 넣는다. 하위 디렉터리 CLAUDE.md와 paths: 규칙은 필요할 때 다시 로드된다. Claude Code 메모리
• (2026-06-18 기준) 블로그 글이 든 방법별 컴팩션 동작: 루트 CLAUDE.md는 다시 읽힘, 범위 없는 rules는 다시 주입, 호출된 스킬은 공유 예산 안에서 다시 주입되며 오래된 것부터 빠짐, 하위 디렉터리 CLAUDE.md는 그 디렉터리를 다시 건드릴 때까지 사라짐. Steering Claude Code (편집자 해석) 원본의 "If you've invoked many skills during a session, the oldest ones drop first"에 비추면, 스킬을 많이 호출한 긴 세션에서 초반에 부른 스킬의 절차가 사라진 것처럼 보일 때 이 예산을 원인 후보로 볼 수 있다. → 스킬
• 사라졌다면 원인은 셋 중 하나다: 대화로만 준 지시, 아직 다시 로드되지 않은 하위 디렉터리 CLAUDE.md, 그 뒤로 맞는 파일을 다루지 않은 경로별 규칙. 대화로만 준 지시는 CLAUDE.md에 적어야 남는다. Claude Code 메모리 → 장기 작업 컨텍스트 관리
• (2026-10-18 기준) 경로별 규칙이 컴팩션 뒤에도 꼭 남아야 하면: 공식 컨텍스트 창 문서는 그 규칙의 paths: frontmatter를 빼거나 내용을 프로젝트 루트 CLAUDE.md로 옮기라고 한다. 경로별 규칙과 하위 디렉터리 CLAUDE.md는 메시지 기록에 들어가 컴팩션 때 요약되기 때문이다. 대신 항상 로드되므로 컨텍스트 비용이 늘어날 수 있다(경로 범위 없는 규칙은 항상 로드된다는 메모리 문서 설명에 비춘 편집자 연결). Claude Code 컨텍스트 창, Claude Code 메모리
• (2026-10-18 기준) 스킬로 둔 절차가 사라진 것 같으면: 스킬 설명 목록은 컴팩션 뒤 다시 들어오지 않고, 호출한 스킬 본문만 예산 안에서 다시 붙는다. Claude Code 컨텍스트 창 → 스킬
• 확인: /context로 지금 로드된 CLAUDE.md와 자동 메모리 파일을 본다. Claude Code 컨텍스트 창

됐는지 확인하는 법#

고친 뒤 아래 화면으로 확인한다. 모두 본문 각 증상 절에 나온 방법을 모은 것이다.

• 시작 때 로드되는 CLAUDE.md: /context의 Memory files 목록에 그 파일이 보이면 로드된 것이다(증상 1의 1번). Claude Code 메모리
• 하위 디렉터리 CLAUDE.md: Memory files에는 나오지 않는다. 그 폴더의 파일을 읽게 했을 때 터미널에 경로와 함께 Loaded 줄이 뜨면 로드된 것이다(증상 1의 3번). Claude Code 메모리
• AGENTS.md: /memory 목록에서 AGENTS.md 경로를 찾는다. v2.1.280 전 버전은 목록에 나오지 않으므로 Claude에게 프로젝트 지시가 뭐라고 하는지 물어본다(증상 2). Claude Code 메모리
• 파일 크기: 권장 길이를 넘으면 시작 때와 /status에 경고가 뜬다. 경고가 사라졌는지 본다(증상 4). Claude Code 메모리
• /compact 뒤: /context로 지금 로드된 CLAUDE.md와 자동 메모리 파일을 본다(증상 5). Claude Code 컨텍스트 창
• 지시를 실제로 따르는지: 원본에는 "지시를 따랐다"를 확인하는 별도 방법이 없다. 로드 여부는 위 방법으로 확인하되, 로드돼도 엄격히 지켜진다는 보장은 없으므로 반드시 돌아야 하는 일은 훅으로 옮긴다(증상 1 끝). Claude Code 메모리

언제 쓰는가#

• 쓴다: 지시가 무시되는 것 같을 때, 새 하위 디렉터리 CLAUDE.md나 경로별 규칙을 만들고 동작을 확인할 때, AGENTS.md 저장소에서 Claude가 지시를 모르는 것 같을 때.
• 쓰지 않는다: 처음 파일을 만드는 단계라면 CLAUDE.md 작성·구성부터 본다.