한 줄 요약: Claude Code 공식 문서 "Explore the context window". 세션 하나를 시작부터 컴팩션까지 재생하는 인터랙티브 시뮬레이션으로, 입력 전에 무엇이 자동 로드되는지, 파일 읽기·경로별 규칙·훅·서브에이전트가 컨텍스트에 무엇을 더하는지, 그중 무엇이 터미널에 보이지 않는지, /compact 뒤에 무엇이 남는지를 보여 준다. 컨텍스트가 찰 때 미리 할 수 있는 일(/compact 초점 지정, /rewind 부분 요약, /autocompact, /clear, 서브에이전트 위임)과 실제 사용량 확인(/context)도 다룬다.
원본 정보#
- 제목: Explore the context window
- 발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
- URL: https://code.claude.com/docs/en/context-window (새 창)
- 수집(fetch)일: 2026-10-18. 본문의 명령, 버전 조건(v2.1.198), 한도(5,000·25,000토큰), 1M 컨텍스트 지원 모델 목록은 이 날짜 기준이다.
- 형식: 원본의 대부분은 시뮬레이션 컴포넌트 코드다. 이벤트마다 이름, 예시 토큰 수, 터미널 표시 여부(보이지 않음·한 줄·전체), 설명(
desc), 팁(tip)이 붙어 있고, 그 뒤에 글로 된 설명 네 절(타임라인이 보여 주는 것, 컴팩션 뒤 남는 것, 컨텍스트가 찰 때, 내 세션 확인)이 있다. 이 요약은desc·tip과 글 본문을 근거로 쓴다.
핵심 주장#
- 입력하기 전에 이미 많은 것이 로드된다. 시스템 프롬프트, 자동 메모리(
MEMORY.md앞 200줄 또는 25KB 중 먼저 닿는 쪽), 환경 정보, MCP 도구 이름, 스킬 설명, 전역~/.claude/CLAUDE.md, 프로젝트 CLAUDE.md가 첫 프롬프트 전에 컨텍스트에 들어간다. AGENTS.md가 CLAUDE.md 대신 로드될 수 있고, 출력 스타일이나--append-system-prompt텍스트가 더해질 수 있다. 원본의 요점: "프롬프트는 이미 로드된 것에 비해 아주 작다. Claude 컨텍스트의 대부분은 사용자의 말이 아니라 프로젝트 지식이다." 이 시작 내용은 터미널에 보이지 않는다. → 컨텍스트 비용 - 컨텍스트를 가장 많이 쓰는 것은 파일 읽기다. 원본 팁: "File reads dominate context usage." 터미널에는 "Read auth.ts" 한 줄만 보이지만 파일 내용은 Claude만 본다. 그래서 프롬프트를 구체적으로 써("auth.ts의 버그를 고쳐") 읽는 파일을 줄이고, 리서치가 많은 일은 서브에이전트에 맡기라고 한다. 경로별 규칙(
paths:)은 맞는 파일을 읽을 때 자동으로 로드되고 터미널에는 "Loaded" 한 줄만 보인다. → 컨텍스트 엔지니어링 - 서브에이전트는 자기 창에서 읽고, 메인에는 최종 텍스트만 돌아온다. 서브에이전트는 더 짧은 자기 시스템 프롬프트, CLAUDE.md 사본(내장 Explore·Plan은 생략), 같은 MCP·스킬을 갖고, 대화 기록과 메인 세션의 자동 메모리 없이 시작한다. 돌아오는 것은 최종 텍스트 응답과 토큰 수·소요 시간을 담은 작은 메타데이터뿐이다. 기본으로 Agent 도구 자체는 재귀를 막기 위해 빠진다. → 서브에이전트
- 컴팩션 뒤에 남는 것은 "어떻게 로드됐나"에 달렸다. 시작 때 로드된 것(시스템 프롬프트·출력 스타일, 프로젝트 루트 CLAUDE.md·범위 없는 rules, 자동 메모리)은 다시 들어오고, 대화 중 로드된 것(경로별 규칙, 하위 디렉터리 CLAUDE.md, 훅이 더한 컨텍스트)은 대화와 함께 요약된다. 최근 수정된 파일은 최대 5개까지 다시 읽고, 호출한 스킬 본문은 스킬당 5,000토큰·합계 25,000토큰 안에서 다시 붙인다. 스킬 설명 목록은 다시 들어오지 않는다. → 장기 작업 컨텍스트 관리
- 꽉 차도 세션은 끝나지 않는다. 그래도 미리 손쓸 수 있다. Claude Code는 한도에 가까워지면 자동으로 컴팩션한다. 그 전에
/compact에 초점을 주거나,/rewind로 일부만 요약하거나,/autocompact로 더 일찍 돌게 하거나, 관련 없는 일로 넘어갈 때/clear하거나, 큰 읽기를 서브에이전트에 맡길 수 있다. 실제 사용량은/context로 본다. → 장기 작업 컨텍스트 관리, Claude Code
시뮬레이션이 보여 주는 세션 (예시)#
원본 시뮬레이션은 "토큰 갱신 뒤 401이 나는 인증 버그를 고쳐"라는 요청 하나로 세션을 재생한다. 순서와 터미널 표시만 옮긴다(토큰 수는 위 콜아웃대로 예시).
| 단계 | 컨텍스트에 들어가는 것 | 터미널에 보이는 것 |
|---|---|---|
| 입력 전 | 시스템 프롬프트, 자동 메모리, 환경 정보 | 입력창만 |
| 프롬프트 | 사용자 프롬프트 | 프롬프트 |
| 작업 | 파일 읽기 4건, 경로별 규칙 2건src/, *.에 맞음), grep 결과 | 파일마다 한 줄, 규칙은 "Loaded" 한 줄 |
| 수정 | Claude의 분석·PostToolUse 훅additionalContext로 돌려준 내용, 테스트 출력 | 분석과 diff, 훅은 보이지 않음, 테스트는 요약 |
| 후속 요청 | "서브에이전트로 세션 타임아웃 처리를 조사한 뒤 고쳐" → 서브에이전트 요약과 메타데이터 | 서브에이전트 작업 알림과 결과 |
!git status | 명령과 출력이 사용자 메시지의 일부로 | 출력 |
/ | disable-model-invocation: true 스킬의 전체 본문 | 스킬 실행 |
/ | 구조화된 요약 + 다시 로드된 시작 내용 + 다시 읽은 파일 + 다시 붙인 스킬 | "Conversation compacted", 다시 읽은 파일마다 한 줄, "Skills restored" |
원본이 밝힌 세부 동작 (2026-10-18 기준)#
자동 로드 항목
- MCP: 기본으로 도구 이름만 싣고 전체 스키마는 tool search로 필요할 때 불러온다.
ENABLE_TOOL_SEARCH=auto면 스키마가 컨텍스트 창의 10% 안에 들어갈 때 미리 싣고,ENABLE_TOOL_SEARCH=false면 모두 싣는다. → MCP - 스킬 설명:
disable-model-invocation: true인 스킬은 목록에 없고/name으로 부를 때까지 컨텍스트에 전혀 들어가지 않는다. → 스킬 - 프로젝트 CLAUDE.md 팁: 200줄 이하로 두고, 참고 내용은 스킬이나 경로별 규칙으로 옮겨 필요할 때만 로드되게 한다. → 메모리(CLAUDE.md)
훅 출력이 컨텍스트에 들어가는 길
PostToolUse훅이hookSpecificOutput.additionalContext로 돌려준 필드는 Claude의 컨텍스트에 들어가고, 종료 코드 0의 일반 stdout은 들어가지 않고 디버그 로그에만 쓰인다(원본의PostToolUseprettier 훅 예).- 종료 코드 2는 stderr를 오류로 Claude에게 보여 주지만,
PostToolUse에서는 도구가 이미 실행됐으므로 막지 못한다. - 출력이 10,000자를 넘으면 파일로 저장되고 Claude는 미리보기와 파일 경로를 받는다.
- 맞는 도구 이벤트마다 훅이 다시 실행된다.
→ 훅
서브에이전트
- general-purpose 에이전트의 시스템 프롬프트는 짧은 프롬프트와 환경 정보다. 커스텀 에이전트 frontmatter에
memory:가 있으면 메인의 것 대신 자기MEMORY.md를 싣는다. - 부모 도구 대부분을 받되, 중첩 맥락에 맞지 않는 몇 가지(plan 모드 제어, 백그라운드 작업 도구, 기본으로 Agent 도구 자체)는 빠진다.
- 사용자 프롬프트 대신 Claude가 써 준 작업 프롬프트를 받는다.
→ 서브에이전트
! 접두어 명령
- 터미널에서
!로 셸 명령을 실행하면 명령과 출력이 사용자 메시지의 일부로 컨텍스트에 들어간다. Claude가 실행하지 않아도 명령 결과를 근거로 주는 데 쓴다. → Claude Code
컴팩션 뒤 무엇이 남나 (원본 표, 2026-10-18 기준)#
컴팩션은 대화 기록을 요약해 창에 맞춘다. v2.1.198부터 요약 요청은 세션의 extended thinking 설정을 따른다(세션에서 켜져 있으면 켜고 아니면 끈다). thinking은 요약을 만드는 방식에만 영향을 주고 세션 설정은 그대로다.
| 방식 | 컴팩션 뒤 |
|---|---|
| 시스템 프롬프트와 출력 스타일 | 둘 다 계속 적용 |
| 프로젝트 루트 CLAUDE.md와 범위 없는 rules | 디스크에서 다시 주입 |
| 자동 메모리 | 디스크에서 다시 주입 |
| git status 스냅샷 | 세션이 스냅샷으로 시작했다면 저장소에서 새로 읽음 |
| plan 모드에서 Claude가 쓴 계획 | 디스크에서 다시 주입 |
paths: frontmatter가 있는 rules | 필요할 때 다시 로드 |
| 하위 디렉터리의 CLAUDE.md | 필요할 때 다시 로드 |
| Claude가 읽거나 편집한 파일 | 최근 수정된 것부터 최대 5개를 다시 읽음 |
| 호출한 스킬 본문 | 스킬당 5,000토큰, 합계 25,000토큰 안에서 다시 주입. 오래된 것부터 빠짐 |
| 백그라운드 명령과 백그라운드 서브에이전트 | 계속 실행. 중복 실행하지 않도록 Claude에게 아직 도는 것을 알려 줌 |
| 앞서 훅이 더한 컨텍스트 | 나머지 대화와 함께 요약됨 |
compact 소스에 맞는 SessionStart 훅 | 실행해 그 출력을 컴팩션된 컨텍스트에 더함 |
원본의 덧붙임:
- 다시 읽는 파일 중 5,000토큰을 넘는 것은 내용 없이 경로 참조로 돌아온다(
Read대신Referenced file로 표시). - 경로별 규칙과 하위 디렉터리 CLAUDE.md는 트리거 파일을 다룰 때 메시지 기록에 들어가므로 컴팩션이 다른 대화와 함께 요약해 버린다. 컴팩션을 넘어 남아야 하는 규칙이면
paths:frontmatter를 빼거나 프로젝트 루트 CLAUDE.md로 옮긴다. - 큰 스킬은 스킬당 한도에 맞춰 잘리고, 총 예산을 넘으면 가장 오래 전에 호출한 스킬부터 빠진다. 잘릴 때 파일 앞부분이 남으므로 가장 중요한 지시는
SKILL.md위쪽에 둔다. - 시뮬레이션의 컴팩션 뒤 안내: "System prompt, CLAUDE.md, memory, and MCP tools reload automatically"(시스템 프롬프트, CLAUDE.md, 메모리, MCP 도구는 자동으로 다시 로드된다). 같은 안내가 최근 고친 파일을 최대 다섯 개 다시 읽고 호출한 스킬을 다시 넣으며, 스킬 목록은 다시 로드하지 않는다고 덧붙인다.
- 시뮬레이션의 요약 블록 설명: 요약은 사용자의 요청과 의도, 핵심 기술 개념, 살펴보거나 고친 파일과 중요한 코드 조각, 오류와 해결 방법, 남은 작업, 현재 작업을 남긴다. 원문 대화를 대체하므로 전체 도구 출력과 중간 추론은 사라진다. Claude는 나머지 작업을 참조할 수 있지만 정확한 내용은 갖지 못한다.
컨텍스트가 찰 때 (2026-10-18 기준)#
- 한도에 가까워지면 자동으로 컴팩션하므로 창이 차도 세션이 끝나지 않는다. 자동 컴팩션은
/compact와 같은 방식으로 돈다. 대화를 놓아두면 컴팩션하는 idle compaction도 있다(원본은 settings reference로 링크만). - 미리 할 수 있는 일:
- 초점을 주고 컴팩션:
/compact focus on the auth bug fix처럼 지시를 붙인다. 긴 새 작업을 시작하기 전에. 요약이 자동 컴팩션의 추측 대신 사용자가 고른 것을 남긴다. - 일부만 컴팩션:
/rewind에서 메시지를 고르고 Summarize from here 또는 Summarize up to here. - 더 일찍 컴팩션:
/autocompact 500k처럼 토큰 수를 주어 자동 컴팩션이 도는 지점을 정한다. - 작업 사이에 비우기: 관련 없는 일로 넘어갈 때
/clear. 원본 이유: 오래된 대화가 다음에 필요한 파일의 자리를 빼앗고 매 메시지 토큰을 쓴다. - 큰 읽기 위임: 리서치를 서브에이전트에 보내 파일 내용이 그 창에 남게 한다.
- 초점을 주고 컴팩션:
- 더 큰 창이 필요하면: Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.6 이상, Sonnet 4.6이 100만 토큰 컨텍스트 창을 지원한다. 플랜별 가용성과
[1m]모델 변형 선택은 원본이 Extended context 문서로 넘긴다. 큰 한도에서도 컴팩션은 같은 방식이다. - 자동 컴팩션이 도는 지점은 모델과 설정에 따라 다르다(원본은 모델별 기본 임계값 문서로 링크만). LLM 게이트웨이 별칭처럼 Claude Code가 모델의 창 크기를 잘못 가정하면 창을 바로잡는 설정이 있다(링크만).
- 시뮬레이션 화면 안내: 실제 세션에서는 컨텍스트가 성능에 영향을 주기 시작할 때나 긴 새 작업 전에
/compact를 돌린다.
내 세션 확인#
/context: 지금 컨텍스트 사용량을 카테고리별로 보여 주고 최적화 제안을 내며, 어떤 CLAUDE.md와 자동 메모리 파일이 로드됐는지 보여 준다./memory: 그 파일들을 열어 고친다.
원본이 링크한 관련 문서#
- How Claude Code works의 "The context window"·"When context fills up" 절, Checkpointing의 "Rewind and summarize", Model configuration의 Extended thinking·Extended context·기본 auto-compact 임계값·auto-compact 창 설정·게이트웨이 창 보정, settings reference의 idle compaction·
includeGitInstructions, Hooks guide의 컴팩션 뒤 컨텍스트 재주입, Sub-agents(지속 메모리, 포그라운드·백그라운드), MCP tool search, Output styles, CLI reference, Prompt caching, Reduce token usage, Best practices