Claude Code가 느려지는 이유와 컨텍스트 관리 전략

Claude Code를 사용하다 보면 세션(대화)이 길어질수록 응답이 느려지거나 맥락을 잃어버리는 경험을 하게 됩니다.

이 문제의 근본 원인은 컨텍스트 윈도우에 있습니다.

이번 포스팅에서는 컨텍스트 윈도우의 개념과 Claude Code에서 제공하는 관리 명령어, 그리고 auto-compact 설정의 트레이드오프까지 정리합니다.

 

컨텍스트 윈도우란?

컨텍스트 윈도우는 AI가 하나의 세션 내에서 동시에 기억하고 처리할 수 있는 토큰의 총량입니다.

대화 기록, 업로드된 파일, 코드 등 세션에서 주고받은 모든 데이터가 이 공간을 소비합니다.

예를들어, Claude 3.5 모델(Sonnet, Opus 등)은 200K(약 20만) 토큰의 컨텍스트 윈도우를 제공합니다.

이 공간이 가득 차면 AI는 이전 내용을 잊기 시작하거나, 정보 과부하로 인해 잘못된 답변(환각)을 생성할 수 있습니다.

 

컨텍스트 관리 명령어

/compact — 압축 요약

/compact는 현재까지의 대화 내역을 요약해 압축하는 명령어입니다.

이전 대화를 완전히 삭제하지 않고, 핵심 정보만 남긴 요약본으로 교체합니다.

보존할 내용을 직접 지정하는 것도 가능합니다.

/compact 코딩 패턴과 결정사항만 유지해줘

중요한 맥락이 있는 세션이라면 auto-compact에 맡기기보다 수동으로 먼저 실행해 보존할 내용을 직접 지정하는 편이 안전합니다.

/clear — 전체 초기화

/clear는 대화 내역을 완전히 삭제하고 빈 상태로 시작하는 명령어입니다. 

/compact와 달리 이전 맥락이 전혀 남지 않습니다.

효과적으로 활용하려면 작업을 작은 단위로 나눠 각 단계가 끝날 때마다 세션을 격리하는 방식을 권장합니다.

작업을 단계별로 모듈화하고, 각 단계의 출력을 검증한 뒤, /clear로 다음 단계와 격리하는 흐름입니다.

이렇게 하면 컨텍스트가 현재 작업과 관련된 정보로만 채워져 응답 품질을 더 오래 유지할 수 있습니다.

 

auto-compact: 자동 압축

Claude Code에는 auto-compact 기능이 내장되어 있습니다.

컨텍스트 윈도우가 한계에 가까워지면 자동으로 /compact를 실행해 세션이 중간에 끊기지 않도록 유지해 줍니다.

auto-compact는 켜고 끌 수 있는 설정입니다.

이 설정이 실제로 컨텍스트 공간에 얼마나 영향을 미치는지 직접 측정해봤습니다.

auto-compact: true 상태

autoCompact: false 상태

 

true 상태에서는 200K 중 약 45K가 버퍼로 예약되어 실제 작업에 쓸 수 있는 공간이 그만큼 줄어듭니다. 

false 상태에서는 200K 를 작업공간으로 사용가능합니다.  

 

단, 트레이드오프가 있습니다.

auto-compact를 끄면 컨텍스트가 100%에 도달한 시점에서 /compact를 실행할 공간 자체가 없어 Prompt is too long 에러가 발생할 수 있습니다.

 

현재 사용량은 /cost 명령어로 확인할 수 있습니다.

 

중요한 건 컨텍스트가 차기 전에 먼저 행동하는 것입니다.

컨텍스트가 가득 찬 상태에서는 모델이 이전 맥락을 잃기 시작하고 응답 품질이 눈에 띄게 떨어집니다.

일반적으로 70% 시점을 기준으로 /compact를 실행하는 것을 권장합니다.

이렇게 하면 모델이 전체 맥락을 유지한 상태에서 압축이 이루어지기 때문에 요약의 품질도 높아집니다.

 

auto-compact On/Off 방법

터미널에서 /config 명령어를 입력하면 설정 화면으로 진입할 수 있습니다.

여기서 autoCompact 옵션을 true/false로 변경하면 됩니다.

 

CLAUDE.md로 핵심 정보 유지하기

컨텍스트를 압축하거나 초기화하더라도 프로젝트의 핵심 정보가 사라지지 않도록 하려면 CLAUDE.md 파일을 활용하는 것이 좋습니다.

아키텍처 결정사항, 코딩 컨벤션, 주요 도메인 개념 등을 이 파일에 정리해두면 세션이 새로 시작되더라도 에이전트가 프로젝트 맥락을 유지할 수 있습니다.

 

예를 들어 아래와 같이 작성할 수 있습니다.

# 프로젝트 개요
- 앱 이름: MyApp
- 아키텍처: MVVM + Clean Architecture

# 코딩 컨벤션
- 비동기 처리는 Swift Concurrency(async/await) 사용
- 외부 의존성 주입은 DIContainer를 통해 처리

# 주요 결정사항
- 네트워크 레이어는 URLSession 기반으로 직접 구현 (Alamofire 미사용)
- 로컬 저장소는 SwiftData 사용

/compact나 /clear 이후에도 이 파일의 내용은 매 세션마다 에이전트에게 자동으로 주입되므로, 반복적으로 설명할 필요 없이 프로젝트 맥락을 일관되게 유지할 수 있습니다.