Ch9. 컨텍스트 관리

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

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

/compact 명령

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

/compact

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

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

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

압축 타이밍 가이드

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

CLAUDE.md의 Compact Instructions

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

## Compact Instructions

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

컨텍스트 절약 전략

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의 토글로 끄거나, 프로젝트 설정의 autoMemoryEnabled로 제어합니다.

{
  "autoMemoryEnabled": false
}

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

autoMemoryDirectory 설정

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

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

/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) 긴 세션을 이어갈 때 메모리가 더 안정적입니다.

Sonnet 5의 1M 컨텍스트는 v2.1.247부터 약 967k 토큰에서 auto-compaction을 시작합니다. 이전 약 934k보다 작업 여유가 늘었지만, 장기 세션의 결정 사항은 여전히 CLAUDE.md나 작업 문서에 남겨 두세요.

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

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

Fable 5.1과 Fable 5는 adaptive thinking이 항상 켜져 있습니다. MAX_THINKING_TOKENS=0, 세션 thinking toggle, alwaysThinkingEnabled로 thinking 자체를 끌 수 없으며, 실제 깊이는 /effort로 조절합니다. Fable 5.1은 tool 호출 사이의 진행 메시지도 thinking block으로 돌려주므로, Messages API에서 이를 표시하려면 thinking.display: "updates"(beta) 또는 "summarized"를 설정합니다.

토큰 절약 개선

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

• Fable 5.1: Claude Code v2.1.255 이상과 조직 접근 권한이 필요하며, 1M 컨텍스트가 기본이자 최대입니다. fable[1m] 표기도 v2.1.255 이상에서 동작합니다. prompt cache read가 $0.25/MTok로 Fable 5의 1/4이라 긴 컨텍스트를 반복 읽는 세션 비용이 낮아졌습니다.
• Fable 5: Claude Code v2.1.170 이상과 조직 접근 권한이 필요하며, Anthropic API에서 1M 컨텍스트를 기본 지원합니다. v2.1.255 이상에서는 /model claude-fable-5로만 선택합니다.
• Sonnet 5: Claude Code v2.1.197 이상에서 사용할 수 있으며, Anthropic API에서는 200K 변형 없이 1M 컨텍스트를 기본 지원합니다. LLM gateway 뒤에서는 sonnet[1m]으로 1M 지원을 명시할 수 있습니다.
• Max·Team·Enterprise 플랜: Opus가 추가 설정 없이 1M 컨텍스트로 자동 업그레이드됩니다(이전부터 기본 활성화, v2.1.75). Team Standard·Premium 좌석 모두 해당.
• Sonnet 4.6의 1M 컨텍스트: Sonnet 5 이전의 Sonnet 경로에서는 자동 업그레이드 대상이 아니며 모든 구독 플랜(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-1[1m]
/model claude-opus-5

# 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 (영어)