본문으로 건너뛰기

컨텍스트 예산 감사: /skill-doctor, 출력 상한, 그리고 컨텍스트 창을 채우는 여섯 개의 숫자

중급

Claude Code 프로젝트는 노트북에 브라우저 탭이 쌓이듯 컨텍스트 부채를 쌓습니다. 설치한 스킬 하나하나가 Claude가 매 턴 다시 읽는 목록에 한 줄을 더합니다. 서브에이전트 하나하나가 설명(description)을 더합니다. 3월에 써 둔 CLAUDE.md 단락은 그 작업에 필요하든 아니든 9월에도 로드됩니다. 그리고 npm test 한 번은 최대 30,000자를 대화에 쏟아붓습니다. 세션이 지시를 잊어버리기 시작하거나 청구서가 한 일과 맞지 않게 될 때까지, 이 중 어느 것도 눈에 보이지 않습니다.

컨텍스트 관리는 그 순간에 쓰는 두 명령, /clear와 /compact를 다룹니다. 이 페이지는 프로젝트당 한 번 돌리는 감사입니다. 당신이 아무것도 입력하기 전에, 또는 턴 사이에 Claude Code가 컨텍스트를 쓰는 여섯 군데, 각각을 지배하는 설정, 그리고 그 기본값을 다룹니다. 여기 있는 모든 내용은 2026년 9월 기준 공식 문서에 있으며, 대부분의 노브는 그에 관한 통설보다 더 최신입니다.

What you'll learn
  • 자르기 전에 측정하기: /context, /usage의 사용량 귀속, /doctor의 목록 비용 추정치를 읽어 가장 큰 항목부터 손보기
  • /skill-doctor(v2.1.252+)와 네 가지 skillOverrides 상태로 스킬 목록을 솎아내고, 목록에 걸린 창의 1% 예산을 이해하기
  • 셸 명령이나 백그라운드 작업이 인라인으로 반환하는 양(기본 30,000자와 32,000자)을 bashOutputMaxChars와 taskOutputMaxChars로 제한하기
  • omitClaudeMd(v2.1.271+)로 모든 서브에이전트마다 CLAUDE.md 값을 치르는 것을 멈추고, 서브에이전트 설명을 15,000토큰 경고선 아래로 유지하기
  • 자동 압축 창을 의도적으로 설정하고(/autocompact, autoCompactWindow), 압축 후 어떤 호출된 스킬이 살아남는지 결정하는 25,000토큰 예산을 이해하기
  • 컨텍스트가 아니라 사고(thinking) 토큰이 실제 청구서일 때 maxEffortLevel로 전사적으로 노력 수준을 제한하기

입력하기 전에 이미 창 안에 있는 것​

이 다이어그램을 실행 가능하게 만드는 사실은 두 가지입니다. 왼쪽 상자에 있는 모든 것은 매 요청마다 비용이 발생합니다. Claude Code가 매 턴 전체 대화를 전송하고, 캐시 읽기 할인만이 그 충격을 완화하기 때문입니다. 그리고 오른쪽 상자는 장황한 명령 하나가 한 걸음에 왼쪽 상자 전체보다 더 많은 것을 더할 수 있는 곳입니다. 아래 감사는 왼쪽에서 오른쪽으로 진행합니다.

감사​

Guided walkthrough1 of 9
  1. /context를 실행하면 범주별 실시간 분석과 최적화 제안이 나오며, 어떤 CLAUDE.md와 자동 메모리 파일이 로드되었는지도 포함됩니다. Pro, Max, Team, Enterprise 플랜에서는 /usage가 최근 사용량을 스킬, 서브에이전트, 플러그인, 개별 MCP 서버에 백분율로 귀속시키고, 10% 이상을 차지하는 행동(긴 컨텍스트, 캐시 미스)을 표시합니다. /doctor는 스킬 목록의 컨텍스트 비용과 가장 큰 기여자들을 추정합니다. 아무것도 바꾸기 전에 가장 큰 항목 세 개를 적어 두세요.

그대로 붙여 쓸 수 있는 설정 블록​

프로젝트 로컬 컨텍스트 상한 (.claude/settings.local.json)

{
"bashOutputMaxChars": 12000,
"taskOutputMaxChars": 12000,
"skillOverrides": {
  "legacy-migration-notes": "name-only",
  "deploy-prod": "user-invocable-only",
  "old-design-system": "off"
},
"autoCompactWindow": 500000,
"maxEffortLevel": "high"
}

이것을 기본값이 아니라 결정으로 읽고 위에서 아래로 내려가세요. 두 개의 출력 상한은 수다스러운 테스트 러너를 가정합니다. Claude가 실행할 때마다 저장된 출력 파일을 열기 시작하면 30,000 / 32,000 기본값 쪽으로 되돌리세요. 세 개의 오버라이드는 설명 값을 치르지 않으면서 스킬을 계속 닿을 수 있게 유지합니다. 압축 창은 모델이 조정한 지점보다 절반 지점에서 압축하고 싶은 1M 컨텍스트 모델을 위한 명시적 선택입니다. 노력 상한은 여기서 출력 품질을 바꾸는 유일한 한 줄이므로, 마지막에, 그리고 /usage가 사고 토큰이 지배한다고 보여준 뒤에만 설정하세요.

CLAUDE.md를 로드하지 않는 서브에이전트 (.claude/agents/repo-auditor.md)

---
name: repo-auditor
description: Audits a repository for dead code and unused exports. Use for read-only sweeps.
tools: Read, Grep, Glob, Bash
model: sonnet
omitClaudeMd: true
---
You are a read-only auditor. Everything you need is in the delegation prompt.
Report findings as a table of path, symbol, and evidence. Do not edit files.

헤드리스 세션에서 스킬 보고서 실행하기

claude -p "/skill-doctor"

흔한 실수​

Watch out
  • 스킬을 접어두는 대신 삭제하기. name-only는 거의 0에 가까운 목록 비용으로 스킬을 계속 호출 가능하게 유지합니다. off는 / 메뉴에서도 없애버립니다. 대부분의 '미사용' 스킬은 사라지는 게 아니라 name-only가 되어야 합니다.
  • 빌드 로그 하나가 넘쳤다고 bashOutputMaxChars를 128,000 상한까지 올리기. 그러면 앞으로의 모든 명령이 인라인에서 최대 4배 더 비싸집니다. 대신 PreToolUse 훅으로 로그를 필터링하세요(FAIL을 grep, head -100). 비용 문서에 정확한 훅 예시가 있습니다.
  • autoCompactWindow를 모델 컨텍스트보다 크게 설정하기. Claude Code가 조용히 창 크기로 제한하므로, 설정은 적용된 것처럼 보이지만 아무 일도 하지 않습니다.
  • 컨텍스트가 분리되어 있으니 서브에이전트가 싸다고 가정하기. Explore, Plan이거나 omitClaudeMd를 설정하지 않았다면 그 시작 단계에는 여전히 모든 CLAUDE.md 단계와 git 스냅샷이 포함됩니다.
  • 휴대폰에서 Remote Control로 /skill-doctor를 읽기. 'Skill usage reports are not available on this connection.'을 반환합니다. 세션이 살아 있는 터미널에서 실행하세요.
  • 호출된 스킬이 /compact를 살아남을 거라 기대하기. 25,000토큰 재부착 예산에 각 5,000토큰씩, 가장 최근 호출만 들어갑니다. 여전히 필요한 것은 다시 호출하세요.

빠른 점검​

Check yourself

0/6
  1. /skill-doctor는 무엇을 보고하고, 무엇을 의도적으로 빼놓나요?
  2. 스킬 목록이 예산을 초과했습니다. 무슨 일이 일어나나요?
  3. 성공한 npm test가 80,000자를 출력합니다. 기본 설정에서 Claude는 무엇을 받나요?
  4. 어떤 서브에이전트가 아무 설정 없이도 당신의 CLAUDE.md 파일을 건너뛰나요?
  5. 긴 세션에서 스킬 여섯 개를 호출했고 /compact가 막 실행됐습니다. 무엇이 살아남나요?
  6. maxEffortLevel이 관리 설정에서 'medium', 사용자 설정에서 'high'로 되어 있습니다. 무엇이 적용되나요?
Enter 또는 스페이스 키를 눌러 카드를 뒤집습니다. 좌우 화살표 키로 카드를 이동할 수 있습니다.용어가 표시되었습니다.
1 / 10
Key takeaways
  • 먼저 측정하세요: 실시간 분석은 /context, 스킬·서브에이전트·플러그인·MCP 서버별 귀속은 /usage, 목록 비용 추정은 /doctor.
  • 스킬 목록은 창의 1%로 제한된 턴별 세금입니다. /skill-doctor가 무엇을 접을지 알려주고, name-only는 거의 0에 가까운 비용으로 스킬을 계속 쓸 수 있게 합니다.
  • 도구 출력은 창을 날려버리는 가장 빠른 방법입니다: 성공한 명령당 인라인 약 30,000자, 백그라운드 작업당 32,000자. bashOutputMaxChars / taskOutputMaxChars로 제한하거나 훅으로 필터링하세요.
  • 서브에이전트는 시작 단계에서 무료가 아닙니다: Explore, Plan이거나 omitClaudeMd가 아니라면 모든 CLAUDE.md 단계에 git status까지 붙습니다. 커스텀 설명은 합계 15,000토큰 아래로 유지하세요.
  • 압축은 가장 최근에 호출된 스킬만 유지합니다(각 5,000, 합계 25,000). autoCompactWindow를 의도적으로 설정하고, 살아남아야 하는 것은 다시 호출하세요.
  • 사고 토큰이 청구서를 지배할 때 maxEffortLevel이 전사적으로 노력 수준을 제한합니다. 가장 낮은 스코프가 이기고 모든 공급자에서 유지됩니다.

출처 및 더 읽을거리​

다음​

  • 컨텍스트 관리 — 감사가 끝난 뒤, 그 순간의 /clear 대 /compact
  • 스킬 — 목록의 한 줄을 값어치 있게 만드는 스킬 쓰기
  • 서브에이전트 — omitClaudeMd가 안전하도록 위임 프롬프트를 설계하기