전략적 컴팩트 스킬 (Strategic Compact Skill)
임의의 자동 컴팩트(auto-compaction)에 의존하지 않고, 워크플로의 전략적 지점에서 수동 /compact를 제안합니다.
활성화 시점
- 컨텍스트 한도(200K+ 토큰)에 가까워지는 긴 세션을 실행할 때
- 다단계 작업(연구 → 계획 → 구현 → 테스트)을 수행할 때
- 같은 세션 내에서 관련 없는 작업 간에 전환할 때
- 주요 마일스톤을 완료하고 새 작업을 시작할 때
- 응답 속도가 느려지거나 덜 일관성 있게 될 때(컨텍스트 압력)
전략적 컴팩트가 필요한 이유
자동 컴팩트는 임의의 시점에 트리거됩니다:
- 종종 작업 중간에 트리거되어 중요한 컨텍스트가 손실됨
- 논리적 작업 경계를 인식하지 못함
- 복잡한 다단계 작업을 방해할 수 있음
논리적 경계에서의 전략적 컴팩트:
- 탐색 후, 실행 전 — 연구 컨텍스트를 컴팩트하고 구현 계획은 유지
- 마일스톤 완료 후 — 다음 단계를 위한 새 출발
- 주요 컨텍스트 전환 전 — 다른 작업 전에 탐색 컨텍스트를 정리
작동 방식
suggest-compact.js 스크립트는 PreToolUse(편집/쓰기) 시점에 실행되며 두 가지 신호를 결합합니다:
- 컨텍스트 크기 (주 신호) — 세션 기록(
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를 설정하면 복구할 수 있지만, 이는 머신별 환경 설정입니다 — 이 스킬과 함께 이동하지 않으므로 사용자가 이 기능을 가지고 있다고 가정할 수 없습니다.이는 "내 할 일 목록이 컴팩트 후에도 유지된다"는 이유로 사용자가 상태를 파일에 기록하는 대신 컴팩트하기 때문입니다. 도구가 없으면 유지될 목록이 없으며 계획은 그냥 사라집니다. 컴팩트하기 전에 계획을 파일에 기록하십시오 — 파일은 모든 버전과 모든 모델에서 유지됩니다. 작업 목록은 없을 수도 있는 편의 기능으로 취급하고, 절대 영구 기록으로 의존하지 마십시오.
모범 사례
- 계획 후 컴팩트 — 계획이 확정되고 파일에 기록된 후 새로 시작하기 위해 컴팩트
- 디버깅 후 컴팩트 — 오류 해결 컨텍스트를 지우고 계속 진행
- 구현 중간에는 컴팩트하지 마십시오 — 관련 변경 사항을 위한 컨텍스트 유지
- 제안을 읽으십시오 — 훅은 언제를 알려주고, 사용자는 여부를 결정합니다.
- 컴팩트 전에 기록하십시오 — 중요한 컨텍스트를 파일이나 메모리에 저장한 후 컴팩트
- 요약과 함께
/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스킬 — 세션 종료 전 패턴 추출