컨텍스트 윈도우 관리: 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 파일에 설정하세요

참고 문헌