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