Claude Code 컨텍스트, 대형 템플릿 복사하면 무엇이 먼저 로드될까
에이전트 49개와 스킬 74개가 든 템플릿을 복사해도 정의 파일 본문이 첫 대화에 전부 들어오지는 않는다. 기본 설정으로 프로젝트 루트에서 새 세션을 열면 루트 지침과 @ 참조 파일, 이름·설명 목록, 시작 훅 출력이 먼저 문맥 재료가 된다. 공식 문서와 소스는 2026-11-09 KST에 확인했다.
본문은 호출할 때 읽히고, 이 커밋에서 시작 단계에 준비되는 정적 재료는 34,883바이트다.
Claude Code 컨텍스트에 처음부터 들어오는 것은 무엇인가
남의 .claude 폴더와 CLAUDE.md를 내 저장소에 복사하면 시작 문맥은 얼마나 커질까. 파일이 첫 질문부터 다 읽히는지, 부를 때만 읽히는지부터 나눠야 한다.
사례는 Donchitos의 Claude Code Game Studios 저장소다. 고정 커밋 05ad7c8a5b8aa2aa86bbd3439ae7cf7295cac418(2026-10-19 커밋)을 shallow clone해 파일을 셌다. README와 실제 파일 모두 에이전트 정의 49개, SKILL.md 74개였다.
정의 파일 원문은 에이전트 457,813바이트, 스킬 1,021,536바이트다. 이 1.4메가바이트가 넘는 텍스트가 세션마다 들어가지는 않는다. 시작 때 준비되는 재료와 호출 때 읽히는 본문은 따로 봐야 한다.
세션이 열릴 때는 본문 없이 지침과 이름·설명 목록이 먼저 준비되고, 본문은 작업을 고른 뒤에 로드된다.
공식 문서와 소스로 확인한 로딩 시점
로딩 시점은 Claude Code 공식 문서에 나뉘어 있다. 「How Claude remembers your project」는 작업 디렉터리의 CLAUDE.md를 시작할 때 읽고, @경로로 가져온 파일 내용도 함께 확장한다고 설명한다.
「Extend Claude with skills」와 「Create custom subagents」에 따르면 이름·설명은 선택용 목록으로 먼저 들어간다. 본문은 호출하거나 실행할 때 로드된다.
소스는 Bun 1.4.4 스크립트로 UTF-8 바이트를 전수 측정했다. 이름과 설명은 YAML 파싱 뒤 문자열만 셌고 내부 래퍼는 넣지 않았다.
| 항목 | 이 커밋의 UTF-8 바이트 | 로딩 시점 |
|---|---|---|
루트 CLAUDE.md | 3,531 | 세션 시작 |
@ import 네 파일 | 14,123 | 루트와 함께 확장 |
| 에이전트 49개 이름·설명 | 7,253 | 시작, 부모 문맥 목록 |
| 자동 호출 스킬 69개 이름·설명 | 9,976 | 시작, 예산 적용 전 목록 |
| 조건 없는 rule | 0 | 14개 모두 paths 조건 |
| 정적 재료 소계 | 34,883 | 소스 합계, 토큰 수 아님 |
| 시작 훅 2개 stdout | 470 | 샌드박스 1회 관측, 소계와 별도 |
| 에이전트 49개 본문 | 444,767 | 실행 시 자식 문맥 |
| 스킬 74개 본문 | 985,313 | 호출 시 |
소계 34,883바이트는 소스에서 센 문자열 합계다. 실제 모델 입력 크기나 토큰 수로 읽으면 안 된다.
파일을 나눠도 시작 문맥이 커지는 이유
루트 CLAUDE.md는 83줄, 3,531바이트로 짧다. 그런데 import까지 합친 시작 지침은 17,654바이트다. @ import가 경로 안내에 그치지 않고 파일 내용을 함께 확장하기 때문이다.
이 커밋은 문서 네 개를 @로 불러온다. 공식 문서상 import는 최대 네 단계까지 재귀로 동작한다. 파일을 쪼개도 @로 묶으면 문맥 비용은 남는 것으로 본다.
스킬 74개 중 다섯 개는 disable-model-invocation: true다. 이 스킬은 사용자가 부르기 전까지 설명도 모델 문맥에서 빠진다.
나머지 69개의 이름·설명 9,976바이트가 목록 재료다. 스킬 문서는 목록의 문자 예산이 모델 문맥 창의 1%에 따라 달라지고, 넘치면 덜 쓴 스킬 설명부터 생략한다고 설명한다. 그래서 이 값은 예산 적용 전 합계다.
에이전트는 이름·설명 7,253바이트가 위임 판단용으로 부모 문맥에 들어간다. 다섯 에이전트는 skills 필드로 스킬을 미리 지정했다. 이 스킬 본문은 부모 세션이 아니라 해당 자식 에이전트가 시작될 때 들어간다.
.claude/rules/의 Markdown 14개(27,994바이트)는 모두 paths 조건을 갖는다. 그래서 시작 때 무조건 읽히는 rule은 0바이트다.
훅의 쉘 코드 원문은 모델에 들어가지 않는다. 다만 「Hooks reference」에 따르면 SessionStart 명령의 stdout은 문맥에 추가될 수 있다. 이 커밋은 등록 명령 15개 중 session-start.sh와 detect-gaps.sh를 SessionStart에 연결했다.
두 시작 훅을 샌드박스에서 한 번씩 직접 실행했다. <폴더>는 소스를 복사해 둔 샌드박스 폴더다.
cd <폴더>/hook-observation
env HOME=<폴더>/hook-home XDG_CACHE_HOME=<폴더>/hook-home/.cache CI=1 CLAUDE_PROJECT_DIR=<폴더>/hook-observation bash .claude/hooks/session-start.sh < /dev/null
env HOME=<폴더>/hook-home XDG_CACHE_HOME=<폴더>/hook-home/.cache CI=1 CLAUDE_PROJECT_DIR=<폴더>/hook-observation bash .claude/hooks/detect-gaps.sh < /dev/null
첫 명령의 stdout은 200바이트였다.
=== Claude Code Game Studios — Session Context ===
Branch: main
Recent commits:
05ad7c8 Release 1.2.0 — the main path, rebuilt and tested
Review mode: solo
===================================
두 번째 명령은 새 프로젝트임을 알리고 /start, /project-stage-detect 실행을 권하는 안내를 270바이트 출력했다. 두 훅을 합치면 470바이트다.
외부 템플릿을 복사하면 무엇부터 줄일까
복사 직후에는 시작 때 합쳐지는 항목부터 줄이는 편이 낫다. 이 사례에서는 지침 17,654바이트와 에이전트·스킬 설명 17,229바이트가 그 대상이다.
- 루트
CLAUDE.md에서@로 시작하는 줄을 찾고 참조 파일 크기를 합산한다. - 매 세션 쓰지 않는 문서는
@에서 빼고, 하위 폴더CLAUDE.md나paths가 있는.claude/rules/파일로 옮긴다. - 수동으로만 부를 스킬의
SKILL.md에disable-model-invocation: true를 붙인다. .claude/agents/*.md의description길이와skills목록을 보고, 쓰지 않을 역할은 폴더에서 뺀다..claude/settings.json의SessionStart명령을 샌드박스에서 실행해 stdout 크기를 확인한다.
이 측정으로 알 수 없는 것
이번 결과는 소스 바이트와 샌드박스 훅 출력을 잰 값이다. 실제 Claude Code 세션은 시작하지 않았고 모델 입력도 캡처하지 않았다.
내부 래퍼, 예산 적용 뒤 생략 결과, /context 표시값, 캐시와 요금 차이는 재지 않았다. 470바이트도 최근 커밋이 1건인 shallow clone에 CI=1을 준 조건이라 다른 저장소에서는 달라질 수 있다.
본문이 처음부터 부모 대화에 붙지 않는다고 비용이 없는 것은 아니다. 스킬 본문은 호출 뒤 부모 대화에 추가될 수 있고, 서브에이전트는 별도 문맥 창에서 자체 요청을 만든다. 실제 비용은 자기 저장소에서 호출 빈도와 사용량을 재야 알 수 있다.
스킬이 늘 때의 관리 부담은 AI 코딩 스킬, 많을수록 좋을까 — 자산이 부채로 바뀌는 손익분기에서, 지침 파일 작성법은 CLAUDE.md 기본 구조 — Claude Code에게 같은 지시 반복 안 하는 법에서 다뤘다.
결론
이 커밋 기준으로 세션 시작 문맥의 재료는 본문 1.4메가바이트가 아니라 지침·목록 34,883바이트와 별도의 시작 훅 출력이다. 결국 기준은 파일 개수보다 시작 때 확장되는 @ 참조와 자동 호출 설명 목록의 크기다. 외부 템플릿을 들였다면 루트 CLAUDE.md의 @ 줄과 스킬의 disable-model-invocation 설정부터 열어 필요한 항목만 남기면 된다.

댓글
댓글 쓰기