Claude Code, 이제 긴 하위 디렉터리 CLAUDE.md 파일을 잘라냅니다 — Claude가 보지 못하게 되는 지침과 확인 방법 (2026)

Anthropic의 메모리(memory) 문서에는 이제 이 케이스에 대한 트러블슈팅 항목이 "Claude가 하위 디렉터리 CLAUDE.md의 끝부분을 무시합니다"라는 제목으로 추가되었습니다. 이 항목은 다음과 같이 동작을 직접 설명합니다. "하위 디렉터리 CLAUDE.md 또는 온디맨드로 로드되는 규칙 파일이 파일당 크기 제한을 초과하면, Claude는 해당 파일의 시작 부분만 받게 됩니다. 그 부분은 Claude에게 Read 도구를 사용하여 나머지 부분을 읽으라고 안내하는 노트로 끝나며, Claude가 직접 읽기를 선택하기 전까지는 이후의 지침이 컨텍스트에 포함되지 않습니다."

동일한 항목의 끝에는 다음과 같은 버전 관련 문구가 있습니다. "v2.1.309 이전에는 Claude Code가 온디맨드로 로드되는 파일에 이 제한을 적용하지 않았습니다."

따라서 변경 사항은 제한적입니다. 릴리스 노트는 한 가지 사실을 설명합니다. 즉, 큰 온디맨드 파일이 이제 전체가 아닌 일부만 전달된다는 점입니다. 루트 파일에 대한 규칙은 별도로 설명되어 있으며, 제한 크기가 훨씬 더 큽니다.

릴리스 노트에서는 그 이유를 밝히고 있습니다. Claude가 매우 큰 중첩된 CLAUDE.md 아래의 파일을 읽은 후 세션이 반복적으로 압축(compacting)되는 현상이 발생했기 때문입니다. Claude가 특정 폴더를 다룰 때 로드되는 큰 지침 파일은 세션을 압축 상태로 밀어 넣을 수 있으며, 다음에 Claude가 해당 폴더에서 작업할 때 다시 로드될 수 있습니다.

따라서 이 제한은 실제 문제를 해결합니다. 다만 트레이드오프(trade-off)로 파일의 끝부분이 잘려 나가게 되며, 문서에서 설명하는 안내 노트는 사용자가 아닌 Claude를 대상으로 작성됩니다.

문서에는 온디맨드로 로드되고 제한 대상에 해당하는 파일들이 다음과 같이 나열되어 있습니다.

• "Claude Code를 시작한 디렉터리의 하위 디렉터리에 있는 CLAUDE.md 및 CLAUDE.local.md 파일, 그리고 이들이 @path로 가져오는(import) 파일"
• "하위 디렉터리의 .claude/rules/에 있는 규칙 파일"
• "프로젝트의 .claude/rules/ 또는 ~/.claude/rules/에 있는 경로 범위 규칙"

놓치기 쉬운 두 가지 세부 사항이 있습니다. 가져온 파일도 동일한 항목의 적용을 받습니다. 또한 경로 범위 규칙은 프로젝트의 메인 .claude/rules/ 폴더에 있더라도 적용을 받는데, 이는 시작할 때가 아니라 Claude가 일치하는 파일로 작업할 때 로드되기 때문입니다.

시작할 때 로드되는 파일은 다르게 작동합니다. 문서에 따르면 MEMORY.md 제한은 "MEMORY.md에만 적용됩니다. Claude는 시작할 때 로드되는 각 CLAUDE.md 파일이 4 MiB 이하인 한 전체를 가져옵니다." 또한 "Claude Code는 4 MiB를 초과하는 파일을 건너뛰고 전혀 로드하지 않습니다."라고 덧붙입니다. 그런 다음 새로운 규칙을 가리킵니다. "경로 범위 규칙과 하위 디렉터리의 CLAUDE.md 파일은 자체적으로 더 작은 파일당 제한을 가집니다."

즉, 루트 CLAUDE.md는 매우 큰 크기까지 전체가 로드되는 반면, 한 단계 아래 폴더에 있는 CLAUDE.md는 훨씬 더 작은 제한을 초과하는 순간 일부만 로드됩니다.

제한 크기는 세션이 실행되는 컨텍스트 창(context window)에 따라 다릅니다. 문서에서는 다음과 같은 값을 제시합니다.

• 200K 컨텍스트 창: 40,000자
• 1M 컨텍스트 창: Claude Opus 4.6 및 Claude Sonnet 4.6의 경우 200,000자, 이후 모델의 경우 150,000자

단위는 문자 수(characters)입니다. Anthropic의 크기 관련 권장 사항은 줄 수("CLAUDE.md 파일당 200줄 미만 목표")로 되어 있지만, 줄이 길면 200줄짜리 파일도 여전히 커질 수 있습니다.

컨텍스트 창 크기도 중요합니다. 현재 여러 모델이 기본적으로 1M 창으로 실행되지만, 이를 끌 수 있습니다. Anthropic의 모델 구성 페이지에 따르면 "세션을 200K 창으로 유지하려면 셸이나 설정 파일에서 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하십시오"라고 되어 있습니다. 귀하 또는 귀하의 팀이 이 변수를 설정한 경우, 세션은 40,000자 제한을 사용하게 되며, 1M 창을 사용하는 동료에게는 전체가 로드되는 파일이 귀하에게는 일부만 로드될 수 있습니다. 200K로 실행되는 모델로 작업하는 경우에도 마찬가지입니다.

Claude는 파일의 시작 부분과 함께 Read 도구를 사용하여 나머지 부분을 읽을 수 있다는 노트를 받게 됩니다. 이후의 지침은 Claude가 읽기를 "선택하기 전까지"는 Claude의 컨텍스트에 포함되지 않습니다. Claude가 나머지 부분을 읽을지 여부는 눈앞의 작업에 달려 있습니다. 중요하게 생각하는 지침이 긴 services/payments/CLAUDE.md 파일의 맨 아래에 있는 테스트 이름 규칙이고, Claude가 테스트를 작성하는 대신 버그를 수정하는 중이라면 나머지 부분을 열어볼 이유가 없을 수 있습니다.

이에 따라 다음 세 가지 결과가 따릅니다.

1. 이제 파일 내부의 순서가 중요해집니다. 제한을 초과한 파일의 상단에 있는 콘텐츠는 Claude에게 전달되지만, 하단에 있는 콘텐츠는 전달되지 않을 수 있습니다.
2. 가져오기(Imports)가 크기를 증가시킵니다. Anthropic의 가이드에 따르면 가져오기는 "긴 파일을 정리하는 데 도움이 되지만, 가져온 파일이 이를 가져오는 CLAUDE.md와 함께 로드되기 때문에 컨텍스트 비용을 줄여주지는 않습니다."
3. 노트는 Claude를 위한 것입니다. 트러블슈팅 항목에서는 전달된 부분의 끝에 나머지 부분이 어디에 있는지 Claude에게 알려주는 노트가 추가된다고 설명합니다. 사용자에게 알림을 보낸다는 설명은 없으며, 동일한 항목에서 직접 파일을 확인할 수 있는 방법을 제공합니다.

새로운 제한은 이미 루트 파일과 달랐던 기존 로딩 규칙 위에 추가로 적용됩니다.

Claude가 폴더를 다룰 때 로드됩니다. Claude Code는 작업 디렉터리 아래의 하위 디렉터리에서 CLAUDE.md 파일을 찾으며, "시작할 때 로드하는 대신, Claude가 해당 하위 디렉터리의 다른 파일을 읽거나 쓰거나 편집할 때 각 파일을 로드합니다."

덮어쓰는 것이 아니라 누적됩니다. Anthropic은 "발견된 모든 파일은 서로를 덮어쓰는 대신 컨텍스트에 결합(concatenate)됩니다"라고 설명합니다. 하위 디렉터리 파일은 루트 파일을 대체하지 않고 추가됩니다.

시작 목록에 표시되지 않습니다. 트러블슈팅 섹션에서는 "작업 디렉터리의 하위 디렉터리에 있는 CLAUDE.md는 시작할 때가 아니라 온디맨드로 로드되기 때문에 Memory 파일 아래에 나타나지 않습니다. 로드되면 터미널에 해당 경로와 함께 Loaded 라인이 표시됩니다"라고 언급합니다.

압축(Compaction)은 이를 대화처럼 취급합니다. 컨텍스트 창 페이지에 따르면 "경로 범위 규칙과 중첩된 CLAUDE.md 파일은 Claude가 트리거 파일을 읽거나 쓰거나 편집할 때 메시지 히스토리에 로드되므로, 압축 시 다른 모든 내용과 함께 요약되어 사라집니다." 이 파일들은 Claude가 일치하는 파일을 다음에 다룰 때 다시 로드됩니다. 이에 대한 권장 사항은 다음과 같습니다. "규칙이 압축 후에도 유지되어야 하는 경우, paths: 프런트매터를 제거하거나 프로젝트 루트의 CLAUDE.md로 이동하십시오." 유지해야 할 항목에 자동 압축을 적용하는 가이드에서 이 목록을 자세히 다루고 있으며, 유휴 상태 압축 가이드에서는 자리를 비운 사이에 발생하는 경우를 다룹니다.

따라서 하위 디렉터리 파일의 지침이 Claude의 컨텍스트 밖에 있게 되는 이유는 세 가지입니다. Claude가 아직 해당 폴더를 다루지 않았거나, 압축으로 인해 요약되었거나, 잘려 나간 부분 뒤에 있기 때문입니다.

Codex 역시 지침 파일의 크기를 제한합니다. OpenAI의 Codex 문서에 따르면 "Codex는 빈 파일을 건너뛰고, 결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단합니다."

Codex는 AGENTS.md 파일 체인 전체를 함께 제한하므로 작업 디렉터리에 가장 가까운 파일이 누락될 위험이 있습니다. 반면 Claude Code는 이제 각 온디맨드 파일을 개별적으로 제한하므로 각 대형 파일의 끝부분이 잘릴 위험이 있습니다. 두 방식 모두 지침 파일이 실제 작업을 방해하지 않도록 방지하며, 두 방식 모두 마지막 줄이 먼저 제외됩니다. Codex가 AGENTS.md 규칙을 건너뛰지 않도록 방지하는 가이드에서 Codex 측면의 내용을 다룹니다.

파일이 너무 작아서 상관없을 것이라고 가정하기. 줄이 길면 200줄짜리 파일도 40,000자를 초과할 수 있으며, 이는 200K 창에서의 제한 크기입니다. 줄 수가 아니라 문자 수를 세어야 합니다.

/context 확인하기. 하위 디렉터리 파일은 온디맨드로 로드되므로 Memory 파일 아래에 표시되지 않습니다.

모든 내용을 루트 CLAUDE.md로 이동하기. 이렇게 하면 파일당 제한은 피할 수 있지만, 루트 파일은 모든 세션에서 로드되며 Anthropic은 "파일이 길어질수록 더 많은 컨텍스트를 소비하고 지침 준수율이 떨어집니다"라고 경고합니다.

Claude에게 파일 전체를 읽으라고 지시하는 줄 추가하기. 해당 줄이 제한을 초과한 파일의 하단 근처에 있다면, Claude가 받지 못하는 부분에 포함될 수 있습니다.

1단계: 온디맨드 파일 찾기 및 문자 수 세기

제한 대상이 되는 파일들을 나열합니다. Claude Code를 시작하는 폴더 아래의 CLAUDE.md 및 CLAUDE.local.md 파일, 이들이 @path로 가져오는 모든 파일, 하위 디렉터리의 .claude/rules/ 폴더에 있는 규칙 파일, 그리고 프로젝트 내 또는 ~/.claude/rules/에 있는 paths: 필드가 포함된 모든 규칙 파일이 해당됩니다.

문자 수를 세는 Anthropic의 지침은 간단합니다. "Bash 또는 Zsh에서 wc -m path/to/CLAUDE.md를 실행하여 파일의 문자 수를 출력하십시오." 이 값을 세션의 제한 크기(200K 창의 경우 40,000자, 1M 창의 경우 모델에 따라 150,000자 또는 200,000자)와 비교해 보세요.

실제로 어떤 파일이 언제 로드되는지 확인하기 위해 Anthropic은 훅(hook)을 제안합니다. "InstructionsLoaded 훅을 사용하여 어떤 CLAUDE.md 및 규칙 파일이 로드되는지, 언제 로드되는지, 왜 로드되는지 기록하십시오." Claude가 폴더에서 작업을 시작할 때 터미널에 표시되는 Loaded 라인을 관찰할 수도 있습니다.

2단계: 다듬기, 분할하기 또는 중요한 줄을 위로 이동하기

제한을 초과하는 파일에 대해 문서는 두 가지 옵션을 제시합니다. "파일을 다듬거나, 파일의 일부를 하나 이상의 규칙 파일로 이동하십시오. 각 규칙 파일은 개별적으로 제한 크기가 적용됩니다."

각 규칙 파일마다 고유한 제한이 적용되므로 분할하는 방식이 효과적입니다. 60,000자의 api/CLAUDE.md 파일은 더 짧은 CLAUDE.md와 해당 경로 범위로 지정된 두 개의 규칙 파일로 나눌 수 있습니다. 각 파일은 Claude가 일치하는 파일을 다룰 때 로드되며 제한 크기 미만으로 유지됩니다.

가장 중요한 규칙은 각 파일의 상단 근처에 배치하여, 나중에 파일이 커지더라도 상단 부분이 여전히 Claude에게 전달되도록 하세요. Anthropic은 압축 후 끝부분이 잘려 나가는 스킬(skills)에 대해서도 동일한 조언을 제공합니다. "잘림(Truncation) 시 파일의 시작 부분은 유지되므로, 가장 중요한 지침은 SKILL.md의 상단 근처에 배치하십시오."

파일을 다듬는 데 도움이 되는 두 가지 기본 제공 도구가 있습니다. /doctor prompt-audit은 "이전 모델용으로 작성된 지침, 존재하지 않는 파일이나 명령에 대한 참조, 서로 모순되는 파일"을 찾아내고, 사용자가 요청하기 전까지는 아무것도 변경하지 않은 채 수정 사항을 제안합니다. 다른 팀의 파일이 함께 수집되는 대규모 모노레포(monorepos)에서는 claudeMdExcludes를 사용하여 경로 또는 glob 패턴별로 특정 CLAUDE.md 파일을 건너뛸 수 있습니다.

3단계: 배경 설명을 지침 파일에서 제외하기

Anthropic의 자체 다듬기 도구는 파일에 포함되어야 할 내용을 잘 보여줍니다. /doctor 진단은 "디렉터리 레이아웃, 종속성 목록, 아키텍처 개요 등 Claude가 코드베이스에서 유추할 수 있는 콘텐츠를 잘라내고, 도구 기본값과 다른 함정, 근거, 규칙을 유지합니다." 따라서 규칙 옆에 있는 한 줄짜리 이유는 그대로 유지됩니다.

제외할 수 있는 것은 긴 역사입니다. 결제 서비스가 왜 두 번 재시도하는지, 어떤 마이그레이션이 폐기되었는지, 누가 테스트 레이아웃을 주장했는지에 대한 전체 이야기 등입니다. 이러한 내용은 결정 문서나 해당 규칙을 도입한 풀 리퀘스트(pull request)로 이동하세요. 특정 작업에만 중요한 절차의 경우, Anthropic은 스킬을 가리킵니다. "항상 컨텍스트에 있을 필요가 없는 작업별 지침의 경우, 대신 스킬을 사용하십시오. 스킬은 사용자가 호출하거나 Claude가 프롬프트와 관련이 있다고 판단할 때만 로드됩니다." 이렇게 하면 파일은 작아지면서도 역사는 여전히 기록으로 남길 수 있습니다.

새로운 제한은 문서의 다른 곳에서 이미 강조했던 점을 다시 한번 확인시켜 줍니다. 즉, 지침 파일은 짧은 규칙을 위한 공간이며, Claude는 특정 조건 하에서만 이를 수신한다는 점입니다. Claude가 폴더를 다룰 때 로드되고, 압축에 의해 요약되며, 이제 길어지면 잘려 나갑니다. 규칙 뒤에 숨겨진 긴 배경 설명이 가장 먼저 밀려나게 되는 것입니다.

MemoryLake는 이러한 배경 설명을 직접 관리하는 하나의 목록으로 유지하여, Claude Code 및 연결된 다른 어시스턴트(예: ChatGPT, Codex 등)에서 사용할 수 있도록 지원하는 메모리 레이어입니다.

사용자는 자신의 언어로 직접 항목을 작성합니다. CLAUDE.md 파일, 규칙 파일, 자동 메모리 폴더 또는 서드파티 저장소에서 어떠한 내용도 읽거나 쓰거나 삭제하지 않습니다. 업무용 리포지토리의 경우, 외부에 보관하는 정보에 대한 조직의 정책을 따르십시오.

1단계: API 키 생성

로그인한 후 대시보드에서 키를 생성합니다. 이 키는 MemoryLake 워크스페이스에 속하며 Anthropic 계정과는 별개입니다.

2단계: 첫 번째 메모리 업로드

해결책 3단계에서 지침 파일 외부로 이동한 내용부터 시작하세요. 규칙 뒤에 숨겨진 역사, 폐기된 접근 방식, 서비스에 대한 결정 사항 등입니다. 항목당 하나의 요점을 작성하고, 날짜를 기입하고, 적용되는 폴더나 서비스의 라벨을 지정합니다.

3단계: AI 및 에이전트 연결

사용 중인 Claude Code 및 기타 어시스턴트를 연결합니다. 작업에 필요할 때 배경 설명을 사용할 수 있으며, CLAUDE.md 파일은 전체가 로드될 수 있을 만큼 짧게 유지됩니다.

첫 번째 차이점은 세션의 제한 크기와 비교하여 문자 수를 측정해 보았기 때문에, 이번 변경 사항이 어떤 파일에 영향을 미쳤는지 정확히 알 수 있다는 것입니다.

두 번째는 중요하게 생각하는 규칙이 Claude에게 확실히 전달된다는 점입니다. 규칙들이 짧은 파일의 상단 근처나 범위가 지정된 규칙 파일에 위치하므로, 파일이 커지더라도 잘려 나가지 않습니다.

세 번째는 지침 파일이 두 가지 역할을 동시에 수행하지 않게 된다는 점입니다. 규칙은 CLAUDE.md에 남고, 그 뒤의 역사는 다른 곳에 보관됩니다. 다른 도구를 위해 AGENTS.md도 유지하고 있다면, Claude Code가 AGENTS.md를 읽는 방식에 대한 가이드에서 어떤 파일이 우선권을 갖는지 다룹니다.

문자 수 세기. 제한 크기는 200K 창의 경우 40,000자, 1M 창의 경우 150,000자 또는 200,000자입니다.

세션이 사용하는 컨텍스트 창 확인하기. CLAUDE_CODE_DISABLE_1M_CONTEXT=1 설정 및 200K 모델을 사용하는 경우 더 낮은 제한 크기가 적용됩니다.

가장 중요한 규칙을 먼저 배치하기. 파일이 제한을 초과하여 커지면 시작 부분만 Claude에게 전달됩니다.

범위가 지정된 규칙 파일로 분할하기. 각 규칙 파일은 개별적으로 제한 크기가 적용됩니다.

긴 역사는 지침 파일에서 제외하기. 한 줄짜리 이유는 남겨둘 수 있습니다. 전체 이야기는 컨텍스트를 두고 경쟁하지 않는 다른 곳에 보관해야 합니다.

여러 워크트리(worktrees)에서 작업하는 경우, 각 워크트리 세션이 로드하는 내용에 대한 가이드에서 지침 파일과 자동 메모리가 어떻게 작동하는지 다룹니다.

Claude Code v2.1.309는 온디맨드로 로드되는 지침 파일(하위 디렉터리의 CLAUDE.md 및 CLAUDE.local.md 파일, 이들의 가져오기 파일, 하위 디렉터리의 .claude/rules/ 폴더에 있는 규칙, 경로 범위 규칙)에 대해 파일당 크기 제한을 추가했습니다. 제한을 초과하는 파일은 시작 부분과 노트만 Claude에게 전달되며, 나머지는 Claude가 직접 읽기 전까지 컨텍스트에서 제외됩니다. 프로젝트 루트의 CLAUDE.md는 여전히 최대 4 MiB까지 전체가 로드됩니다.

온디맨드 파일의 문자 수를 세어 세션의 컨텍스트 창 제한 크기와 비교해 보고, 제한을 초과하는 파일은 분할하거나 다듬으세요. 중요한 규칙을 먼저 배치하고, 긴 배경 설명은 크기 제한을 신경 쓰지 않아도 되는 다른 곳으로 이동시키십시오.