context-budget

name	context-budget
description	Claude Code 세션에서 에이전트, 스킬, MCP 서버, 규칙이 소비하는 컨텍스트 창을 감사합니다. 비대화, 중복 요소를 식별하고 우선순위가 있는 토큰 절감 권고를 생성합니다.
origin	ECC

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를 추가한 뒤에는 다시 감사합니다