26장: 핵심 역량으로서의 컨텍스트 관리

이것이 중요한 이유

Claude에서 가장 과소평가된 하위 시스템을 하나만 선택해야 한다면 코드의 전체 코드베이스는 컨텍스트 관리입니다. 허가 시스템이 눈길을 끌고 Agent Loop가 핵심이며 프롬프트가 표시됩니다. 엔지니어링은 널리 알려져 있지만 상황 관리가 핵심입니다. AI 에이전트가 "계속 작업"할 수 있는지 여부를 결정하는 인프라 효과적으로."

200K 토큰 컨텍스트 창은 넉넉해 보이지만 실제 시나리오에서는 예상보다 빨리 소비됩니다. 시스템 프롬프트에 약 15-20K, 각 도구 호출 결과는 5-50K가 소요되며 몇 라운드 후에 파일 읽기와 코드 검색에 이미 절반을 사용했습니다. 더 비판적으로, 컨텍스트 창은 단순한 "용량" 문제가 아니라 "정보" 문제입니다. 밀도" 문제. 창이 오래된 도구 결과로 가득 차면, 중복된 파일 내용, 해결된 토론, 모델의 관심 희석되어 응답 품질이 저하됩니다.

3부(9~12장)에서 분석한 컨텍스트 관리 시스템 공통 주제로 6가지 핵심 원칙을 공개합니다. 컨텍스트 창은 다음과 같습니다. 메모리만큼 주의 깊게 관리해야 하는 희소 자원입니다.

소스코드 분석

26.1

원칙 1: 모든 것에 예산을 책정하세요 정의: 컨텍스트 창에 들어가는 모든 콘텐츠는 다음을 충족해야 합니다. 명확한 토큰 예산 한도가 있어야 하며 예외는 없습니다.

Claude Code의 예산 시스템은 해당 컨텍스트의 모든 콘텐츠 소스를 포괄합니다. 창문:

표 26-1: Claude Code의 토큰 예산 시스템

디자인의 세분화에 주목하세요. '총 예산'만 있는 것이 아닙니다. 뿐만 아니라 "항목별 예산"도 있습니다. 둘 다의 소스:

// restored-src/src/constants/toolLimits.ts:13
export const DEFAULT_MAX_RESULT_SIZE_CHARS = 50_000

// restored-src/src/constants/toolLimits.ts:49
export const MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000

MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000은 N개의 병렬 도구를 방지합니다. 동시에 큰 결과를 반환하고 컨텍스트를 넘치게 하는 것으로부터 — 각 도구 결과가 50K 이내인 경우에도 10개의 병렬 도구로 생성할 수 있습니다. 500,000자. 메시지당 예산은 이에 대한 보호 장치입니다. "합법적이지만 위험한" 조합.

스킬 목록의 1% 예산은 특히 주목할 만합니다.

// restored-src/src/tools/SkillTool/prompt.ts:20-23
// Skill listing gets 1% of the context window (in characters)
export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01
export const CHARS_PER_TOKEN = 4
export const DEFAULT_CHAR_BUDGET = 8_000 // Fallback: 1% of 200k × 4

사용자가 점점 더 많은 기술을 설치함에 따라 기술 목록이 늘어날 수 있습니다. 바운드 없이. Claude Code의 솔루션은 3단계 절단입니다. 캐스케이드: 첫 번째 설명 잘림(MAX_LISTING_DESC_CHARS = 250), 그런 다음 우선순위가 낮은 기술을 잘라내고 마지막으로 해당 기술의 이름만 유지합니다. 내장된 스킬. 이렇게 하면 기술 목록이 다음 이상을 차지하지 않도록 보장됩니다. 컨텍스트 창의 1% — 사용자가 1,000개의 스킬을 설치한 경우에도 마찬가지입니다.

안티패턴: 무제한 콘텐츠 주입. 주입 도구 결과, 파일 내용 또는 구성 정보를 컨텍스트 창에 표시 제한 없이 궁극적으로 컨텍스트를 다음으로 채웁니다. 정보 밀도가 낮은 콘텐츠.

26.2

원칙 2: 상황 위생 정의: 컨텍스트 관리는 단순히 콘텐츠를 압축하는 것이 아닙니다. 이미 창에 있지만 고비용을 사전에 필터링하는 것에 대해 주입 전 현재 에이전트의 목표와 관련 없는 정보.

Claude Code는 하위 에이전트 내에서 이 원칙을 철저하게 구현합니다. 체계. Explore / Plan 같은 읽기 전용 에이전트는 기본 에이전트를 상속하지 않습니다. 에이전트의 전체 제어 영역: runAgent() 사전에 생략 CLAUDE.md 조건이 충족되면 계층적 지시어 Explore / Plan에 대해 gitStatus을 제거합니다. 그 이유는 이것이 아니다. 정보는 결코 유용하지 않지만 일반적으로 사중입니다. 읽기 전용 검색 에이전트: 커밋 규칙, PR 규칙 및 린트 제약 조건은 주 에이전트에 의해서만 해석되면 됩니다. 탁한 git status은 수십 KB를 차지할 수 있지만 코드 검색에는 도움이 되지 않습니다.

더 중요한 것은 이러한 트리밍이 생성될 때 발생한다는 것입니다. 하위 에이전트의 컨텍스트, 토큰 압력 후 압축 수정이 아님 빌드합니다. 표준 하위 에이전트는 검색 노이즈를 자체적으로 격리합니다. 대화, 요약된 결과만 부모에게 반환 Explore 심지어 기본값은 omitClaudeMd: true입니다. 이것이 바로 "맥락"의 본질이다 위생": 정보 밀도가 낮은 콘텐츠가 창에 들어오지 않도록 하세요. 먼저 압축 시스템이 나중에 정리되기를 바랍니다.

안티패턴: 전체 상속. 모든 도우미 에이전트에 전체 시스템 프롬프트, CLAUDE.md, git 상태, 최근 도구 출력, 사용자 기본 설정으로 인해 모든 읽기 전용 쿼리가 중복됩니다. 값비싼 접두사 비용을 지불합니다.

26.3

원칙 3: 중요한 것을 보존하세요 정의: 압축이 필요하지만 압축 후 압축도 필요합니다. 가장 중요한 컨텍스트를 선택적으로 복원합니다.

자동 압축(자세한 내용은 9장 참조)은 전체 파일을 압축합니다. 대화 기록을 요약으로 정리하여 컨텍스트 공간을 확보합니다. 하지만 압축하면 특정 코드 내용, 파일 경로 및 정확한 라인이 손실됩니다. 번호 참조. 모델이 파일 내용을 완전히 잃어버린 경우 이전에 압축한 후에 읽었으므로 다시 읽어야 하므로 낭비됩니다. 도구 호출 및 사용자 대기 시간.

Claude Code의 솔루션은 압축 후 복원입니다(이 장 참조). 자세한 내용은 10):

// restored-src/src/services/compact/compact.ts:122
export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5

복원 전략 흐름:

그림 26-1: 다짐-복원 흐름

복원 전략의 핵심은 선택성입니다: 복원하지 않음 모든 파일(최근 5개 제외); 전체 파일 내용을 복원하지 않음 하지만 5K 토큰 내에서는 잘립니다. 총 50K를 초과하지 않습니다. 이 숫자 신중하게 고려된 장단점을 반영합니다. 너무 많이 복원하는 것은 압축하지 않는 것과 동일하며, 너무 적게 복원하는 것은 과도하게 압축.

스킬 회복 디자인도 똑같이 세련되었습니다. 압축 후는 그렇지 않습니다. 이미 전송된 스킬의 이름(sentSkillNames)을 다시 주입하십시오. 모델은 여전히 ​​SkillTool의 스키마를 보유하고 있습니다. 즉, 스킬 시스템을 알고 있습니다. 존재하는데, 구체적인 스킬 내용을 잊어버렸을 뿐입니다. 이렇게 하면 저장됩니다. 약 4K 토큰.

안티패턴: 전체 압축 또는 전체 보존. 복원하거나 아무것도(모델을 처음부터 다시 시작해야 함) 또는 보존하려고 시도함 모든 것(압축 효율성은 0입니다).

26.4

원칙 4: 알리고 숨기지 마세요 정의: 콘텐츠가 잘리거나 압축되면 모델은 다음을 수행해야 합니다. 무슨 일이 일어났는지 알려줌으로써 적극적으로 정보를 얻을 수 있습니다. 완전한 정보.

Claude Code는 이 원칙을 여러 수준에서 실천합니다.

도구 결과 잘림 알림. 도구 결과가 50K를 초과하는 경우 문자(DEFAULT_MAX_RESULT_SIZE_CHARS), 전체 결과는 다음과 같습니다. 디스크에 기록(restored-src/src/utils/toolResultStorage.ts)하고 모델은 잘림 알림을 포함한 미리보기 메시지를 수신합니다. 전체 콘텐츠에 대한 디스크 경로입니다. 따라서 모델은 다음을 알고 있습니다. (1) 자신이 보는 것은 모든 것이 아니라, (2) 모든 것을 얻는 방법.

캐시 마이크로 압축 알림(자세한 내용은 11장 참조) cache_edits이 이전 도구 결과를 제거하면 notifyCacheDeletion() "일부 오래된 도구 결과가 정리되었습니다"라고 모델에 알립니다. 이렇게 하면 모델이 더 이상 존재하지 않는 콘텐츠를 참조하는 것을 방지할 수 있습니다.

파일 읽기 페이지 매기기. FileReadTool은 기본적으로 2000줄을 읽습니다. 오프셋/제한 매개변수를 통해 페이지 매김을 지원합니다. 도구 설명은 이 동작을 명시적으로 설명합니다. 모델은 그 내용만 알고 있습니다. 기본적으로 처음 2000줄을 확인하고 오프셋을 지정할 수 있습니다. 나중에 콘텐츠가 필요합니다.

압축 요약의 명시적 선언. 압축 프롬프트 (자세한 내용은 9장 참조) 요약에는 "어디서?"가 포함되어야 합니다. 진행 상황" 및 "아직 수행해야 할 작업" — 압축 후 모델은 작업의 어느 단계에 있는지 알고 있습니다. 그만큼 <analysis> 압축 프롬프트의 초안 블록 (restored-src/src/services/compact/prompt.ts:31) 모델을 먼저 사용합니다. 대화 내용을 분석한 후 구조화된 요약을 생성합니다. 분석 블록은 포맷 중에 제거되며 최종 공간을 차지하지 않습니다. 맥락 공간.

안티패턴: 자동 잘림. 도구 결과 자르기 또는 삭제 모델이 알지 못하는 상황 콘텐츠. 모델이 만들 수도 있습니다. 불완전한 정보에 기초한 잘못된 결정 또는 "조작" 내용을 잘 기억하지 못합니다. 왜냐하면 내용을 모르기 때문입니다. 정보가 불완전합니다.

26.5 원칙 5: 회로 차단 런어웨이 루프

정의: 자동화된 프로세스가 연속적으로 실패하면 무한히 재시도하는 대신 강제로 중지하는 메커니즘이어야 합니다.

자동 압축 회로 차단기가 가장 직접적인 구현입니다. MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3 (restored-src/src/services/compact/autoCompact.ts:70) — 3 이후 연속 실패하면 시도를 중단하세요. 소스 코드 주석(장 참조) 전체 코드 참조에 대한 25, 원칙 6)은 다음을 문서화합니다. 이 숫자에 대한 엔지니어링 근거: BigQuery 데이터에 따르면 1,279 세션에서 50회 이상 연속 압축 실패(최대 3,272회)가 발생했습니다. 하루에 약 250,000개의 API 호출을 낭비하고 있습니다.

보다 광범위하게 Claude Code는 유사한 회로 차단 메커니즘을 구현합니다. 여러 하위 시스템에 걸쳐:

표 26-2: Claude Code의 회로 차단기 개요

각 회로 차단기는 동일한 패턴을 따릅니다. 합리적인 재시도 설정 한도를 초과하면 안전하지만 기능적으로 제한된 상태로 저하됩니다. 충돌이나 무한 루프가 발생하지 않습니다.

안티패턴: 무한 재시도. "압축에 실패했습니다. 다시 시도해 보세요. 실패했습니다. 다시? 다른 매개변수로 시도해 보세요." 이는 특히 위험합니다. AI 에이전트 — 재시도할 때마다 API 호출(실제 돈)이 소비되며 실패 그 이유는 종종 체계적입니다(컨텍스트가 너무 커서 압축할 수 없습니다). 요약 토큰 예산)이므로 재시도해도 결과가 변경되지 않습니다.

26.6

원칙 6: 보수적으로 추정 정의: 토큰 계산 및 예산 할당에서는 과소평가보다 소비를 과대평가하라 - 과소평가가 이끈다 오버플로하면 과대평가는 공간을 조금 더 낭비할 뿐입니다.

Claude Code의 토큰 추정은 보수적인 방향을 선택합니다. 모든 시나리오(자세한 내용은 12장 참조):

표 26-3: 토큰 추정 전략 비교

2바이트/토큰으로 JSON을 추정하는 것은 특히 의미 있는 설계입니다. 선택. JSON 구조 문자({}, [], "", :, ,) 토큰화 자연어보다 훨씬 덜 효율적입니다. 100바이트의 JSON은 40-50개의 토큰을 소비하는 반면, 영어 100바이트에는 25-30개만 필요합니다. 토큰. 일반적인 4바이트/토큰 추정치를 사용하는 경우 JSON 밀도 도구 결과가 심각하게 과소평가되어 잠재적으로 맥락을 야기할 수 있습니다. 과다.

스킬 목록 예산에도 이를 반영합니다. (restored-src/src/tools/SkillTool/prompt.ts:22): CHARS_PER_TOKEN = 4 토큰 예산을 캐릭터 예산으로 변환하는 데 사용됩니다. 초과 지출이 없도록 문자/토큰 비율을 보수적으로 유지하세요.

보수적인 추정의 이점은 비용보다 훨씬 큽니다. 그만큼 토큰 소비를 과대평가하는 최악의 경우 압축이 발생합니다. early — 사용자가 몇 초 더 기다립니다. 최악의 경우 토큰 소비를 과소평가하는 것은 prompt_too_long 오류입니다 — API 통화 실패, 비상 상황 삭제 필요, 잠재적으로 손실됨 중요한 정보.

안티패턴: 정확한 계산에 대한 환상. ~을 시도하다 클라이언트 측에서 토큰 수를 정확하게 계산합니다. API만 서버 측 토크나이저는 정확한 값을 제공할 수 있습니다(모든 클라이언트 측 개수). 추정치입니다. 추정치이므로 편향되어 있어야 합니다. 안전한 방향.

패턴 증류

6가지 원칙

요약 테이블

표 26-4: 6가지 컨텍스트 관리 원칙 요약

관계

원칙 사이

그림 26-2: 6가지 컨텍스트 관리의 관계 다이어그램 원칙

예산 모든 것은 토대입니다. 각 콘텐츠 소스. 컨텍스트 위생은 어떤 콘텐츠를 결정합니다. 현재 창에 전혀 들어가서는 안됩니다. 중요한 것을 보존하세요 압축 후 복원을 처리하며 알리고 숨기지 마세요는 모델은 잘린 내용을 알고 있습니다. 회로 차단 런어웨이 루프 자동화된 프로세스가 예산을 초과하는 것을 방지합니다. 예상 보수적으로 과소평가로 인해 예산이 회피되지 않도록 보장합니다.

패턴: 계층형

토큰예산

• 문제 해결: 제한된 수량을 위해 경쟁하는 여러 콘텐츠 소스 맥락 공간
• 핵심 접근 방식: 소스별 독립 예산 + 총 예산, 초과분에 대한 잘림 계단식 처리
• 코드 템플릿: 항목당 한도(50K) → 집계 한도 (200K/메시지) → 전역 제한(컨텍스트 창 - 출력 예약 - 완충기)
• 전제조건: 콘텐츠의 토큰 소모량을 추정할 수 있는 능력 주사하기 전에

패턴: 컨텍스트

위생

• 문제 해결: 반복적으로 상속되는 읽기 전용 도우미 에이전트 관련성이 없지만 비용이 많이 드는 접두사 콘텐츠
• 핵심 접근 방식: 현재와 관련 없는 맥락을 생략합니다. 스폰 시간에 책임을 맡고 탐색 소음을 내부에서 격리합니다. 하위 대화
• 전제조건: 현재 어떤 상황인지 구별하는 능력 에이전트가 실제로 소비합니다.

패턴:

압축-복원주기

• 문제 해결: 압축이 중요한 컨텍스트를 잃습니다.
• 핵심 접근 방식: 압축 전 스냅샷 → 컴팩트 → 선택적으로 가장 최근/가장 중요한 콘텐츠 복원
• 전제조건: 어떤 콘텐츠가 '가장 최근에' 추적되었는지 추적하는 기능 사용된"

패턴: 회로

차단기

• 문제 해결: 자동화된 프로세스가 무한 반복됩니다. 비정상적인 상태
• 핵심 접근 방식: N회 연속 실패 후 중지, 안전한 수준으로 저하 상태
• 전제조건: "실패" 및 사후 성능 저하에 대한 정의된 기준 행동

할 수 있는 일

1. 에이전트의 컨텍스트 소비를 감사합니다. 토큰 수 측정 각 콘텐츠 소스는 실제 시나리오에서 소비하고 가장 큰 소비자
2. 도구 결과의 크기 제한을 설정합니다. 파일 읽기, 데이터베이스 확인 쿼리 및 API 호출 결과에는 문자/줄 수 제한이 있습니다.
3. 읽기 전용 도우미를 줄입니다. 검색형과 기획형 에이전트는 전체 CLAUDE.md, git 상태 및 기본적으로 최근 도구 출력
4. 압축 후 복원을 구현합니다. 귀하의 대리인이 다음을 사용하는 경우 컨텍스트 압축, 복원 전략 설계 — 따라서 압축 후 모델은 0부터 시작할 필요가 없습니다.
5. 잘라낼 때 모델에 알립니다. 모델에게 "이것은 잘렸습니다. 정식 버전이 여기에 있습니다." — 이것이 훨씬 낫습니다. 자동으로 자르고 모델이 정보를 발견하도록 함 그 자체로 공백
6. 회로 차단기를 추가하세요. 잠재적인 재시도 제한 설정 루핑 자동화 프로세스. 저하된 작업은 항상 다음보다 낫습니다. 무한 루프