컨텍스트 예산은(는) 무엇을 하나요?
Claude Code 세션에 로드된 모든 구성 요소의 토큰 오버헤드를 분석하고 컨텍스트 공간을 회수할 수 있는 실행 가능한 최적화 방안을 제시합니다.
사용 시기
- 세션 성능이 느려지거나 출력 품질이 저하될 때
- 최근에 많은 스킬, 에이전트 또는 MCP 서버를 추가했을 때
- 실제 컨텍스트 헤드룸이 얼마나 되는지 알고 싶을 때
- 추가 구성 요소를 계획 중이며 여유 공간이 있는지 확인해야 할 때
/context-budget명령어 실행 시 (이 스킬이 이를 지원합니다)
작동 방식
1단계: 인벤토리
모든 구성 요소 디렉터리를 스캔하고 토큰 소비량을 추정합니다:
에이전트 (agents/*.md)
- 파일당 줄 수 및 토큰 수 계산 (단어 수 × 1.3)
description프론트매터 길이 추출- 플래그: 파일 >200줄 (무거움), 설명 >30단어 (비대한 프론트매터)
스킬 (skills/*/SKILL.md)
- SKILL.md당 토큰 수 계산
- 플래그: 파일 >400줄
.agents/skills/에 중복 복사본이 있는지 확인 — 동일 복사본은 이중 계산을 위해 건너뜀
규칙 (rules/**/*.md)
- 파일당 토큰 수 계산
- 플래그: 파일 >100줄
- 같은 언어 모듈 내 규칙 파일 간 콘텐츠 중복 감지
MCP 서버 (.mcp.json 또는 활성 MCP 설정)
- 설정된 서버 수 및 총 도구 수 계산
- 도구당 약 500토큰의 스키마 오버헤드 추정
- 플래그: 도구가 20개를 초과하는 서버, 단순 CLI 명령어(
gh,git,npm,supabase,vercel)를 래핑하는 서버
CLAUDE.md (프로젝트 + 사용자 수준)
- CLAUDE.md 체인의 파일당 토큰 수 계산
- 플래그: 합계 >300줄
2단계: 분류
모든 구성 요소를 다음 버킷으로 정렬합니다:
| 버킷 | 기준 | 조치 |
|---|---|---|
| 항상 필요 | CLAUDE.md에서 참조되거나, 활성 명령어를 지원하거나, 현재 프로젝트 유형과 일치 | 유지 |
| 때때로 필요 | 도메인별(예: 언어 패턴), CLAUDE.md에서 참조되지 않음 | 온디맨드 활성화 고려 |
| 거의 필요 없음 | 명령어 참조 없음, 콘텐츠 중복, 또는 명백한 프로젝트 일치 없음 | 제거 또는 지연 로딩 |
3단계: 문제 감지
다음 문제 패턴을 식별합니다:
- 비대한 에이전트 설명 — 프론트매터의 설명이 30단어를 초과하면 모든 Task 도구 호출 시 로드됨
- 무거운 에이전트 — 파일 >200줄이면 스폰될 때마다 Task 도구 컨텍스트를 부풀림
- 중복 구성 요소 — 에이전트 로직을 복제하는 스킬, CLAUDE.md를 복제하는 규칙
- MCP 과다 구독 — 서버가 10개 이상이거나 무료로 사용 가능한 CLI 도구를 래핑하는 서버
- CLAUDE.md 비대화 — 장황한 설명, 오래된 섹션, 규칙이어야 할 지침
4단계: 보고서
컨텍스트 예산 보고서를 생성합니다:
컨텍스트 예산 보고서
═══════════════════════════════════════
총 예상 오버헤드: ~XX,XXX 토큰
컨텍스트 모델: Claude Sonnet (200K 창)
유효 가용 컨텍스트: ~XXX,XXX 토큰 (XX%)
구성 요소 분석:
┌─────────────────┬────────┬───────────┐
│ 구성 요소 │ 개수 │ 토큰 │
├─────────────────┼────────┼───────────┤
│ 에이전트 │ N │ ~X,XXX │
│ 스킬 │ N │ ~X,XXX │
│ 규칙 │ N │ ~X,XXX │
│ MCP 도구 │ N │ ~XX,XXX │
│ CLAUDE.md │ N │ ~X,XXX │
└─────────────────┴────────┴───────────┘
경고: 발견된 문제 (N개):
[토큰 절감량 순으로 정렬]
상위 3개 최적화:
1. [조치] → ~X,XXX 토큰 절감
2. [조치] → ~X,XXX 토큰 절감
3. [조치] → ~X,XXX 토큰 절감
잠재적 절감량: ~XX,XXX 토큰 (현재 오버헤드의 XX%)
상세 모드에서는 추가로 파일별 토큰 수, 가장 무거운 파일의 줄별 분석, 중복 구성 요소 간의 특정 중복 라인, MCP 도구 목록(도구별 스키마 크기 추정 포함)을 출력합니다.
예시
기본 감사
사용자: /context-budget
스킬: 설정 스캔 → 16개 에이전트 (12,400 토큰), 28개 스킬 (6,200), 87개 MCP 도구 (43,500), 2개 CLAUDE.md (1,200)
플래그: 3개의 무거운 에이전트, 14개의 MCP 서버 (3개는 CLI로 대체 가능)
최대 절감: 3개의 MCP 서버 제거 → -27,500 토큰 (오버헤드 47% 감소)
상세 모드
사용자: /context-budget --verbose
스킬: 전체 보고서 + planner.md (213줄, 1,840 토큰) 파일별 분석,
MCP 도구 목록(도구별 크기 포함), 중복 규칙 라인 나란히 비교
추가 전 확인
사용자: MCP 서버 5개를 더 추가하고 싶은데 여유가 있나요?
스킬: 현재 오버헤드 33% → 서버 5개 (~50개 도구) 추가 시 약 25,000 토큰 추가 → 오버헤드 45%로 증가
권장 사항: 40% 미만으로 유지하려면 먼저 CLI로 대체 가능한 서버 2개 제거
모범 사례
- 토큰 추정: 일반 텍스트는
단어 수 × 1.3, 코드가 많은 파일은문자 수 / 4사용 - MCP가 가장 큰 레버입니다: 각 도구 스키마는 약 500토큰이 소요되며, 30개 도구 서버는 모든 스킬을 합친 것보다 더 많은 비용이 듭니다
- 에이전트 설명은 항상 로드됩니다: 에이전트가 호출되지 않더라도 설명 필드는 모든 Task 도구 컨텍스트에 존재합니다
- 디버깅에는 상세 모드 사용: 정기 감사가 아닌 오버헤드를 유발하는 정확한 파일을 찾아야 할 때 사용
- 변경 후 감사 실행: 에이전트, 스킬 또는 MCP 서버를 추가한 후 실행하여 초기 증가를 감지