Claude Code의 공식 문서에는 CLAUDE.md는 1 파일당 200줄 미만을 목표로 해야 한다고 적혀 있습니다. 그렇다면 200줄을 초과한 내용은 어디에 배치해야 할까요? Codex와 함께 사용하고 AGENTS.md까지 가지고 있는 경우, 같은 규칙을 두 개의 파일에 작성해야 하며, 이 과정에서 AGENTS.md의 위치 설정도 문제가 됩니다.
우선 전제 사항부터 말씀드립니다. CLAUDE.md는 Claude Code가 대화 시작 시 읽는 프로젝트 지침 파일입니다. 빌드 명령어나 코드 규약을 배치하여 설명하는 수고를 덜기 위해 사용됩니다. AGENTS.md는 Codex 등 다른 코딩 에이전트를 위한 지침 파일입니다.
/compact는 길어진 대화를 압축하여 AI가 한 번에 처리할 수 있는 문서 양의 여유 공간을 확보해 주는 Claude Code 명령어이며, 이 글에서는 그 문서 양을 '컨텍스트(context)'라고 부릅니다.
근거는 2026-10-28에 읽은 공식 memory 페이지 https://code.claude.com/docs/en/memory 에 국한됩니다. 이는 직접 동작을 재현하여 기록한 것이 아니라, 공식 문서의 내용을 정리한 것입니다. 해당 페이지에는 업데이트 날짜 표기가 없어 언제 시점의 내용인지 확인할 수 없습니다. 따라서 Claude Code의 버전 숫자는 페이지 본문에 기재된 것에 한정합니다. 만약 차이가 있다면 공식 문서를 따릅니다.
200줄을 초과했을 때, 읽히는 시점에 따라 분리하기
공식 문서의 해당 내용은 다음과 같습니다.
Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.
기준은 파일 하나당이며, 전체 합계가 200줄을 의미하는 것은 아닙니다. 공식 문서는 CLAUDE.md, 규칙(rules) 파일, @path로 불러온 파일을 각각 별도의 파일로 계산한다고 명시하고 있습니다. 공식이 제시한 수치 기준에는 CLAUDE.md 1 파일당 200줄의 적정량과, 읽기 건너뛰기(skipping) 시 4 MiB가 있습니다. 200줄을 초과하면 시작 시점과 /status에서 경고가 뜨며, 4 MiB를 초과하는 파일은 읽기 건너뛰기가 됩니다. 불러오는 모든 파일의 총합에도 상한선이 있어 초과 시 경고가 뜨지만, 그 수치는 읽는 범위에 포함되어 있지 않습니다. 공식 문서는 내용이 길어지면 준수하기 어려워진다고 말하지만, 효과가 몇 퍼센트나 달라지는지에 대한 수치적 정보는 읽은 범위 내에서 찾을 수 없습니다.
무엇을 남기고 무엇을 분리할지에 대한 기준 또한 공식 문서에 나와 있습니다.
Keep it to facts Claude should hold in every session: build commands, conventions, project layout, "always do X" rules. If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead.
매번의 대화에서 유지해야 할 사실은 CLAUDE.md에 남깁니다. 여러 단계로 이루어진 작업은 skill로 옮기고, 코드 일부에만 관련된 지침은 규칙(rule)으로 이동시킵니다. 규칙은 프로젝트의 .claude/rules/ 폴더에 놓는 Markdown 파일이며, 맨 앞에 paths:를 작성하면 해당 파일을 건드릴 때만 읽힙니다. 공식이 제시하는 방식대로라면 다음과 같습니다.
---
paths:
- "src/api/**/*.ts"
...
paths:가 없는 규칙은 무조건 로드되어 모든 파일에 영향을 미칩니다. paths:가 있는 규칙은 해당 파일을 Read, Write, Edit 등으로 건드렸을 때만 로드됩니다. 서브 폴더에 놓인 CLAUDE.md 역시 시작 시점에는 읽히지 않으며, 그 폴더의 파일을 읽거나 쓰기 할 때 비로소 적용됩니다. paths가 지정된 규칙에도 파일당 상한선이 있으며, 이를 초과하면 맨 앞 부분만 전달됩니다. 이 수치는 본문에서 다루지 않습니다.
CLAUDE.md에 작성된 내용은 강제가 아니라 지침(instruction)으로 전달됩니다. 공식 문서는 "Claude treats them as context, not enforced configuration"라고 적으며, 반드시 막고 싶은 작업은 PreToolUse의 hook, 즉 도구를 사용하기 전에 정해진 절차를 실행하는 메커니즘을 통해 차단하도록 안내하고 있습니다.
분리한 후에는 검토가 필요합니다. 두 지침이 모순될 경우, Claude는 둘 중 하나를 임의로 선택할 수 있습니다. 공식 문서는 CLAUDE.md, 서브 폴더의 CLAUDE.md, .claude/rules/를 정기적으로 검토하여 오래되거나 모순되는 지침을 제거할 것을 권장합니다.
左に 200 行を超えた長い CLAUDE.md の箱。右に、毎回要る物だけの短い CLAUDE.md と、該当ファイルを触る時だけ読まれるルール、手順を入れる skill の 3 つの箱が並ぶ。
@로 분리해도 로드되는 양은 줄지 않는다
CLAUDE.md를 짧게 만드는 가장 쉬운 방법은 내용을 다른 파일로 옮겨서 가져오는 것입니다. 가져오기는 @가 붙은 경로를 CLAUDE.md 안에 적기만 하면 됩니다.
공식 문서는 명확하게 설명합니다.
Imports는 긴 파일을 정리하는 데 도움이 되지만, 가져와진 파일들은 해당 CLAUDE.md와 함께 로드되기 때문에 컨텍스트 비용(context cost)을 줄이지는 못합니다. 가져오기는 정리에 유용하지만, 문맥 소비량은 줄어들지 않습니다. 가져오기는 중첩이 가능하며 최대 4단계까지 할 수 있습니다.
로드되는 양을 줄이는 방법으로는 paths가 포함된 규칙(rule)과 서브 폴더의 CLAUDE.md가 있으며, 그 외에 skill로 분리하는 방법도 있습니다. 다음 표는 skill을 제외한 위치별로 읽히는 시점을 정리한 것입니다.
| 위치 | 읽히는 시점 | 문맥 소비 |
|---|
| 루트의 CLAUDE.md | 시작 시(起動時) | 매번 |
| 서브 폴더의 CLAUDE.md | 해당 폴더의 파일을 건드릴 때 | 건드리기 전까지 로드 안 됨 |
@로 가져온 것 | 가져오는 쪽과 함께 | 줄지 않음 |
| 규칙 (paths 없음) | 무조건적 | 매번 |
| 규칙 (paths 포함) | 해당하는 파일을 건드릴 때 | 건드리기 전까지 로드 안 됨 |
/compact 이후, CLAUDE.md의 무엇이 남는가
긴 대화를 /compact로 압축한 후에는 초반에 전달했던 지침이 사라진 것처럼 보일 수 있습니다.
Project-root CLAUDE.md는 압축을 거쳐도 살아남습니다: /compact 이후, Claude는 이를 디스크에서 다시 읽어 세션에 재주입합니다. 서브디렉터리에 있는 중첩된 CLAUDE.md 파일과 paths: 프런트매터(frontmatter)가 포함된 규칙은 필요할 때 다시 로드됩니다.
프로젝트 루트에 있는 CLAUDE.md는 압축 후에 디스크에서 다시 읽혀져 세션에 재주입됩니다. 서브 폴더의 CLAUDE.md와 paths가 포함된 규칙은 필요할 때 다시 로드됩니다.
압축 후 사라진 지침에 대해 공식이 예시로 드는 것은 ① 대화 내에서만 전달한 지침, ② 아직 다시 읽히지 않은 서브 폴더의 CLAUDE.md, ③ 그 이후 해당 파일을 건드리지 않은 paths가 포함된 규칙, 세 가지입니다. 대화 내에서의 지침은 CLAUDE.md에 작성하면 유지된다는 것이 공식 답변입니다. 첫 번째 절에서 paths가 포함된 규칙으로 옮긴 지침은, 그 후에 해당 파일을 건드리지 않았다면 ③에 해당합니다.
압축으로 무엇이 남는지에 대한 전체 내역은 memory 페이지에서 다른 페이지가 안내하고 있습니다. 그 페이지는 읽지 않았습니다.
/compact の後の流れ。ルートの CLAUDE.md はディスクから読み直されて残る。サブフォルダの CLAUDE.md と paths 付きのルールは必要になった時に読み込まれる。会話の中だけで言った指示は消えうるので、残したい指示は CLAUDE.md に書く。
AGENTS.md와 CLAUDE.md, 어느 것이 읽히는가
공식 문서는 AGENTS.md의 처리에 대해 다음과 같이 설명합니다.
Claude Code는 AGENTS.md를 프로젝트 지침으로 읽을 수 있으므로, 다른 코딩 에이전트를 위해 이미 설정된 리포지토리는 CLAUDE.md, 가져오기(import), 또는 설정을 추가할 필요 없이 작동합니다. Codex 등 다른 에이전트를 위해 AGENTS.md를 정리해 둔 리포지토리는 CLAUDE.md도, 가져오기도, 설정도 추가하지 않고 Claude Code에서 구동된다는 의미입니다. 기본 동작은 작업 폴더나 그 상위 폴더에 무엇이 있느냐에 따라 다음 표와 같이 나뉩니다.
작업 폴더 또는 그 상위 폴더에서 | 읽히는 내용 |
| :--- |
| AGENTS.md만 있을 경우 (CLAUDE.md도 CLAUDE.local.md도 없는 경우) | AGENTS.md |
| AGENTS.md와, CLAUDE.md 또는 CLAUDE.local.md 중 하나가 있는 경우 | CLAUDE.md 쪽 내용만 |
| CLAUDE.md가 @AGENTS.md를 가져오는(include) 경우 | CLAUDE.md (AGENTS.md도 포함되어 읽힘) |
CLAUDE.md가 '없는지' 여부를 확인하는 범위는 작업 폴더와 그 상위 폴더 전체에서, 부모 폴더의 CLAUDE.md와 CLAUDE.local.md까지 포함합니다. 이 중 어느 하나를 배치하면, Claude Code는 AGENTS.md를 직접 읽지 않게 됩니다. ~/.claude/CLAUDE.md
또한, 조직에서 관리하는 CLAUDE.md나 .claude/rules/ 파일은 이 확인 범위에 포함하지 않고, AGENTS.md와 함께 로드합니다.
AGENTS.md를 직접 읽으려면 Claude Code v2.1.277 이상이 필요합니다. v2.1.281 이전 버전에서는 Amazon Bedrock을 사용하는 세션이나 텔레메트리(telemetry)가 꺼진 세션 등에서 CLAUDE.md만 읽히는 경우가 있었습니다. AGENTS.md를 읽기 어려운 환경이라면, 공식적으로 해당 환경에서 사용할 CLAUDE.md 파일에 @AGENTS.md로 가져오도록 안내하고 있습니다.
두 파일이 모두 있는 경우, 기본 설정은 CLAUDE.md만 읽는 것입니다. Claude Code의 설정 중 Project instructions를 claude-md-and-agents-md로 변경하면, 각 폴더에서 CLAUDE.md가 먼저, AGENTS.md가 나중에 순서대로 두 파일을 모두 읽습니다. 이미 가져와진(included) AGENTS.md나 심볼릭 링크(symlink)를 거친 AGENTS.md는 로드된 것으로 간주되어 두 번 읽히지 않습니다. 이 설정은 Claude Code 세션에서 /config를 입력하여 열리는 설정 패널의 Project instructions에서 변경할 수 있습니다. 이 설정에 대한 설명은 memory 페이지의 Choose which instruction files load 섹션에 있습니다.
중복 관리를 하나로 통합하기
같은 규칙을 AGENTS.md와 CLAUDE.md 양쪽에 모두 작성하면, 한쪽만 수정하고 다른 쪽이 오래된 상태로 남아 문제가 발생할 수 있습니다. 공식 문서를 참고하여, 가져오기(include), 심볼릭 링크(symlink), 또는 AGENTS.md 단독 사용 중 하나를 선택하는 방법이 있습니다.
가장 좋은 방법은 AGENTS.md를 모든 도구에 공통으로 사용하는 하나의 파일로 만들고, 옆의 CLAUDE.md에 @AGENTS.md라고 작성하는 것입니다. Claude 전용 지침은 가져오기(include) 내용 아래에 추가합니다.
@AGENTS.md
## Claude Code
Claude 전용 지침만 여기에 작성
심볼릭 링크는 Claude 전용 내용이 필요하지 않을 때 사용할 수 있습니다. ln -s AGENTS.md CLAUDE.md 한 줄입니다. 다만, Edit과 Write 기능은 심볼릭 링크를 통한 쓰기를 거부하며, 이때의 거부 메시지가 링크가 가리키는 AGENTS.md 파일을 수정하도록 안내합니다. Windows 사용자가 있는 리포지토리에서는 core.symlinks를 활성화하지 않은 환경에서 심볼릭 링크가 단순 텍스트 파일이 되기 때문에, 공식적으로는 가져오기를 사용하는 것이 좋다고 권장하고 있습니다.
공식 문서를 정리하면, Claude 전용 지침이 있는 경우는 가져오기(include)를 사용하고, 그렇지 않은 경우는 심볼릭 링크 또는 AGENTS.md 단독 사용으로 나뉩니다. CLAUDE.md 없이 AGENTS.md만 사용할 수 있는 환경은 AGENTS.md를 읽을 수 없는 세션이 없는 경우입니다. 읽을 수 없는 세션이 존재하는 환경에서는 CLAUDE.md를 통한 가져오기가 필요합니다.
左は、AGENTS.md と CLAUDE.md の両方に同じ規則を書いてずれる二重管理。右は、AGENTS.md を正本にして、CLAUDE.md が @AGENTS.md で取り込み、Claude 専用の指示だけを足す形。
v2.1.277 이전에 만들어진 임시 해결책 중에는, AGENTS.md가 직접 읽히는 현재 상황에서는 더 이상 필요하지 않거나 유지할 수 있는 것들이 있습니다. 공식 문서의 Remove an earlier AGENTS.md workaround 섹션은 @AGENTS.md를 작성한 CLAUDE.md는 그대로 두어도 괜찮다고 안내합니다. 심볼릭 링크는 그대로 두거나 삭제해도 무방합니다. AGENTS.md 내용을 출력하는 SessionStart
공식에서는 hook을 제거하라고 명시하고 있습니다. 직접 읽게 되면, hook 부분이 같은 내용으로 문맥에 중복되어 쌓이면서 양이 늘어나기 때문입니다. AGENTS.md를 읽으라고 단순히 텍스트로 지시하는 CLAUDE.md는 삭제하거나, @AGENTS.md 가져오기로 대체합니다.
수정한 후, CLAUDE.md와 AGENTS.md 확인하기
줄 수는 wc -l CLAUDE.md로 계산합니다. 200줄을 초과하면, 공식에 따르면 /status에서 경고가 발생합니다. 버전은 claude --version으로 알 수 있습니다. 다음 세션에서 /context를 실행하여 Memory files 항목에 CLAUDE.md가 표시되는지 확인합니다. AGENTS.md를 읽었는지 여부는 /memory 목록에 해당 경로가 나타나는지를 통해 확인합니다. v2.1.280 이전 버전에서는, 직접 읽혔더라도 목록에 나오지 않습니다.
본문에서 확인하지 못한 사항
압축 후 남는 모든 항목의 전체 내역은 다른 페이지를 읽지 않아 확인하지 못했습니다. 한쪽에서 다른 쪽을 생성하는 도구는, 읽은 범위 내에 설명이 없어 다루고 있지 않습니다.
Docspi는 분산된 문서를 하나의 가상 트리(지도)로 정리하여, 사람과 AI 에이전트가 같은 지도를 볼 수 있도록 만드는 저희 서비스입니다. Free 플랜은 $0이며 프로젝트 10개까지 지원하며 신용카드가 필요하지 않습니다 (2026-10-28 기준).
토론
