Strategic Compact Skill (전략적 컴팩트 스킬)
워크플로의 전략적 지점에서 수동 /compact를 제안하여 임의의 자동 컴팩트에 의존하지 않도록 합니다.
활성화 시점
- 컨텍스트 한도(200K+ 토큰)에 가까워지는 긴 세션 실행 중
- 다단계 작업(연구 → 계획 → 구현 → 테스트) 중
- 동일 세션 내에서 관련 없는 작업 간 전환 시
- 주요 마일스톤 완료 후 새 작업 시작 시
- 응답 속도가 느려지거나 일관성이 떨어질 때(컨텍스트 압력)
전략적 컴팩트가 필요한 이유?
자동 컴팩트는 임의의 시점에 트리거됩니다:
- 작업 중간에 자주 발생하여 중요한 컨텍스트를 잃음
- 논리적인 작업 경계를 인식하지 못함
- 복잡한 다단계 작업을 방해할 수 있음
논리적 경계에서의 전략적 컴팩트:
- 탐색 후, 실행 전 — 연구 컨텍스트를 컴팩트하고 구현 계획 유지
- 마일스톤 완료 후 — 다음 단계를 위한 새 출발
- 주요 컨텍스트 전환 전 — 다른 작업 전 탐색 컨텍스트 정리
작동 방식
suggest-compact.js 스크립트는 PreToolUse(Edit/Write)에서 실행되며 두 가지 신호를 결합합니다:
- 컨텍스트 크기(기본) — 세션 기록(
훅 페이로드의transcript_path)에서 최신usage레코드를 읽고input_tokens + cache_read_input_tokens + cache_creation_input_tokens(턴의 실제 컨텍스트 크기)를 합산합니다. 창 크기에 따라 조정된 임계값(200K 창에서 160K 토큰, 1M 창에서 250K 토큰 —[1m]모델 마커에서 감지되거나 관찰된 토큰이 이미 200K를 초과할 때 추론)에서/compact`를 제안하고, 컨텍스트가 60K 토큰 추가 성장할 때마다 다시 알림 - 도구 호출 횟수(보조) — 세션의 도구 호출을 계산하고 구성 가능한 임계값(기본값: 50회)에서 제안한 후 25회마다 제안
도구 호출 횟수만으로는 창 압력의 약한 대리 지표입니다: 몇 번의 대용량 파일 읽기나 MCP 응답이 매우 적은 호출로 창을 가득 채울 수 있는 반면, 많은 소규모 호출이 거의 빈 창에서 50회를 넘길 수 있습니다. 컨텍스트 크기 신호는 실제로 중요할 때 작동합니다.
훅 설정
플러그인으로 설치됨? 설정이 필요 없습니다. 플러그인의 hooks/hooks.json이 이미 suggest-compact.js를 등록합니다(훅 ID pre:edit-write:suggest-compact, standard 및 strict 훅 프로필에서 활성화). 아래 블록을 ~/.claude/settings.json에 복사하지 마세요 — 플러그인 설치 시 ~/.claude/scripts/는 존재하지 않으며, 플러그인 훅을 중복하면 이중 실행이 발생합니다.
수동으로 설치한 경우 (./install.sh), ~/.claude/settings.json에 다음을 추가하세요:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
},
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
}
]
}
}
구성
환경 변수:
COMPACT_THRESHOLD— 첫 번째 제안 전 도구 호출 횟수(기본값: 50)COMPACT_CONTEXT_THRESHOLD— 컨텍스트 크기 제안 전 컨텍스트 토큰(200K 창에서 기본값: 160000, 1M 창에서 250000;0은 컨텍스트 신호 비활성화)COMPACT_CONTEXT_INTERVAL— 제안이 반복되기 전 추가 컨텍스트 토큰(기본값: 60000)COMPACT_STATE_TTL_DAYS— 임시 디렉토리의 세션별 상태 파일이 정리되기 전 일수(기본값: 14)ECC_CONTEXT_WINDOW_TOKENS— 명시적 컨텍스트 창 크기(토큰), 자동 감지 재정의. 보고된 ID에[1m]마커가 없는 대형 창 모델(예: 400K Opus 4.x 또는 새로운 1M 창 모델 제품군)에 대해 이 값을 설정하여 임계값이 실제 창에 맞게 조정되고 기본값 200K로 인해 컨텍스트 사용량을 과장하지 않도록 합니다.CLAUDE_CODE_AUTO_COMPACT_WINDOW— Claude Code의 기본 창 크기 재정의(토큰).ECC_CONTEXT_WINDOW_TOKENS가 설정되지 않은 경우 대체값으로 사용됩니다.
컨텍스트 창은 그렇지 않으면
[1m]모델 마커에서 자동 감지되거나 관찰된 토큰이 이미 200K를 초과할 때 추론됩니다. 두 신호를 모두 제공하지 않는 대형 창 모델에서는 위 재정의 중 하나를 설정하여/compact제안이 올바른 지점에서 작동하도록 하세요.
컴팩트 결정 가이드
다음 표를 사용하여 컴팩트 시점을 결정하세요:
| 단계 전환 | 컴팩트? | 이유 |
|---|---|---|
| 연구 → 계획 | 예 | 연구 컨텍스트는 부피가 큼; 계획은 추출된 결과물 |
| 계획 → 구현 | 예 | 계획은 파일로 기록됨(또는 작업 목록); 코드를 위한 컨텍스트 확보 |
| 구현 → 테스트 | 때로 | 테스트가 최근 코드를 참조하면 유지; 초점 전환 시 컴팩트 |
| 디버깅 → 다음 기능 | 예 | 디버그 추적이 관련 없는 작업의 컨텍스트를 오염시킴 |
| 구현 중간 | 아니요 | 변수 이름, 파일 경로, 부분 상태 손실 비용 높음 |
| 실패한 접근 후 | 예 | 새 접근 시도 전 막다른 추론 제거 |
컴팩트 후 유지되는 것
무엇이 유지되는지 이해하면 자신 있게 컴팩트할 수 있습니다:
| 유지됨 | 손실됨 |
|---|---|
| CLAUDE.md 지침 | 중간 추론 및 분석 |
| 디스크의 파일 | 이전에 읽은 파일 내용 |
메모리 파일 (~/.claude/memory/) | 다단계 대화 컨텍스트 |
| Git 상태(커밋, 브랜치) | 도구 호출 기록 및 횟수 |
| 작업 목록 — todo 도구가 있는 경우에만(아래 참조) | 구두로 명시된 미묘한 사용자 선호도 |
작업 목록 유지에 의존하지 마세요 — 존재하지 않을 수 있습니다
Claude Code 2.1.233은 Opus 4.8, Sonnet 5, Fable 5, Mythos 5 및 최신 모델에서 todo/task 도구를 기본적으로 제거했습니다(
TodoWrite,TaskCreate/Get/Update/List).CLAUDE_CODE_ENABLE_TODO_TOOLS=1은 이를 다시 활성화하지만, 이는 시스템별 환경 설정입니다 — 이 스킬과 함께 전달되지 않으므로, 독자가 이를 가지고 있다고 가정할 수 없습니다.이는 "내 todo 목록이 컴팩트 후에도 유지된다"는 이유로 상태를 기록하는 대신 컴팩트하는 사람들이 있기 때문에 중요합니다. 도구가 없으면 유지할 목록이 없으며 계획은 단순히 사라집니다. 컴팩트하기 전에 계획을 파일에 기록하세요 — 파일은 모든 버전과 모든 모델에서 유지됩니다. 작업 목록을 누락될 수 있는 편의 기능으로 취급하고, 영구 기록으로 절대 취급하지 마세요.
모범 사례
- 계획 후 컴팩트 — 계획이 확정되고 파일에 기록된 후 새로 시작하기 위해 컴팩트
- 디버깅 후 컴팩트 — 계속 진행하기 전 오류 해결 컨텍스트 정리
- 구현 중간에 컴팩트하지 마세요 — 관련 변경 사항의 컨텍스트 유지
- 제안을 읽으세요 — 훅이 언제인지 알려주고, 여부는 사용자가 결정
- 컴팩트 전에 기록하세요 — 중요한 컨텍스트를 파일이나 메모리에 저장
- 요약과 함께
/compact사용 — 사용자 정의 메시지 추가:/compact 다음에 인증 미들웨어 구현에 집중
토큰 최적화 패턴
트리거 테이블 지연 로딩
세션 시작 시 전체 스킬 콘텐츠를 로드하는 대신, 키워드를 스킬 경로에 매핑하는 트리거 테이블을 사용하세요. 스킬은 트리거될 때만 로드되어 기본 컨텍스트를 50% 이상 줄입니다:
| 트리거 | 스킬 | 로드 시점 |
|---|---|---|
| "test", "tdd", "coverage" | tdd-workflow | 사용자가 테스트 언급 |
| "security", "auth", "xss" | security-review | 보안 관련 작업 |
| "deploy", "ci/cd" | deployment-patterns | 배포 컨텍스트 |
컨텍스트 구성 인식
컨텍스트 창을 소비하는 요소를 모니터링하세요:
- CLAUDE.md 파일 — 항상 로드되므로 간결하게 유지
- 로드된 스킬 — 각 스킬이 1-5K 토큰 추가
- 대화 기록 — 각 교환마다 증가
- 도구 결과 — 파일 읽기, 검색 결과가 부피 추가
중복 지침 감지
일반적인 중복 컨텍스트 소스:
~/.claude/rules/와 프로젝트.claude/rules/에 동일한 규칙- CLAUDE.md 지침을 반복하는 스킬
- 중복 도메인을 다루는 여러 스킬
컨텍스트 최적화 도구
token-optimizerMCP — 콘텐츠 중복 제거를 통한 자동 95%+ 토큰 감소context-mode— 컨텍스트 가상화(315KB에서 5.4KB로 감소 입증됨)
관련 정보
- The Longform Guide — 토큰 최적화 섹션
- 메모리 지속성 훅 — 컴팩트 후에도 유지되는 상태용
continuous-learning스킬 — 세션 종료 전 패턴 추출