컨텍스트 윈도우 관리: 50번의 세션에서 배운 AI 개발의 교훈

50번의 Claude Code 개발 세션에서 토큰 소비량을 측정했습니다. 패턴은 일관적이었습니다. 하드 리밋이 압축을 트리거하기 훨씬 전인 컨텍스트 사용률 약 60% 지점에서 출력 품질이 저하되기 시작합니다.¹

TL;DR

컨텍스트 윈도우 소진은 AI 코딩 품질을 조용히 저하시킵니다. Claude Code 인프라와 블로그 품질 시스템을 구축하며 50번의 세션을 추적한 결과, 수 시간에 걸친 세션에서도 출력 품질을 유지하는 세 가지 패턴을 발견했습니다. 각 하위 작업 완료 후 선제적 압축, 컨텍스트 경계를 넘어 지속되는 파일시스템 기반 메모리, 그리고 메인 컨텍스트를 가볍게 유지하는 서브에이전트 위임입니다. 핵심 통찰은 컨텍스트 윈도우를 끝없는 대화 스레드가 아닌 희소한 자원으로 다루어야 한다는 것입니다.

품질 저하의 실제 양상

모든 파일 읽기, 도구 출력, 대화 턴은 토큰을 소비합니다. 대용량 파일 한 번 읽기(2,000줄)만으로 15,000~20,000 토큰이 소비될 수 있습니다. 파일 10개를 읽고 여러 명령을 실행한 후에는 컨텍스트 윈도우에 실제 지시사항보다 도구 출력이 더 많아집니다.²

품질 저하는 미묘합니다. Claude는 “컨텍스트가 80% 찼습니다”라고 알려주지 않습니다. 대신 모델이 다음과 같은 증상을 보이기 시작합니다: - 20분 전에 설정한 이전 지시사항을 잊어버림 - 세 턴 전에 이미 거부된 제안을 반복함 - 대화 초반에 확립한 패턴을 놓침 - 다중 파일 변경의 일관성이 떨어짐

심의 시스템을 구축하면서 이 패턴을 발견했습니다. 8개의 Python 모듈에 걸쳐 정밀한 다중 파일 편집으로 시작된 세션이 90분쯤 되자 단일 파일에만 집중하는 터널 비전으로 퇴화했습니다. 에이전트가 이전에 읽은 아키텍처를 참조하지 않게 되었는데, 해당 컨텍스트가 이미 압축되어 사라졌기 때문입니다.

전략 1: 선제적 압축

Claude Code의 /compact 명령은 대화를 요약하고 컨텍스트 공간을 확보합니다. 시스템은 핵심 결정, 파일 내용, 작업 상태를 보존하면서 장황한 도구 출력을 제거합니다.³

압축 시점: - 뚜렷한 하위 작업을 완료한 후 (기능 구현, 버그 수정) - 코드베이스의 새로운 영역을 시작하기 전 - Claude가 이전 컨텍스트를 반복하거나 잊어버리기 시작할 때

집중적인 세션에서는 대략 25~30분마다 압축합니다. 심의 인프라 구축(PRD 9개, Python 3,455줄) 중에는 각 PRD가 완료될 때마다 압축을 실행했습니다. 매번 압축은 아키텍처 결정을 보존하면서 다음 구현 단계를 위한 컨텍스트를 확보했습니다.

전략 2: 파일시스템을 메모리로 활용

컨텍스트 경계를 넘어 가장 신뢰할 수 있는 메모리는 파일시스템에 존재합니다. Claude Code는 모든 세션 시작 시와 매번 압축 후에 CLAUDE.md 파일과 메모리 파일을 읽습니다.⁴

저의 .claude/ 디렉토리는 구조화된 기억의 궁전 역할을 합니다:

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

MEMORY.md 파일은 여러 세션에 걸쳐 오류, 결정, 패턴을 기록합니다. 현재 54건의 실패 사례와 교차 도메인 학습 패턴이 문서화되어 있습니다. bash에서 VAR이 0일 때 ((VAR++))가 set -e와 함께 실패한다는 것을 발견하면 기록합니다. 세 번의 세션 후, Python에서 유사한 정수 엣지 케이스를 만났을 때 MEMORY.md 항목이 해당 패턴을 떠올려 줍니다.⁵

교차 도메인 복합 효과: 훅 개발 중 발생한 bash 이스케이핑 오류가 Python 블로그 린터의 정규식 개선에 반영되었습니다. CSS 토큰 누락(--spacing-2xs가 존재하지 않음)이 모든 커스텀 프로퍼티 참조에 대한 체계적 감사를 촉발했습니다. 각 항목은 개별 세션 컨텍스트 내에서 분리되어 있었을 도메인들을 서로 연결합니다.

전략 3: 세션 핸드오프

여러 세션에 걸친 작업의 경우, 전체 상태를 캡처하는 핸드오프 문서를 작성합니다:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

~/.claude/handoffs/ 디렉토리에는 다중 세션 작업의 핸드오프 문서 49개가 보관되어 있습니다. claude -c(계속하기)로 새 세션을 시작하거나 핸드오프 문서를 읽으면, 후속 세션에 최소한의 토큰 비용으로 전체 컨텍스트를 제공합니다.⁶

핸드오프 패턴은 심의 시스템 구축 중 큰 도움이 되었습니다. PRD-4(재귀 가드 확장)는 PRD 1-3의 결정 사항에 대한 이해가 필요했습니다. 핸드오프 없이는 새 세션에서 수정된 모든 파일을 다시 읽어야 했을 것입니다. 핸드오프를 통해 세션이 아키텍처 컨텍스트를 갖춘 채 시작되어 곧바로 구현에 착수할 수 있었습니다.

전략 4: 서브에이전트 위임

서브에이전트는 독립적인 컨텍스트 윈도우에서 실행됩니다. 조사나 리뷰 작업을 서브에이전트에 위임하면 메인 세션의 컨텍스트를 구현 작업에 보존할 수 있습니다.⁷

저의 재귀 가드 시스템이 이를 자동으로 관리합니다:

# From recursion-guard.sh - spawn budget enforcement
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

각 서브에이전트는 원시 출력 대신 요약을 반환하여 메인 컨텍스트를 가볍게 유지합니다. 블로그 포스트 재작성 중에는 탐색 작업(CSS 데이터 수집, 훅 코드 읽기, 디렉토리 구조 조사)을 서브에이전트에 위임합니다. 메인 컨텍스트는 글쓰기에 집중하고, 서브에이전트가 조사를 담당합니다.

스폰 버짓은 어렵게 배운 교훈입니다. 제한 없이 진행한 초기 세션에서 재귀적 서브에이전트가 각각 더 많은 서브에이전트를 생성했습니다. 이제 재귀 가드 훅이 안전한 정수 검증과 설정 기반 버짓으로 깊이 제한을 시행합니다.⁸

경험에서 배운 안티패턴

10줄만 필요할 때 전체 파일을 읽는 것. Claude Code 사용 초기에는 함수 하나를 위해 2,000줄짜리 파일 전체를 읽었습니다. 줄 오프셋을 사용하세요: Read file.py offset=100 limit=20으로 읽기당 15,000+ 토큰을 절약할 수 있습니다.

장황한 오류 출력을 컨텍스트에 남겨두는 것. 스폰 버짓 문제를 디버깅한 후, 컨텍스트에 실패한 반복의 스택 트레이스가 40개 이상 남아 있었습니다. 버그 수정 후 /compact 한 번으로 이 불필요한 부담을 해소했습니다.

매 세션마다 모든 파일을 읽으며 시작하는 것. 초기 세션에서는 “컨텍스트 확보”를 위해 8~10개의 파일을 미리 로드했습니다. 이제는 Claude Code의 glob과 grep 도구가 필요에 따라 관련 파일을 찾도록 하여, 불필요한 사전 로딩으로 소비되는 100,000+ 토큰을 절약합니다.

핵심 요점

개인 개발자를 위한 조언: - Claude가 강제 압축을 트리거할 때가 아니라, 완료된 하위 작업마다 압축하세요. 25~30분 간격의 선제적 압축이 출력 품질을 유지합니다 - 세션이 진행되는 동안 핵심 결정을 파일시스템 메모리 파일에 기록하세요. 저의 MEMORY.md에는 수백 번의 세션에 걸쳐 유지되는 54개의 항목이 있습니다 - 메인 컨텍스트를 오염시킬 조사 작업에는 서브에이전트를 사용하세요. 5개 파일에 대한 조사 쿼리는 메인 컨텍스트에서 75,000+ 토큰이 들지만, 서브에이전트를 통하면 500 토큰 요약만으로 충분합니다

팀을 위한 조언: - 다중 세션 작업을 위한 핸드오프 문서 형식을 표준화하세요. 저의 49개 핸드오프는 모두 동일한 상태/파일/결정/차단/다음 구조를 따릅니다 - 모든 세션에 자동으로 로드되는 아키텍처 컨텍스트를 프로젝트 수준 CLAUDE.md 파일에 설정하세요. 이러한 토큰 관리 원칙에서 발전한 7계층 위계 구조는 컨텍스트가 곧 아키텍처다에서 자세히 다룹니다

자주 묻는 질문

LLM 컨텍스트 윈도우가 가득 차면 어떻게 됩니까?

컨텍스트 윈도우가 용량 한계(사용률 약 95%)에 가까워지면 Claude Code는 자동 압축을 실행합니다. 대화 기록을 요약해 빈 공간을 확보하는 과정입니다. 그러나 출력 품질은 압축이 실행되기 훨씬 전부터 저하됩니다. 제가 50번의 세션에 걸쳐 측정한 결과, 품질 저하는 컨텍스트 사용률 약 60% 지점에서 시작되었습니다. 모델이 앞서 받은 지시를 잊고, 이미 거부된 제안을 반복하며, 다중 파일 변경의 일관성을 잃기 시작합니다. 게다가 압축이 일어날 때마다 중요한 결정이 담겨 있었을지도 모를 컨텍스트가 버려지므로, 압축 횟수가 적을수록 세션은 더 일관성 있게 유지됩니다.

긴 세션에서 LLM 컨텍스트를 효과적으로 관리하려면 어떻게 해야 합니까?

다음 네 가지 전략이 수 시간에 걸친 긴 세션에서도 출력 품질을 유지해 줍니다. 하위 작업을 완료할 때마다(25~30분마다) 실행하는 선제적 압축은 눈에 띄지 않게 진행되는 품질 저하를 막아 줍니다. 파일시스템 기반 메모리(CLAUDE.md, MEMORY.md, 핸드오프 문서)는 핵심 상태를 컨텍스트 경계 너머까지 보존합니다. 서브에이전트 위임은 조사 작업을 독립된 컨텍스트 윈도우로 넘기고 원본 출력 대신 요약만 돌려받게 합니다. 그리고 줄 오프셋을 지정한 표적 파일 읽기(Read file.py offset=100 limit=20)는 파일 전체를 불러올 때와 비교해 한 번에 15,000 토큰 이상을 절약합니다. 3계층 압축 프레임워크는 컨텍스트가 곧 새로운 메모리다에서 자세히 다룹니다.

Claude Code의 컨텍스트 압축이란 무엇입니까?

컨텍스트 압축은 컨텍스트 윈도우가 용량 한계에 가까워질 때 대화 기록을 요약하는 Claude Code의 내장 메커니즘입니다. /compact 명령을 사용하면 직접 실행할 수 있으며, 자동 압축은 사용률 약 95% 지점에서 자동으로 작동합니다. 압축은 핵심 결정과 파일 내용, 작업 상태는 그대로 보존하면서 장황한 도구 출력만 걷어냅니다. 압축이 세 번 연속으로 실패하면 서킷 브레이커가 동작을 중단시켜 무한 재시도 루프를 방지합니다. 이 안전장치가 도입되기 전에는 1,279개 세션에서 50회 이상 연속 실패가 발생해 하루 약 25만 건의 API 호출이 낭비되었으며, 이 내용은 소스 코드 유출 분석에 기록되어 있습니다.

생산적인 AI 개발에는 토큰이 얼마나 필요합니까?

200K 토큰짜리 컨텍스트 윈도우도 제대로 관리하기만 하면 충분합니다. 압축을 적용한 저의 설정은 윈도우의 약 78%(156,000 토큰)를 추론용으로 남겨 두어, 압축 임계값에 도달하기 전까지 40~60번의 생산적인 턴을 확보합니다. 압축하지 않은 설정은 추론에 26%(53,000 토큰)만 남기며 15~20턴 만에 압축에 도달합니다. 윈도우의 실질적인 크기는 그 크기 자체보다 무엇으로 채워지는지에 더 크게 좌우됩니다. 잘 압축된 200K 윈도우는 압축되지 않은 도구 출력으로 가득 찬 가상의 500K 윈도우보다 나은 결과를 냅니다. 시스템 프롬프트 압축, CLI 우선 도구 아키텍처, 새로운 에이전트 스폰이 효과가 가장 큰 최적화입니다.

핸드오프 문서는 여러 세션에 걸친 AI 개발에 어떤 도움이 됩니까?

핸드오프 문서는 다음 세션에 넘겨줄 작업의 전체 상태를 그대로 기록해 둔 문서입니다. 현재 진행 상황, 변경한 파일, 내린 핵심 결정, 차단 요인, 다음 단계가 여기에 담깁니다. 새 세션을 핸드오프 문서를 읽는 것으로 시작하면, 에이전트가 변경된 파일을 모두 다시 읽을 필요 없이 최소한의 토큰 비용(보통 500 토큰 미만)으로 전체 아키텍처 컨텍스트를 확보합니다. 저의 핸드오프 문서 49건은 모두 Status/Files/Decision/Blocked/Next라는 일관된 구조를 따릅니다. 심의 시스템 구축 당시에도 핸드오프 덕분에 각 PRD 세션이 이전 PRD의 대화 기록을 끌고 오지 않고도 그때까지의 아키텍처 결정을 불러온 상태에서 시작할 수 있었습니다.

참고 문헌