가이드
Claude Code 컨텍스트 윈도우 설명: 무엇이 채우고, /compact는 무엇을 남기는가
컨텍스트 윈도우에는 Claude가 세션에 대해 아는 모든 것이 들어 있습니다. 사용자의 지시, Claude가 읽은 파일, Claude 자신의 응답, 그리고 터미널에는 나타나지 않는 내용까지 포함됩니다. 이 글은 Anthropic의 Explore the context window 문서를 따라가며, 시작할 때 무엇이 로드되는지, 사용량을 어떻게 확인하는지, 윈도우가 가득 차면 어떻게 되는지, /compact 이후 무엇이 남는지, 그리고 /compact, /clear, /rewind가 각각 어떻게 동작하는지 설명합니다. 문서는 2026년 10월 30일에 확인했습니다.
- 컨텍스트 윈도우에는 대화 외에도 많은 것이 들어갑니다. CLAUDE.md, 자동 메모리, MCP 도구 이름, skill 설명은 아무것도 입력하기 전에 이미 로드됩니다.
/context를 실행하면 카테고리별 실시간 내역과 최적화 제안을 볼 수 있습니다.- Claude Code는 한도에 가까워지면 자동으로 compact하므로, 컨텍스트 윈도우가 가득 차도 세션이 끝나지 않습니다.
- compact 후에는 프로젝트 루트의 CLAUDE.md와 자동 메모리가 디스크에서 다시 주입됩니다.
paths:가 있는 규칙과 중첩된 CLAUDE.md 파일은 대신 필요할 때 다시 로드됩니다. - 요약이 중요한 내용을 남기게 하려면
/compact focus on the auth bug fix처럼 지침과 함께/compact를 실행하세요. 관련 없는 작업으로 옮길 때는/clear를 쓰세요.
컨텍스트 윈도우에 들어가는 것
문서에는 시작부터 compact까지의 세션을 재생하는 인터랙티브 타임라인이 있습니다. 그 안의 토큰 수는 대표적인 예시이며 실제 사용량이 아닙니다. 문서가 설명하는 순서는 대략 다음과 같습니다.
- 아무것도 입력하기 전: CLAUDE.md, 자동 메모리, MCP 도구 이름, skill 설명이 모두 컨텍스트에 로드됩니다. AGENTS.md 파일이 CLAUDE.md 대신 로드될 수도 있습니다. 사용자의 환경에 따라 output style이나
--append-system-prompt의 텍스트 같은 것이 더 추가될 수 있습니다. - Claude가 작업하는 동안: 파일을 읽을 때마다 컨텍스트가 늘어나고, 경로 범위 규칙은 일치하는 파일과 함께 자동으로 로드되며, 편집할 때마다 PostToolUse hook이 실행됩니다.
- 후속 프롬프트: subagent가 자신만의 별도 컨텍스트 윈도우에서 조사를 처리하므로, 큰 파일 읽기 내용이 사용자의 컨텍스트에 들어오지 않습니다. 요약과 작은 메타데이터 꼬리만 돌아옵니다.
- 타임라인의 끝:
/compact를 실행하면 대화가 구조화된 요약으로 대체됩니다. 시작 시 로드된 내용 대부분은 자동으로 다시 로드되며, 각 메커니즘이 어떻게 되는지는 아래 표에 있습니다.
subagent 작성법은 Claude Code subagents, skills는 Claude Code skills, CLAUDE.md는 CLAUDE.md 작성법을 참고하세요.
컨텍스트 사용량 확인하는 방법
문서에 따르면 언제든 /context를 실행해 실제 사용량을 볼 수 있습니다. 카테고리별 실시간 내역과 최적화 제안이 표시되며, 어떤 CLAUDE.md와 자동 메모리 파일이 로드되었는지도 보여 줍니다. /memory를 실행하면 그 파일들을 열어 편집할 수 있습니다.
명령어 레퍼런스는 두 명령어를 이렇게 설명합니다.
| 명령어 | 문서의 설명 |
|---|---|
/context [all] | 현재 컨텍스트 사용량을 색상 격자로 시각화하고, 컨텍스트를 많이 차지하는 도구, 메모리 비대화, 용량 경고에 대한 최적화 제안을 제공합니다. 대화가 컨텍스트 윈도우를 넘으면 출력에 한도를 얼마나 넘겼는지와 공간을 확보하는 명령어를 알려 주는 경고가 포함됩니다. 전체 화면 모드에서는 격자가 보이도록 항목별 내역을 접어 두며, all을 주면 펼칩니다. |
/memory | CLAUDE.md 파일을 편집하고, 자동 메모리를 켜거나 끄며, 자동 메모리 항목을 봅니다. |
비용 문서에는 /usage로 현재 토큰 사용량을 확인할 수 있고, 상태 표시줄을 설정해 계속 표시할 수도 있다는 설명이 더해져 있습니다. /usage는 세션 비용, 요금제 사용 한도, 활동 통계를 보여 줍니다.
컨텍스트가 가득 차면 어떻게 되나
Claude Code는 한도에 가까워지면 자동으로 compact하므로, 컨텍스트 윈도우가 가득 차도 세션이 끝나지 않습니다. 자동 처리는 타임라인의 /compact 단계와 같은 방식으로 동작합니다.
자동 compact가 실행되는 시점은 모델과 설정에 따라 다릅니다. 모델별 기본 임계값과, 모델 ID에 대해 Claude Code가 잘못된 윈도우를 가정할 때의 해결 방법은 문서의 model-config 페이지에 있습니다. 이 글에서는 구체적인 숫자를 제시하지 않습니다.
대화를 줄이는 것이 아니라 더 큰 윈도우가 필요하다면, 문서에 따르면 Fable 모델, Sonnet 5 이상, Haiku 5.5, Opus 4.6 이상, Sonnet 4.6이 100만 토큰 컨텍스트 윈도우를 지원합니다. 요금제별 제공 여부와 [1m] 모델 변형을 선택하는 방법은 문서의 Extended context 섹션에 있습니다. 더 큰 한도에서도 compact는 같은 방식으로 동작한다고 합니다.
compact 후 남는 것과 남지 않는 것
긴 세션이 compact되면 Claude Code는 컨텍스트 윈도우에 맞도록 대화 기록을 요약합니다. v2.1.198부터 요약 요청은 세션의 extended thinking 설정을 그대로 이어받으므로, 세션에서 thinking이 켜져 있으면 켠 상태로, 아니면 끈 상태로 추론합니다. thinking은 요약이 만들어지는 방식에만 영향을 주며, 이후 세션 설정은 바뀌지 않습니다. 각 종류의 내용이 어떻게 되는지는 어떻게 로드되었는지에 따라 다릅니다.
| 메커니즘 | compact 후 |
|---|---|
| 시스템 프롬프트와 output style | 둘 다 계속 적용됩니다 |
| 프로젝트 루트 CLAUDE.md와 범위 없는 규칙 | 디스크에서 다시 주입됩니다 |
| 자동 메모리 | 디스크에서 다시 주입됩니다 |
| Skill 설명 | 현재 skills로 다시 구성해 주입됩니다. Claude Code v2.1.304 이상이 필요합니다 |
| Git status 스냅샷 | 세션이 스냅샷과 함께 시작되었다면 Claude Code가 저장소에서 새로 읽습니다 |
| plan 모드에서 Claude가 작성한 계획 | 디스크에서 다시 주입됩니다 |
paths: frontmatter가 있는 규칙 | Claude Code가 필요할 때 다시 로드합니다 |
| 하위 디렉터리의 중첩된 CLAUDE.md | Claude Code가 필요할 때 다시 로드합니다 |
| Claude가 읽거나 편집한 파일 | Claude Code가 최근 수정된 순으로 최대 5개를 다시 읽습니다 |
| 호출된 skill 본문 | 다시 주입되며, skill당 5,000 토큰, 전체 25,000 토큰으로 제한됩니다. 오래된 것부터 버려집니다 |
| 백그라운드 명령과 백그라운드 subagent | 계속 실행됩니다. Claude Code가 아직 실행 중인 것을 Claude에게 알려 주므로 중복으로 시작하지 않습니다 |
| 앞서 hooks가 추가한 컨텍스트 | 나머지 대화와 함께 요약됩니다 |
compact 소스와 일치하는 SessionStart hooks | Claude Code가 실행하고 그 출력을 compact된 컨텍스트에 추가합니다 |
문서가 짚는 세 가지 세부 사항은 다음과 같습니다.
- 파일 다시 읽기에는 크기 제한이 있습니다. compact 직후 Claude Code는 세션에서 Claude가 읽거나 편집한 파일 중 가장 최근에 수정된 것부터 최대 5개를 다시 읽습니다. 5,000 토큰을 넘는 파일은 내용 없이 경로 참조로만 돌아오며,
Read대신Referenced file로 표시됩니다. - 경로 범위 규칙과 중첩된 CLAUDE.md 파일은 요약 과정에서 사라집니다. 이들은 Claude가 트리거 파일을 읽거나 쓰거나 편집할 때 메시지 기록에 로드되므로, compact가 다른 내용과 함께 요약해 버립니다. 규칙이 compact 이후에도 유지되어야 한다면
paths:frontmatter를 제거하거나 프로젝트 루트 CLAUDE.md로 옮기세요. - Skill 본문은 잘릴 수 있습니다. Skill 본문은 다시 주입되지만, 큰 skill은 skill당 상한에 맞춰 잘리고 전체 예산을 넘으면 오래전에 호출된 skill부터 버려집니다. 잘라낼 때는 파일의 앞부분이 남으므로 가장 중요한 지침을
SKILL.md위쪽에 두세요.
compact 전에 할 수 있는 것
자동 처리가 실행되기 전에 직접 대응할 수 있습니다. 문서는 다섯 가지 방법을 나열합니다.
| 방법 | 어떻게 |
|---|---|
| 초점을 정해 compact | 긴 새 작업을 시작하기 전에 /compact focus on the auth bug fix처럼 지침과 함께 /compact를 실행합니다. 자동 처리가 중요하다고 추측한 것이 아니라 사용자가 고른 것이 요약에 남습니다. |
| 대화의 일부만 compact | /rewind를 실행하고 메시지를 선택한 뒤 Summarize from here 또는 Summarize up to here를 선택합니다. |
| 더 일찍 compact | /autocompact 500k처럼 토큰 수와 함께 /autocompact를 실행해, 자동 처리가 실행되기 전에 컨텍스트 윈도우가 얼마나 차는지 설정합니다. |
| 작업 사이에 clear | 관련 없는 작업으로 옮길 때 /clear를 실행합니다. 오래된 대화는 다음에 필요한 파일을 밀어내고 메시지마다 토큰을 소모합니다. |
| 큰 읽기는 위임 | 조사를 subagent에 보내면 파일 내용이 사용자의 컨텍스트 윈도우가 아니라 subagent의 컨텍스트 윈도우에 머뭅니다. |
관련 명령어에 대해 명령어 레퍼런스는 다음과 같이 설명합니다.
| 명령어 | 문서의 설명 |
|---|---|
/compact [instructions] | 지금까지의 대화를 요약해 컨텍스트를 확보합니다. 요약에 초점을 둘 지침을 선택적으로 줄 수 있습니다. |
/clear [name] | 빈 컨텍스트로 새 대화를 시작합니다. 이름을 주면 /resume 선택기에서 이전 대화에 그 이름이 붙습니다. 같은 대화를 이어 가면서 컨텍스트를 확보하려면 대신 /compact를 사용하세요. 이전 대화는 /resume으로 재개합니다. 별칭: /reset, /new. |
/rewind | 대화 및/또는 코드를 이전 시점으로 되감거나, 선택한 메시지부터 요약합니다. 별칭: /checkpoint, /undo. |
/autocompact [auto|<tokens>] | 자동 compact 윈도우, 즉 Claude Code가 자동으로 compact하기 전에 컨텍스트 윈도우가 얼마나 차는지를 설정합니다. 500k 같은 크기를 주거나, auto를 주면 모델에 맞춰 조정된 윈도우로 돌아갑니다. Claude Code가 그 값을 사용자 설정에 저장하고 현재 세션에 적용합니다. Claude Code v2.1.221 이상이 필요합니다. |
컨텍스트를 가볍게 유지하기
비용 문서에서 컨텍스트와 관련된 조언은 다음과 같습니다.
- 작업 사이에
/clear. 오래된 컨텍스트는 이후 모든 메시지에서 토큰을 낭비합니다. 나중에 세션을 찾을 수 있도록 clear하기 전에/rename을 쓰고, 돌아갈 때는/resume을 쓰세요. - compact 지침을 직접 추가하세요.
/compact Focus on code samples and API usage는 요약하는 동안 무엇을 보존할지 Claude에게 알려 줍니다. 프로젝트 루트의 CLAUDE.md에 써 둘 수도 있습니다.# Compact instructions When you are using compact, please focus on test output and code changes - MCP를 주시하세요. MCP 도구 정의는 기본적으로 지연 로드되므로, Claude가 특정 도구를 사용하기 전까지는 도구 이름과 서버 지침만 컨텍스트에 들어옵니다.
/context를 실행하면 무엇이 공간을 차지하는지 볼 수 있습니다. - 가능하면 CLI 도구를 선호하세요.
gh,aws,gcloud,sentry-cli같은 도구는 도구별 목록을 추가하지 않으므로 MCP 서버보다 컨텍스트 효율이 좋습니다. - CLAUDE.md를 다듬으세요. CLAUDE.md는 세션 시작 시 컨텍스트에 로드됩니다. 특정 워크플로용 상세 지침이 들어 있으면, 관련 없는 작업을 할 때도 그 토큰이 차지됩니다. Skills는 호출될 때만 필요에 따라 로드되므로, 특화된 지침을 skills로 옮기면 기본 컨텍스트가 작아집니다. 문서는 핵심만 담아 CLAUDE.md를 200줄 이하로 유지할 것을 권합니다.
- 장황한 출력은 subagent에 맡기세요. 테스트 실행, 문서 가져오기, 로그 파일 처리는 컨텍스트를 많이 소모할 수 있습니다. 이런 작업을 subagent에 위임하면 장황한 출력은 subagent의 컨텍스트에 남고 요약만 메인 대화로 돌아옵니다.
- hooks로 데이터를 전처리하세요. 문서의 예시입니다. Claude가 1만 줄짜리 로그 파일을 읽어 오류를 찾는 대신, hook이
ERROR를 grep해서 일치하는 줄만 돌려주면 컨텍스트가 수만 토큰에서 수백 토큰으로 줄어듭니다.
이런 습관이 요금에 미치는 영향은 토큰 절약 가이드를, 캐시 동작은 캐시 가이드를 참고하세요. 이 글은 컨텍스트 자체가 어떻게 동작하는지에 집중합니다.
FAQ
컨텍스트 윈도우가 가득 차면 세션이 끝나나요?
아니요. 문서에 따르면 Claude Code는 한도에 가까워지면 자동으로 compact하므로, 컨텍스트 윈도우가 가득 차도 세션이 끝나지 않습니다. 그 전에 직접 /compact를 실행하고, 초점 지침으로 요약에 무엇이 남을지 정할 수도 있습니다. 자동 compact가 실행되는 시점은 모델과 설정에 따라 다릅니다.
CLAUDE.md의 규칙은 compact 후에도 유지되나요?
프로젝트 루트 CLAUDE.md와 범위 없는 규칙은 디스크에서 다시 주입됩니다. paths: frontmatter가 있는 규칙과 하위 디렉터리의 중첩된 CLAUDE.md 파일은 다릅니다. 이들은 필요할 때 다시 로드되며, compact는 이들을 요약해 없앱니다. 규칙이 compact 이후에도 유지되어야 한다면 문서는 paths: frontmatter를 제거하거나 프로젝트 루트 CLAUDE.md로 옮기라고 안내합니다.
/compact와 /clear의 차이는 무엇인가요?
/compact는 대화를 요약해 컨텍스트를 확보하며 대화는 계속됩니다. /clear는 빈 컨텍스트로 새 대화를 시작하며, 이전 대화는 /resume으로 재개할 수 있습니다. 명령어 레퍼런스는 분명하게 말합니다. 같은 대화를 이어 가면서 컨텍스트를 확보하려면 /compact를 사용하세요. 관련 없는 작업으로 옮길 때는 문서가 /clear를 권장합니다.
출처
- Claude Code: Explore the context window (시작 시 로드되는 것, compact 후 남는 것, 컨텍스트가 가득 찰 때,
/context) - Claude Code: Commands (
/context,/compact,/clear,/rewind,/autocompact,/memory,/usage) - Claude Code: Manage costs effectively (컨텍스트 제어 방법, compact 지침 직접 추가)