1M 토큰 컨텍스트 윈도우 작동 방식, /compact 명령, .claudeignore 설정, CLAUDE.md 영구 컨텍스트 관리, 대규모 코드베이스 토큰 최적화 전략.
Claude Code 가이드 #18 — 대규모 코드베이스를 다루다 보면 "컨텍스트 한도 초과" 에러가 나거나, 이전에 설명한 내용을 Claude Code가 잊어버리는 경험을 합니다. 이 편에서는 Claude Code의 컨텍스트 윈도우 작동 방식, /compact 명령, .claudeignore, CLAUDE.md 활용법까지 토큰 최적화 전략 전체를 정리합니다.
† 이 글은 2026년 3월 기준, Claude Code 공식 Context 문서 기반으로 작성됐습니다.
Claude Code의 기반 모델(claude-sonnet 계열)은 최대 1M(100만) 토큰 컨텍스트 윈도우를 지원합니다. 컨텍스트 윈도우는 Claude Code가 한 번에 "기억"할 수 있는 텍스트의 양입니다.
컨텍스트 윈도우 안에 포함되는 것:
1M 토큰은 약 750만 단어 분량으로 매우 크지만, 대규모 코드베이스에서 많은 파일을 읽고 긴 대화를 반복하면 빠르게 소진될 수 있습니다.
| 콘텐츠 유형 | 대략적인 토큰 수 |
|---|---|
| 코드 100줄 | 약 500~800 토큰 |
| 1000줄 JS 파일 | 약 5,000~8,000 토큰 |
| 1시간 분량의 대화 | 약 50,000~150,000 토큰 |
| 중간 규모 코드베이스 전체 | 수백만 토큰 이상 |
/compact 명령을 사용하거나 새 세션을 시작하는 것이 좋습니다. 컨텍스트가 100%에 도달하면 새로운 요청을 처리할 수 없습니다./compact는 현재 세션의 대화 히스토리를 요약해 토큰 사용량을 줄이는 명령입니다. 세션을 완전히 초기화하지 않고 작업 맥락을 유지하면서 공간을 확보할 수 있습니다.
/compact 기본 사용# 현재 대화를 자동 요약 /compact # 요약 지침을 직접 지정 (특정 내용 보존) /compact 현재까지 논의된 API 설계 결정사항과 파일 구조를 반드시 보존해줘 # 사용량 확인 후 compact /tokens # 현재 토큰 사용량 확인 /compact
/compact 실행 후 Claude Code는 대화를 구조화된 요약으로 대체합니다. 요약에는 다음이 포함됩니다:
요약 후 새 질문을 하면 Claude Code는 요약된 컨텍스트를 기반으로 응답합니다. 세부 대화 내용은 사라지지만 핵심 맥락은 유지됩니다.
/compact 후 Claude Code가 이전에 읽은 파일 내용을 모른다고 함 — /compact는 대화를 요약할 뿐, 파일 내용 자체를 다시 로드하지 않습니다. 중요한 파일은 /compact 후 다시 명시적으로 읽도록 요청하거나, CLAUDE.md에 핵심 정보를 기록해 두세요..claudeignore는 .gitignore와 같은 문법을 사용하며, Claude Code가 읽지 않을 파일이나 디렉토리를 지정합니다. 대규모 코드베이스에서 토큰 낭비를 막는 가장 효과적인 방법입니다.
.claudeignore 예시 (프로젝트 루트에 위치)# 의존성 디렉토리 node_modules/ .venv/ venv/ __pycache__/ # 빌드 결과물 dist/ build/ .next/ out/ # 테스트 커버리지 및 캐시 coverage/ .cache/ .pytest_cache/ # 미디어 파일 *.png *.jpg *.jpeg *.gif *.mp4 *.pdf # 로그 파일 *.log logs/ # 대용량 데이터 파일 data/ *.csv *.json.gz # 민감 정보 .env .env.local secrets/
.claudeignore를 사용하면:
CLAUDE.md는 세션이 시작될 때 자동으로 컨텍스트에 포함되는 파일입니다. 매번 설명하지 않아도 되는 프로젝트 규칙, 구조, 컨벤션을 여기에 정리해두면 토큰을 아끼면서 일관성 있는 작업이 가능합니다.
CLAUDE.md에 포함하면 효과적인 내용:
CLAUDE.md 최소 유효 구조 예시# 프로젝트명 ## 기본 명령어 - 빌드: `npm run build` - 테스트: `npm test` - 구문 검사: `node --check {파일}` ## 디렉토리 구조 - `posts/` — 포스트 본문 (posts/{id}.js 형식) - `data/posts.js` — 포스트 메타데이터 - `components/` — React 컴포넌트 ## 중요 규칙 - JS 파일 수정 후 반드시 `node --check` 실행 - data/posts.js의 id는 반드시 숫자형 - 광고(ad 타입)는 포스트당 최대 4개 ## 금지 사항 - `node_modules/` 직접 수정 금지 - `public/` 하위 파일 삭제 금지
수십만 줄 이상의 코드베이스에서 Claude Code를 효율적으로 쓰는 전략입니다.
"이 프로젝트 전체를 분석해줘" 대신 작업 범위를 좁게 지정합니다.
작업 범위를 좁히는 프롬프트 패턴# 비효율적 (전체 코드베이스 로드) 이 프로젝트의 성능 문제를 찾아줘 # 효율적 (범위 명시) pages/index.js와 components/PostCard.js만 읽고, 이 두 파일의 렌더링 성능 문제를 찾아줘 # 더 효율적 (파일 + 함수 단위) components/PostCard.js의 FeaturedCard 컴포넌트만 읽고 불필요한 리렌더링이 있는지 확인해줘
컨텍스트가 긴 작업을 서브에이전트로 분산하면 각 에이전트가 독립적인 컨텍스트 윈도우를 씁니다.
서브에이전트로 병렬 분석# 큰 코드베이스를 여러 영역으로 나눠서 서브에이전트에게 분배 # 각 서브에이전트는 독립적인 컨텍스트 윈도우 사용 서브에이전트 A: pages/ 디렉토리만 분석해서 성능 문제 목록 만들어줘 서브에이전트 B: components/ 디렉토리만 분석해서 성능 문제 목록 만들어줘 서브에이전트 C: data/ 디렉토리만 분석해서 성능 문제 목록 만들어줘 # 각 에이전트 결과를 취합해 전체 보고서 생성
세션을 시작할 때 Claude Code에게 읽힐 파일 순서가 중요합니다. 자주 참조하는 파일을 나중에 읽으면 더 오래 컨텍스트에 남습니다.
/tokens로 사용량을 확인하고, /compact로 히스토리를 요약하거나 필요한 파일을 다시 읽도록 요청하세요.Claude Code는 API 기반으로 동작하므로 토큰 사용량이 곧 비용입니다. 비용을 줄이는 실전 전략입니다.
토큰 사용량 확인 명령어# 현재 세션의 토큰 사용량 확인 /tokens # 출력 예시: # Context usage: 245,382 / 1,000,000 tokens (24.5%) # Input tokens this session: 189,023 # Output tokens this session: 56,359 # Estimated cost: $0.84
비용 절감 전략:
모델 전환으로 비용 절감# settings.json에서 작업별 모델 설정 { "model": "claude-haiku-4-5" } # 또는 실행 시 플래그로 지정 claude --model claude-haiku-4-5 # 모델별 특성: # claude-sonnet-4-5: 복잡한 분석, 아키텍처 설계 (기본) # claude-haiku-4-5: 단순 편집, 검증, 반복 작업 (저렴)
/compact를 자주 써도 비용이 줄지 않음 — /compact는 앞으로의 토큰 소비를 줄이지만, 현재 세션에서 이미 사용한 토큰 비용은 변경되지 않습니다. 비용 절감 효과는 compact 이후 이어지는 작업에서 나타납니다.컨텍스트 및 토큰 관련 자주 발생하는 문제와 해결법입니다.
/compact로 해결되지 않으면 새 세션을 시작해야 합니다. 새 세션 시작 전에 현재 작업 상태를 CLAUDE.md에 기록해 다음 세션에서 이어받을 수 있도록 하세요./compact로 히스토리를 정리한 뒤 다시 읽도록 요청하세요.정리하면:
/compact로 히스토리를 요약해 컨텍스트 공간 확보.claudeignore로 불필요한 파일이 컨텍스트에 포함되지 않도록 제외관련 가이드: