Ch9. 컨텍스트 관리

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

/compact 명령

컨텍스트가 길어지면 /compact로 요약·압축합니다.

/compact

포커스를 지정해 특정 내용 위주로 보존할 수도 있습니다.

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

압축 타이밍 가이드

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

CLAUDE.md의 Compact Instructions

/compact 후에도 반드시 보존할 내용을 CLAUDE.md에 모아두면 안전합니다.

## Compact Instructions

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

컨텍스트 절약 전략

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

탐색/리서치는 서브에이전트에 위임해 결과만 받아오면 메인 컨텍스트가 덜 소모됩니다.

2) 필요한 파일만 읽기

큰 파일 전체를 읽기보다, 필요한 부분만 지정하면 토큰을 절약할 수 있습니다.

3) 작업 단위로 세션 분리

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

/context 명령과 액셔너블 제안

/context 명령은 현재 세션의 컨텍스트 사용 현황을 분석하고 구체적인 최적화 팁을 제안합니다(v2.1.74).

/context

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

자동 메모리 기록

Claude가 유용한 컨텍스트를 자동으로 메모리에 저장합니다(v2.1.59). 수동으로 /memory를 실행하지 않아도 중요한 설정·패턴·선호도가 기록되며, /memory로 언제든 확인·관리할 수 있습니다.

autoMemoryDirectory 설정

자동 메모리 저장 디렉토리를 커스터마이즈할 수 있습니다(v2.1.74).

{
  "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을 자동으로 보여줄 수 있습니다.

• v2.1.108: /recap 명령으로 현재 세션의 한 줄 요약을 수동 생성
• v2.1.110: compact 또는 resume 뒤의 recap 경로가 더 넓게 기본 활성화
• 비활성화: /config 또는 CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0

장기 세션에서 “어디까지 했는지”를 다시 읽느라 토큰을 낭비하는 일을 줄여줍니다.

"Summarize from here" 구간 요약

특정 메시지부터 구간 요약을 수행할 수 있습니다(v2.1.32). 전체 대화를 압축하지 않고 원하는 지점부터만 요약해, 중요한 초반 맥락을 보존합니다.

Progress message compaction 개선

장시간 세션에서 progress message가 compaction을 살아남아 메모리가 점진적으로 증가하는 문제가 수정되었습니다. (v2.1.77) 긴 세션을 유지할 때 메모리 안정성이 향상됩니다.

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

모델의 thinking summary가 기본적으로 생성되지 않습니다. 컨텍스트 소비가 줄어들지만, 추론 과정을 확인하려면 showThinkingSummaries: true 설정을 활성화해야 합니다.

토큰 절약 개선

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) 대용량 로그 출력이 디스크를 채우는 것을 방지합니다.

1M 컨텍스트 윈도우

Max, Team, Enterprise 플랜에서 Opus 4.6의 1M 컨텍스트 윈도우가 기본 활성화됩니다(v2.1.75). 이전에는 Fast mode에서만 지원했지만, 이제 모든 모드에서 기본 적용됩니다.

# 1M 컨텍스트 비활성화 (필요 시)
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1

참고 문서

• /compact 명령: https://code.claude.com/docs/ko/slash-commands (한국어)
• 서브에이전트 개념: https://docs.claude.com/en/docs/claude-code/subagents (영어)
• 메모리 구조와 보존 전략: https://docs.claude.com/ko/docs/claude-code/memory (한국어)