context-budget

Context Budget

Claude Code 세션에 로드된 모든 구성요소의 토큰 오버헤드를 분석하고, 컨텍스트 공간을 회수할 수 있는 실행 가능한 최적화를 드러냅니다.

사용 시점

• 세션 성능이 느려지거나 출력 품질이 저하될 때
• 최근에 많은 스킬, 에이전트, MCP 서버를 추가했을 때
• 실제로 남아 있는 컨텍스트 여유가 얼마나 되는지 알고 싶을 때
• 더 많은 구성요소를 추가하기 전에 공간이 있는지 확인해야 할 때
• /context-budget 명령을 실행할 때

동작 방식

1단계: 인벤토리

모든 구성요소 디렉터리를 스캔하고 토큰 소비를 추정합니다.

Agents (agents/*.md)

• 파일별 줄 수와 토큰 수 계산
• description frontmatter 길이 추출
• 200줄 초과 파일, 30단어 초과 description 표시

Skills (skills/*/SKILL.md)

• SKILL.md별 토큰 수 계산
• 400줄 초과 파일 표시
• .agents/skills/ 중 동일 복제본은 중복 계산 방지

Rules (rules/**/*.md)

• 파일별 토큰 수 계산
• 100줄 초과 파일 표시
• 같은 언어 모듈 내 규칙 파일 간 내용 중복 탐지

MCP Servers (.mcp.json 또는 활성 MCP 설정)

• 설정된 서버 수와 전체 도구 수 계산
• 도구당 스키마 오버헤드 약 500토큰 추정
• 20개 초과 도구를 가진 서버, 단순 CLI를 감싸는 서버 표시

CLAUDE.md

• 체인의 각 CLAUDE.md 파일 토큰 수 계산
• 합계 300줄 초과 시 표시

2단계: 분류

모든 구성요소를 다음 버킷으로 정렬합니다.

Bucket	Criteria	Action
Always needed	CLAUDE.md에 참조되거나 현재 프로젝트 유형과 직접 일치	Keep
Sometimes needed	도메인 특화이지만 항상 필요하진 않음	필요 시 활성화 검토
Rarely needed	명령 참조 없음, 내용 중복, 프로젝트와 명확한 관련 없음	제거 또는 lazy-load

3단계: 문제 탐지

다음 패턴을 식별합니다.

• 비대한 agent description
• 무거운 agent
• 중복 구성요소
• MCP 과구독
• CLAUDE.md 비대화

4단계: 리포트

다음 형태의 context budget 리포트를 생성합니다.

Context Budget Report
═══════════════════════════════════════

Total estimated overhead: ~XX,XXX tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~XXX,XXX tokens (XX%)

Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component       │ Count  │ Tokens    │
├─────────────────┼────────┼───────────┤
│ Agents          │ N      │ ~X,XXX    │
│ Skills          │ N      │ ~X,XXX    │
│ Rules           │ N      │ ~X,XXX    │
│ MCP tools       │ N      │ ~XX,XXX   │
│ CLAUDE.md       │ N      │ ~X,XXX    │
└─────────────────┴────────┴───────────┘

verbose 모드에서는 파일별 토큰 수, 무거운 파일 세부 분석, 중복 라인, MCP 도구별 추정치까지 출력합니다.

예시

기본 감사

User: /context-budget
Skill: 설정 스캔 → 16 agents, 28 skills, 87 MCP tools, 2 CLAUDE.md
       Flags: 3 heavy agents, 14 MCP servers
       Top saving: remove 3 MCP servers

확장 전 체크

User: I want to add 5 more MCP servers, do I have room?
Skill: 현재 오버헤드와 추가 예상 토큰을 계산해 한계 초과 여부와 선제 제거 대상을 권고

모범 사례

• prose는 words × 1.3, 코드 위주는 chars / 4 추정
• 가장 큰 레버는 MCP입니다
• agent description은 항상 로드된다고 가정합니다
• verbose 모드는 정밀 진단용으로만 사용합니다
• agent, skill, MCP를 추가한 뒤에는 다시 감사합니다