CLAUDE.md와 AGENTS.md는 토큰을 얼마나 쓰고, 길이는 어느 정도가 적당한가요?
정해진 숫자는 없습니다. 파일 길이만큼 들고, 세션의 모든 메시지에 함께 실립니다. Anthropic은 CLAUDE.md 파일 하나를 200줄 이내로 유지하라고 권합니다. Codex는 AGENTS.md 파일들을 합쳐 32 KiB에 이르면 더 추가하지 않습니다. 매번 필요한 규칙만 남기고 나머지는 옮기세요.
Codex
AGENTS.md는 시작할 때 한 번 읽고 그 뒤로 세션 내내 실립니다. 합계 한도는 기본 32 KiB이며, OpenAI는 짧게 유지하라고 안내합니다.
Codex는 시작할 때 ~/.codex/AGENTS.md를 읽은 다음, 프로젝트 루트에서 현재 디렉터리까지 내려오면서 단계마다 파일을 최대 하나씩 가져와 프롬프트의 한 블록으로 이어 붙입니다. 그 블록이 32 KiB(project_doc_max_bytes 설정)에 이르면 파일을 더 추가하지 않으므로, 그 뒤에 있는 내용은 아예 읽히지 않습니다. 큰 프로젝트에서는 파일을 계층으로 나누세요. 프로젝트 전체에 적용되는 규칙 몇 개만 루트에 두고, 모듈별 규칙은 해당 모듈 안의 AGENTS.md에 넣습니다. 그러면 그 디렉터리에서 Codex를 시작할 때만 로드됩니다.
공식 문서 원문
Reduce the size of your AGENTS.md. If you work on a larger project, you can control how much context you inject through AGENTS.md files by nesting them within your repository.Codex builds an instruction chain when it starts (once per run; in the TUI this usually means once per launched session).Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default).Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.Claude
CLAUDE.md는 세션을 시작할 때마다 전체가 로드됩니다. Anthropic은 파일당 200줄 이내를 권하며, /context에서 실제로 얼마나 차지하는지 볼 수 있습니다.
Claude Code는 실행될 때 ~/.claude/CLAUDE.md, 프로젝트의 CLAUDE.md(또는 .claude/CLAUDE.md), CLAUDE.local.md, 그리고 상위 디렉터리에 있는 같은 이름의 파일들을 읽습니다. 하위 디렉터리의 파일은 Claude가 그 디렉터리의 파일을 읽을 때에만 로드됩니다. Claude Code는 요청마다 대화 전체를 보내므로 이 내용은 메시지마다 다시 계산됩니다. Anthropic의 설명은 분명합니다. 파일이 길수록 컨텍스트를 더 차지하고 지시를 따르는 정도는 떨어집니다.
공식 문서 원문
CLAUDE.md files are loaded into the context window at the start of every session, consuming tokens alongside your conversation.Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.Claude Code sends your full conversation with every requestCLAUDE.md에서 덜어 낸 내용은 어디로 옮기나요?
Claude Code에서 필요할 때만 지시를 로드하는 방법은 두 가지입니다. @로 가져오는 파일을 포함해 나머지는 모두 실행될 때 로드됩니다.
릴리스, 리뷰, 데이터베이스 마이그레이션처럼 특정 워크플로에만 쓰는 긴 지시: 스킬로 옮기세요. 스킬은 쓸 때만 로드됩니다.
특정 파일에만 적용되는 규칙: .claude/rules/에 넣고 파일을 paths: 블록으로 시작하세요. Claude가 일치하는 파일을 읽을 때 로드됩니다.
사람이 보라고 적은 메모: HTML 주석으로 감싸세요. Claude Code는 파일이 컨텍스트에 들어가기 전에 블록 단위 주석을 제거합니다.
공식 문서 원문
If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work. Skills load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller. Aim to keep CLAUDE.md under 200 lines by including only essentials.Splitting into @path imports helps organization but doesn't reduce context, since imported files load at launch.Block-level HTML comments (<!-- maintainer notes -->) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them.흔한 오해
- CLAUDE.md를 자세히 쓸수록 Claude가 더 잘 따른다
아닙니다. Anthropic의 설명은 정반대입니다. 파일이 길수록 컨텍스트를 더 차지하고 따르는 정도는 떨어지며, 지시가 구체적이고 간결할수록 Claude가 더 일관되게 따릅니다. 길어진 만큼은 메시지마다 내는 고정 비용입니다.
- CLAUDE.md를 @ 가져오기로 쪼개면 토큰이 절약된다
절약되지 않습니다. 가져온 파일도 실행될 때 함께 로드되며, 가져오기는 정리에 도움이 될 뿐입니다. 실제로 토큰을 절약하는 것은 필요할 때만 로드하는 방식, 즉 paths: 블록이 있는 규칙과 스킬입니다.
- Claude는 CLAUDE.md의 200줄 이후를 읽지 않는다
아닙니다. 200줄은 권장치이지 잘리는 지점이 아닙니다. Claude Code는 파일이 4 MiB를 넘지 않는 한 전체를 로드하며, 늘어난 줄마다 토큰이 듭니다. 처음 200줄 또는 25KB 규칙은 자동 메모리 파일인 MEMORY.md에 해당합니다. 실제로 잘라 내는 쪽은 Codex로, AGENTS.md 파일들이 합쳐서 32 KiB에 이르면 더 추가하지 않습니다.
팁
- Claude Code: /context를 입력해 Memory files가 얼마나 차지하는지, 어떤 파일이 로드됐는지 확인하세요.
- Claude Code: /memory를 입력해 해당 파일을 열고 줄이세요. 수정한 내용은 다음 세션부터 적용되며, /compact 뒤에는 Claude Code가 프로젝트 루트의 CLAUDE.md를 디스크에서 다시 읽습니다.
- 파일을 한 줄씩 살펴보세요. 매번 필요한 규칙이 아니면 지우거나 옮기세요. 빌드 명령, 컨벤션, 프로젝트 구조, 항상 지켜야 하는 규칙만 남깁니다.
- Codex: 프로젝트 전체 규칙은 루트 AGENTS.md에 두고, 모듈 규칙은 해당 모듈 안의 AGENTS.md에 넣으세요.
- Codex: codex --ask-for-approval never "Summarize the current instructions."를 실행해 실제로 읽힌 내용이 의도한 것과 같은지 확인하세요.
- 두 도구를 모두 쓴다면 AGENTS.md 하나만 관리하세요. 최신 버전의 Claude Code는 프로젝트에 CLAUDE.md가 없으면 AGENTS.md를 바로 읽습니다. CLAUDE.md도 있다면 그 안에 @AGENTS.md 한 줄을 넣으세요. 가져온 내용에도 토큰이 드니 AGENTS.md는 짧게 유지하세요.