클로드코드 06-context-window

1. 컨텍스트 윈도우

참고: Claude Code 세션에서 컨텍스트 윈도우가 어떻게 채워지는지, 무엇이 자동으로 로드되는지, 각 파일 읽기가 얼마나 비용이 드는지 이해하기

1.1. 컨텍스트 윈도우란?

컨텍스트 윈도우는 세션의 작업 메모리다. 다음 내용을 담는다.

- 시스템 프롬프트
- 대화 기록 (사용자 메시지, Claude의 응답)
- 파일 내용 (Claude가 읽은 파일들)
- 명령어 출력 (테스트 결과, git 상태 등)
- CLAUDE.md 및 auto memory
- 로드된 skills와 MCP 도구 정의
- hooks 결과

1.2. 세션 시작 시 자동 로드

claude를 실행하면 아무것도 입력하기 전에 다음 내용이 컨텍스트에 로드된다.

- 내용: 설명: 토큰 (예시)
- System prompt: 행동, 도구 사용, 응답 형식에 대한 핵심 지시사항: ~4,200
- Auto memory: 이전 세션의 학습 내역 (MEMORY.md 처음 200줄 또는 25KB): ~680
- Environment info: 작업 디렉토리, 플랫폼, 셸, OS 버전, git 상태: ~280
- MCP tools (deferred): 사용 가능한 MCP 도구 이름 목록. 전체 스키마는 필요할 때 로드: ~120
- Skill descriptions: 사용 가능한 skill들의 한 줄 설명. 실제 내용은 사용 시 로드: ~450
- User CLAUDE.md: ~/.claude/CLAUDE.md - 개인 전역 설정: ~320
- Project CLAUDE.md: 프로젝트 지시사항 (가장 중요한 파일): ~1,800

참고: 총 예시 토큰: 약 7,500 tokens. 실제 값은 CLAUDE.md 크기, MCP 서버 수, 파일 길이에 따라 다르다.

1.3. 대화 중 컨텍스트 추가

사용자가 프롬프트를 입력하고 Claude가 작업하면 다음 내용이 추가된다.

1.3.1. 파일 읽기

Read src/api/auth.ts

터미널에는 "Read auth.ts" 한 줄만 표시되지만, 파일 전체 내용(예: 2,400 토큰)이 Claude의 컨텍스트에 들어간다. 파일 읽기가 컨텍스트 사용의 대부분을 차지한다.

참고: 팁: 프롬프트를 구체적으로 작성하면 Claude가 더 적은 파일을 읽는다. 연구가 많이 필요한 작업은 subagent에 위임하라.

1.3.2. Path-scoped rules

.claude/rules/에 있는 규칙 중 paths 패턴이 매칭되면 자동으로 로드된다.

---
paths:
  - "src/api/**/*.ts"
---

Claude가 src/api/ 아래 파일을 읽을 때 이 규칙이 자동으로 로드된다.

1.3.3. Hooks

PostToolUse hook은 파일 편집 후 실행된다. hookSpecificOutput.additionalContext에 JSON으로 출력하면 해당 정보가 Claude의 컨텍스트에 들어간다.

1.3.4. Subagents

Subagent는 별도의 컨텍스트 윈도우에서 작업한다. 수천 토큰의 파일을 읽어도 주 세션에는 영향을 주지 않는다. 최종 요약만 주 세션으로 돌아온다.

- 구성 요소: 주 세션 토큰: Subagent 토큰
- System prompt: ~4,200: ~900
- Project CLAUDE.md: ~1,800: ~1,800
- MCP tools + skills: ~570: ~970
- 파일 읽기: -: ~6,100
- Subagent 결과: ~420: -

참고: Subagent가 6,100 토큰의 파일을 읽었지만, 주 세션은 420 토큰의 요약만 받는다. 이것이 컨텍스트 절약의 핵심이다.

1.3.5. /compact 실행

컨텍스트가 가득 차면 /compact를 실행해 대화를 요약할 수 있다.

- Summarize from here: 선택한 메시지 이후의 모든 내용을 요약으로 대체한다.
- Summarize up to here: 선택한 메시지 이전의 모든 내용을 요약으로 대체한다.

/compact 후 남는 것:

- System prompt, CLAUDE.md, auto memory, MCP tools (자동 재로드)
- Skill descriptions는 재로드되지 않는다. 실제로 사용한 skill만 보존된다.
- 요약된 대화 내용

1.4. 컨텍스트 관리 전략

CLAUDE.md는 200줄 이하로 유지: 긴 파일은 컨텍스트를 많이 소모하고 준수도를 떨어뜨린다.
Path-scoped rules 사용: 모든 파일이 아닌 특정 경로에서만 필요한 규칙은 paths를 사용해 지연 로드한다.
Subagent로 연구 위임: 대규모 코드 탐색은 subagent에게 맡겨 주 컨텍스트를 보존한다.
disable-model-invocation: true skill: 부작용이 있는 skill(커밋, 배포 등)은 이 설정으로 세션 시작 시 컨텍스트에 들어가지 않게 한다.
/context로 점검: 현재 어떤 내용이 공간을 차지하고 있는지 확인한다.