컨텍스트 윈도우 (context window)는 Claude Code가 한 세션 동안 기억하는 모든 것을 담는 작업 책상입니다. 책상은 모델마다 크기가 다르고, 가득 차기 전에 단계적 압축과 /clear로 자리를 비워줘야 긴 작업을 품질과 비용 모두에서 끝까지 무리 없이 마칠 수 있습니다.

배경 참조

이 문서는 MoAI-ADK가 올라타 있는 플랫폼인 Claude Code 자체를 다루는 배경 자료입니다. MoAI-ADK를 쓰는 방법은 토큰 예산 관리와 안전한 중단에서 다룹니다.

정보

한 줄 요약: 컨텍스트 윈도우는 Claude의 작업 책상이자 토큰 비용이 발생하는 장부입니다. 모델이 정한 한계에 가까워지면 5단계 단계적 압축 (graduated compaction)이 순차적으로 작동하고, 95%에 닿으면 다음 행동은 반드시 /clear입니다.

비유로 이해하기

컨텍스트 윈도우를 책상 크기로 상상해 보세요. 작업할 서류(파일·대화)를 책상 위에 펼쳐 두고 일하는데, 책상은 무한하지 않습니다. 책상이 가득 차면 오래된 서류를 요약해 서랍에 넣는 것이 압축 (compaction)이고, 책상을 통째로 치우고 새로 시작하는 것이 /clear입니다. 책상이 넓어도 잡동사니로 채우면 정작 지금 볼 서류가 밀리므로, 크기를 늘리기보다 올려 두는 양을 줄이는 것이 핵심입니다.

컨텍스트 윈도우는 Claude가 한 세션에서 동시에 “볼 수 있는” 정보의 총량입니다. 여기에는 사용자가 입력한 프롬프트뿐 아니라, 터미널에 표시되지 않는 내용까지 모두 포함됩니다.

토큰 (token)은 이 정보를 세는 단위입니다. 대략 영어 단어 하나가 1~2 토큰, 한국어는 글자당 더 많은 토큰을 차지합니다. 다소 의외인 점은, 세션을 시작하기도 전에 이미 상당한 양이 채워진다는 것입니다. CLAUDE.md, 메모리, 스킬 목록, MCP 도구 이름이 첫 프롬프트보다 먼저 로드되기 때문입니다.

Claude가 작업하면서 읽는 파일이 컨텍스트 사용량을 지배합니다. 그래서 프롬프트를 구체적으로 적어 ("auth.ts의 버그를 고쳐줘") Claude가 읽는 파일 수를 줄이는 것이 토큰 절약의 핵심입니다. 리서치처럼 파일을 많이 뒤져야 하는 작업은 서브에이전트 (subagent)에게 맡기세요. 큰 파일 읽기는 별도 컨텍스트 윈도우에서 끝나고, 본 세션으로는 결과 요약만 돌아옵니다.

컨텍스트 윈도우 크기는 모델에 따라 다릅니다. Claude Code에서 실제로 동작하는 기준 (2026년 8월)은 아래 표와 같습니다.

크기가 클수록 한 번에 더 많은 파일과 대화를 담을 수 있지만, 윈도우가 무한하지는 않습니다. 어느 모델을 쓰든 결국 한계에 가까워지면 관리가 필요합니다. 핵심 원칙은 윈도우 크기를 늘리는 것보다, 들어가는 내용을 적게 유지하는 것이 더 안정적이라는 점입니다.

세션이 길어지면 컨텍스트가 한계에 다가갑니다. Claude Code는 모델 호출 직전마다 5단계 단계적 압축 (graduated compaction, Claude Code 2.1.196)을 순차적으로 적용해 창을 가볍게 유지합니다. 창이 차는 정도에 따라 점진적으로 강한 단계로 넘어갑니다.

마지막 단계가 흔히 말하는 압축 (compaction)입니다. /compact를 직접 실행할 수도 있고, 컨텍스트가 한계에 가까워지면 자동으로 일어나기도 합니다. 요약은 다음을 보존합니다.

• 사용자의 요청과 의도
• 핵심 기술 개념
• 살펴보거나 수정한 파일과 중요한 코드 조각
• 발생한 오류와 해결 방법
• 남은 작업과 현재 진행 상황

대신 전체 도구 출력과 중간 추론 과정은 사라집니다. Claude는 작업 내용을 참조할 수 있지만, 이전에 읽은 코드 원문을 더 이상 그대로 갖고 있지 않습니다.

압축 이후 각 정보가 어떻게 되는지는 로드 방식에 따라 다릅니다.

압축을 거쳐도 살려두고 싶은 규칙이라면 paths: 프론트매터를 빼거나 프로젝트 루트 CLAUDE.md로 옮기세요. 스킬은 잘릴 때 앞부분을 남기므로, 중요한 지시는 SKILL.md 위쪽에 두는 것이 안전합니다.

자동 압축의 시점을 조정해야 한다면, 환경 변수 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE로 임계값 (기본값: 전체 컨텍스트 대비 약 75~80%)을 바꿀 수 있습니다. 예를 들어 여유 있게 압축하고 싶다면 더 낮은 값을 지정하세요.

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70  # 70%에서 압축 시작

주의

95% 경고선 (hard stop): 사용량이 **95%**를 넘으면 모델 크기와 무관하게 다음 행동은 반드시 /clear입니다. 그 상태에서는 새로운 큰 작업을 시작하면 안 됩니다. 단계적 압축도 더 이상 버틸 여유가 없기 때문입니다. Claude Code 2.1.196부터는 스트리밍 멈춤 (stall)을 잡는 유휴 감시개 (idle watchdog)가 기본 켜짐으로 동작해, 5분간 이벤트가 없으면 자동으로 중단하고 다시 시도합니다. 이는 멈춤의 결과를 부드럽게 할 뿐, 멈춤 자체의 위험을 없애지는 않으므로 95%에 닿기 전에 미리 비워두는 것이 여전히 맞습니다.

/clear는 압축과 다릅니다. 요약조차 남기지 않고 대화 컨텍스트를 통째로 비워 새 세션처럼 시작합니다. 직전 작업과 무관한 새 작업으로 넘어갈 때 가장 깔끔합니다. 요약(압축)은 “이어서 더 작업할 때”, 초기화(/clear)는 “주제를 바꿀 때” 쓴다고 기억하면 됩니다.

flowchart TD
    A[세션 시작
CLAUDE.md·메모리 자동 로드] --> B[작업 진행
파일 읽기·응답 누적]
    B --> C{컨텍스트가
한계에 근접?}
    C -->|아니오| B
    C -->|이어서 작업| D[5단계 단계적 압축
Budget Reduction → Auto-Compact]
    C -->|주제 전환| E[/clear
컨텍스트 전체 비우기/]
    D --> F{사용량 95% 초과?}
    F -->|아니오| G[작업 계속
요약 + 자동 재주입 위에서]
    F -->|예, hard stop| E
    E --> G

지금 컨텍스트가 얼마나 찼는지 모르면 관리할 수 없습니다. Claude Code는 실측 도구를 제공합니다.

긴 작업에 들어가기 전이나 도중에 /context를 한 번 실행해 어떤 항목이 컨텍스트를 차지하는지 확인하는 습관이 관리에 큰 도움이 됩니다. 특히 어떤 카테고리가 예상보다 크다면 /context의 최적화 제안이 다이어트의 출발점이 됩니다.

대규모 작업일수록 컨텍스트가 가장 먼저 부딪히는 한계입니다. 다음 전략을 조합하면 한 작업을 여러 압축 경계를 넘어 안정적으로 이어갈 수 있습니다.

• 요약 후 계속: 한 단계를 마치면 압축으로 정리하고, 이어지는 단계는 요약 위에서 진행합니다.
• 서브에이전트로 분리: 파일을 많이 읽어야 하는 탐색·리서치는 서브에이전트에게 맡겨 본 세션 컨텍스트를 보호합니다.
• 메모리에 체크포인트 남기기: 중요한 결정과 진행 상황은 메모리에 기록해 압축이나 /clear를 넘어 살아남게 합니다. 체크포인팅 (checkpointing)과 짝을 이뤄 긴 세션의 연속성을 받쳐 줍니다.
• CLAUDE.md 다이어트: 프로젝트 CLAUDE.md는 200줄 이하로 유지하고, 참조용 내용은 스킬이나 경로 범위 규칙으로 옮겨 필요할 때만 로드되게 합니다.
• 95%에 닿기 전에 비우기: 사용량이 70~80%를 넘으면 미리 /compact로 자리를 만들거나 /clear로 단절합니다. 95%는 hard stop이지 관리 시점이 아닙니다.
• 프롬프트를 구체적으로: 읽을 파일을 좁혀 불필요한 파일 읽기를 줄입니다.

이 가운데 메모리와 체크포인트는 MoAI-ADK의 SPEC 워크플로, 세션 핸드오프와 곧바로 맞물립니다. MoAI-ADK는 이 페이지의 원리를 컨텍스트 다이어트 (context diet)라는 운영 규율로 넓혀 놓았습니다. 항시 로드되는 지침을 최소로 줄이고, 모델별 임계값 (1M 컨텍스트 모델은 사용량 50%, 256K·200K 모델은 90%)에 닿으면 진행 상태를 디스크에 저장한 뒤 붙여넣기 한 번으로 다음 세션을 잇는 세션 핸드오프를 제공합니다. statusline에 컨텍스트 사용률 (CW%)을 늘 띄워 임계값이 가까워졌음을 미리 알려 주기도 합니다. 여기서는 “컨텍스트가 차기 전에 미리 비우고, 중요한 상태는 디스크에 남긴다"는 모범 사례 (best practices)만 기억해도 충분합니다.

• 메모리와 자동 메모리
• 체크포인팅

• Claude Code Docs — Context window

팁

새로운 작업을 시작하기 직전에 /clear를 한 번 실행하세요. 이전 작업의 파일 읽기와 대화가 쌓인 채로 새 작업에 들어가면, 관련 없는 토큰이 책상을 차지해 응답 품질은 떨어지고 비용은 늘어납니다.