Ch9. 컨텍스트 관리

/compact·/context·/recap으로 컨텍스트 윈도우를 압축하고, CLAUDE.md·자동 메모리로 핵심 맥락을 보존하며 1M 컨텍스트와 토큰 절약 옵션을 운영하는 방법

핵심 요약

세션 시작 시 시스템 프롬프트·CLAUDE.md·자동 메모리·MCP 도구 목록이 먼저 적재되고, 그 위에 파일 읽기와 도구 출력이 윈도우를 채웁니다.
/compact는 대화를 구조화 요약으로 대체하고, /clear는 빈 컨텍스트로 새로 시작합니다. 압축은 작업 경계에서 실행해야 맥락 손실이 적습니다.
프로젝트 루트 CLAUDE.md·스코프 없는 rule·자동 메모리는 압축 후 디스크에서 다시 주입되지만, 대화로만 전달한 지시는 요약돼 흐려집니다.
MEMORY.md는 앞 200줄 또는 25KB까지만 적재되며, CLAUDE.md는 길이와 무관하게 전부 적재됩니다.
Fable 5·Opus 4.6·Sonnet 4.6은 1M 컨텍스트를 지원하지만, Opus는 자동 업그레이드되는 반면 Sonnet은 추가 사용 크레딧이 필요합니다.

컨텍스트 관리는 세션 품질과 수명을 좌우합니다. 대화 히스토리와 도구 출력이 가장 큰 비중을 차지하니, 불필요한 입력을 줄이고 제때 요약하는 것이 관건입니다.

세션을 시작하는 순간부터 시스템 프롬프트, CLAUDE.md, 자동 메모리(MEMORY.md), MCP 도구 목록, 스킬 설명이 컨텍스트에 먼저 적재됩니다. 그 위에 사용자의 프롬프트, 파일 읽기, 도구 출력이 쌓이면서 윈도우가 채워집니다. 공식 문서의 컨텍스트 윈도우 시뮬레이션에서 각 요소가 어느 시점에 얼마만큼 적재되는지 시각적으로 확인할 수 있습니다.

/compact 명령

컨텍스트가 길어지면 /compact로 대화를 요약·압축해 공간을 확보합니다.

/compact

포커스 지시(instructions)를 인수로 전달해 특정 내용 위주로 보존할 수도 있습니다.

/compact API 변경사항에 집중해서 압축해줘

/compact는 대화 히스토리를 구조화된 요약으로 바꿉니다. 요청과 의도, 핵심 기술 개념, 검토·수정한 파일과 중요한 코드 스니펫, 발생한 오류와 해결 방법, 미완료 작업, 현재 진행 상황은 요약에 남지만, 전체 도구 출력과 중간 추론 과정은 사라집니다.

/clear와의 차이

같은 대화를 이어가면서 공간만 확보하려면 /compact를, 빈 컨텍스트로 새 대화를 시작하려면 /clear(별칭 /reset, /new)를 사용합니다. /clear 후에도 이전 대화는 /resume에서 다시 불러올 수 있습니다.

압축 타이밍 가이드

큰 작업이 끝난 직후
새로운 작업으로 전환하기 전
대화가 길어져 반복 설명이 늘어날 때

작업 경계에서 압축

작업 중간에 압축하면 진행 중인 맥락을 잃기 쉽습니다. 되도록 작업 경계(기능 완료 시점)에서 실행하세요.

CLAUDE.md의 Compact Instructions

/compact 후에도 반드시 보존할 내용을 CLAUDE.md에 모아두면 안전합니다. 프로젝트 루트 CLAUDE.md는 압축 시 디스크에서 다시 읽어 컨텍스트에 재주입되기 때문입니다.

## Compact Instructions

현재 작업: 인증 시스템 리팩토링.
- apps/web: 프론트엔드
- apps/api: 백엔드
- 한국어 응답, 커밋 금지

압축 후 살아남는 것

압축에서 무엇이 살아남느냐는 그 내용이 어떻게 적재됐는지에 따라 갈립니다.

시스템 프롬프트·output style: 메시지 히스토리가 아니므로 그대로 유지
프로젝트 루트 CLAUDE.md, 스코프 없는 rule, 자동 메모리: 디스크에서 재주입
paths: 프론트매터가 있는 rule, 하위 디렉터리의 중첩 CLAUDE.md: 매칭 파일을 다시 읽을 때까지 손실
호출했던 스킬 본문: 재주입되지만 스킬당 5,000토큰·전체 25,000토큰으로 제한되고 초과 시 오래된 것부터 제거

대화로만 전달한 지시는 압축 시 요약돼 흐려지므로, 항상 지켜야 할 규칙은 CLAUDE.md에 적어 두세요.

컨텍스트 절약 전략

1) 서브에이전트로 탐색 격리

탐색/리서치는 서브에이전트에 맡겨 결과만 받아오면 메인 컨텍스트가 덜 닳습니다. 서브에이전트는 자체 컨텍스트 윈도우에서 파일을 읽고, 메인 세션에는 최종 요약과 작은 메타데이터(토큰 수·소요 시간)만 돌아옵니다.

2) 필요한 파일만 읽기

큰 파일을 통째로 읽기보다 필요한 부분만 지정하면 토큰을 아낍니다. 파일 읽기가 컨텍스트 사용량에서 가장 큰 비중을 차지하니, 프롬프트를 구체적으로 써서 읽는 파일 수 자체를 줄이는 편이 효과적입니다.

3) 작업 단위로 세션 분리

서로 다른 기능/버그를 한 세션에 몰아넣지 말고, 세션을 분리해 맥락 오염을 줄입니다.

/context 명령과 액셔너블 제안

/context 명령은 현재 세션의 컨텍스트 사용 현황을 색상 그리드로 시각화하고 구체적인 최적화 제안을 함께 보여줍니다(v2.1.74).

/context

컨텍스트를 많이 사용하는 도구 식별
메모리 비대화 감지 및 경고
용량 임계치 도달 시 구체적 대응 방안 제시

전체화면(fullscreen) 모드에서는 항목별 세부 분석이 접혀 그리드가 가려지지 않게 유지되며, /context all을 실행하면 세부 분석을 펼칠 수 있습니다.

자동 메모리(Auto memory)

Claude가 유용한 컨텍스트를 자동으로 메모리에 저장합니다(v2.1.59 이상 필요). 빌드 명령, 디버깅 인사이트, 아키텍처 노트, 코드 스타일 선호도처럼 다음 대화에 쓸모 있을 내용을 Claude가 스스로 판단해 기록하고, /memory로 언제든 확인·편집·삭제합니다.

저장 위치는 기본적으로 git 저장소 단위의 디렉터리 ~/.claude/projects/<project>/memory/이며, 같은 저장소의 모든 worktree와 하위 디렉터리가 이 디렉터리를 공유합니다(머신 로컬, 클라우드 공유 안 됨). 이 디렉터리의 MEMORY.md가 인덱스 역할을 하고, 세부 노트는 debugging.md 같은 토픽 파일로 분리됩니다.

MEMORY.md 적재 한도

세션 시작 시 MEMORY.md는 앞 200줄 또는 25KB 중 먼저 도달하는 지점까지만 적재됩니다. 그 이상은 시작 시 적재되지 않으며, 토픽 파일은 필요할 때 Claude가 직접 읽습니다. 이 한도는 MEMORY.md에만 적용되고, CLAUDE.md 파일은 길이와 무관하게 전부 적재됩니다(짧을수록 준수율이 높음).

자동 메모리 켜고 끄기

자동 메모리는 기본 활성화입니다. /memory의 토글로 끄거나, 프로젝트 설정의 autoMemoryEnabled로 제어합니다.

{
  "autoMemoryEnabled": false
}

환경 변수로 끄려면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정합니다.

autoMemoryDirectory 설정

자동 메모리 저장 디렉토리를 커스터마이즈할 수 있습니다(v2.1.74). 사용자 설정(~/.claude/settings.json) 또는 정책 설정, --settings 플래그에서만 받아들이며, 값은 절대 경로이거나 ~/로 시작해야 합니다.

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

프로젝트/로컬 설정에서는 무시

autoMemoryDirectory는 프로젝트/로컬 설정에서는 받아들이지 않습니다. 두 파일은 프로젝트 디렉터리 안에 있어, 복제된 저장소가 메모리 쓰기를 민감한 위치로 돌릴 수 있기 때문입니다. 또한 상대 경로(.claude/memory 등)는 허용되지 않으므로 절대 경로나 ~/ 경로를 사용하세요.

/compact 고급 옵션

이미지 보존

/compact 실행 시 이미지를 보존하여 프롬프트 캐시 재사용이 가능합니다(v2.1.69). 이미지가 포함된 대화에서도 캐시 효율이 떨어지지 않습니다.

compaction 후 세션 재개

compaction 후 세션을 재개하면 프리앰블 요약을 생략하여 불필요한 토큰 소비를 줄입니다(v2.1.69).

session recap과 `/recap` (v2.1.108~v2.1.110)

자리를 비웠다가 터미널로 돌아오면 Claude Code가 지금까지의 흐름을 한 줄 recap으로 보여줍니다. recap은 마지막 턴이 끝나고 최소 3분이 지난 뒤 터미널이 비활성 상태일 때 백그라운드에서 만들어져, 다시 돌아오면 바로 준비돼 있습니다. 세션에 턴이 최소 3개는 있어야 나타나고, 연속으로 두 번 나오지는 않습니다.

v2.1.108: /recap 명령으로 현재 세션의 한 줄 요약을 수동 생성
v2.1.110: compact·resume 이후의 recap 경로가 더 넓게 기본 활성화
자동 recap은 모든 플랜·프로바이더에서 기본 켜짐이며, 비대화형(non-interactive) 모드에서는 항상 생략됩니다.
끄려면 /config를 열어 Session recap을 비활성화합니다.

긴 세션에서 "어디까지 했는지"를 다시 읽느라 토큰을 버리는 일을 줄여 줍니다.

`/rewind`로 특정 지점부터 요약 (v2.1.32)

전체 대화를 압축하지 않고 선택한 메시지부터 요약할 수 있습니다. 빈 입력 상태에서 Esc를 두 번 누르면 rewind 메뉴가 열리고, 여기서 코드·대화를 이전 지점으로 되돌리거나 선택한 메시지부터 요약할 수 있습니다(/rewind, 별칭 /checkpoint·/undo). 초반의 중요한 맥락은 남겨 두고 그 뒤 구간만 정리할 때 쓸모가 있습니다.

Progress message compaction 개선

장시간 세션에서 progress message가 compaction을 넘어 살아남아 메모리가 점점 불어나던 문제를 고쳤습니다. (v2.1.77) 긴 세션을 이어갈 때 메모리가 더 안정적입니다.

Thinking Summaries 기본 비활성화 (v2.1.88)

대화형 세션에서 모델의 thinking summary가 기본적으로 생성되지 않습니다. 컨텍스트 소비가 줄어듭니다. 추론 과정을 펼쳐 확인하려면 showThinkingSummaries: true 설정을 활성화해야 합니다. (Anthropic API 대화형 세션은 기본적으로 redacted thinking 블록을 받으므로, 전체 요약을 보려면 동일하게 이 설정이 필요합니다.) thinking 출력은 평소 접혀 있고 Ctrl+O로 펼쳐 회색 이탤릭으로 볼 수 있으며, 접혀 있어도 thinking 토큰은 과금됩니다.

Fable 5는 adaptive thinking이 항상 켜져 있습니다. MAX_THINKING_TOKENS=0, 세션 thinking toggle, alwaysThinkingEnabled로 thinking 자체를 끌 수 없으며, 실제 깊이는 /effort로 조절합니다.

토큰 절약 개선

Read 도구 압축 포맷 (v2.1.86)

Read 도구가 압축된 줄번호 포맷을 사용하고, 이미 읽은 파일의 내용이 변경되지 않았으면 중복 읽기를 제거합니다. 같은 파일을 반복 참조하는 세션에서 컨텍스트 절약 효과가 큽니다.

`@` 멘션 토큰 오버헤드 감소 (v2.1.86)

파일을 @로 멘션할 때 발생하는 토큰 오버헤드가 감소했습니다. 여러 파일을 컨텍스트에 추가하는 워크플로우에서 효율이 향상됩니다.

Edit 도구 앵커 축소 (v2.1.91)

Edit 도구가 더 짧은 old_string 앵커를 사용해 수정 패치 자체가 차지하는 토큰을 줄입니다. 같은 파일을 여러 번 고치는 세션에서 누적 효과가 큽니다.

메모리 파일 인터랙션 개선 (v2.1.86)

메모리 파일명에 호버 시 하이라이트, 클릭 시 열기 기능이 붙었습니다. 메모리 관리가 한결 직관적입니다.

prompt cache 만료 복귀 힌트 (v2.1.92)

Pro 사용자는 prompt cache가 만료된 뒤 세션으로 복귀하면, 다음 턴이 대략 얼마나 많은 토큰을 uncached로 다시 보낼지 푸터 힌트를 볼 수 있습니다. 긴 세션을 이어갈지 /compact 또는 새 세션으로 갈아탈지 판단할 때 도움이 됩니다.

컨텍스트 윈도우 설정

도구 결과 디스크 자동 저장

도구 결과가 50K자를 초과하면 디스크에 자동 저장됩니다(v2.1.51, 기존 100K에서 하향). 컨텍스트 윈도우 절약 효과가 더 커졌습니다.

백그라운드 Bash 출력 제한

백그라운드에서 실행 중인 Bash 작업의 출력이 5GB를 초과하면 자동 종료됩니다. (v2.1.77) 대용량 로그 출력이 디스크를 채우는 것을 방지하며, stderr에 종료 사유가 기록됩니다.

1M 컨텍스트 윈도우

Fable 5, Opus 4.6 이상, Sonnet 4.6은 대규모 코드베이스의 장기 세션을 위한 1M(100만) 토큰 컨텍스트 윈도우를 지원합니다. 실제 활성화 여부는 모델과 플랜에 따라 다릅니다.

Fable 5: Claude Code v2.1.170 이상과 조직 접근 권한이 필요하며, Anthropic API에서 1M 컨텍스트를 기본 지원합니다.
Max·Team·Enterprise 플랜: Opus가 추가 설정 없이 1M 컨텍스트로 자동 업그레이드됩니다(이전부터 기본 활성화, v2.1.75). Team Standard·Premium 좌석 모두 해당.
Sonnet의 1M 컨텍스트: 자동 업그레이드 대상이 아니며 모든 구독 플랜(Max 포함)에서 **추가 사용 크레딧(usage credits)**이 필요합니다.
Pro: Opus·Sonnet 모두 사용 크레딧이 필요합니다.
API·종량제(pay-as-you-go): 전체 접근 가능.

200K를 넘는 토큰에 별도 프리미엄 가격은 없으며, 표준 모델 가격이 적용됩니다.

모델 별칭으로는 fable[1m], sonnet[1m], opus[1m]을 사용하거나, 전체 모델명에 [1m]을 붙일 수 있습니다.

# 1M 컨텍스트 모델 선택
/model opus[1m]
/model sonnet[1m]
/model claude-fable-5[1m]
/model claude-opus-4-8[1m]

모델 별칭과 1M 옵션 확인

fable·opus·sonnet 별칭은 프로바이더별 권장 버전을 가리키며 시간이 지나면 업데이트됩니다. 현재 Anthropic API에서 fable은 Fable 5, opus는 Opus 4.8, sonnet은 Sonnet 4.6으로 해석됩니다(프로바이더에 따라 다름). 계정이 1M 컨텍스트를 지원하면 /model 피커에 옵션이 나타나며, 실제 지원 여부는 /model과 /status에서 확인하세요. opusplan 별칭의 plan 모드 Opus 단계는 표준 200K 윈도우로 동작하므로 자동 1M 업그레이드가 적용되지 않습니다.

# 1M 컨텍스트 비활성화 (필요 시) — /model 피커에서 1M 변형이 제거됩니다
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1

참고 문서

컨텍스트 윈도우 개요와 압축 동작: https://code.claude.com/docs/en/context-window (영어)
/compact·/context·/recap 등 명령 레퍼런스: https://code.claude.com/docs/en/commands (영어)
메모리 구조와 자동 메모리: https://code.claude.com/docs/en/memory (영어)
모델 별칭과 1M 컨텍스트 설정: https://code.claude.com/docs/en/model-config (영어)
서브에이전트 개념: https://code.claude.com/docs/en/sub-agents (영어)