컨텍스트 버짓
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단계: 문제 탐지
다음 문제 패턴을 식별합니다:
- 팽창된 에이전트 설명 — 프론트매터의 description이 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%로 증가
권장: 먼저 CLI로 대체 가능한 서버 2개를 제거하여 40% 미만 유지
모범 사례
- 토큰 추정: 산문의 경우
단어 수 × 1.3, 코드가 많은 파일의 경우문자 수 / 4사용 - MCP가 가장 큰 레버입니다: 각 툴 스키마는 약 500토큰을 소비하며, 30개 툴 서버는 모든 스킬을 합친 것보다 비쌉니다
- 에이전트 설명은 항상 로드됩니다: 에이전트가 한 번도 호출되지 않더라도, description 필드는 모든 Task 툴 컨텍스트에 존재합니다
- 디버깅을 위한 상세 모드: 정기 감사가 아닌, 정확히 어떤 파일이 오버헤드를 유발하는지 파악해야 할 때 사용하세요
- 변경 후 감사: 에이전트, 스킬 또는 MCP 서버를 추가한 후에는 항상 실행하여 조기 파악하세요