compact-guide

name	compact-guide
description	컨텍스트 압축(compaction) 타이밍을 안내합니다. "컴팩트해줘", "컨텍스트 정리해줘", "compact-guide", "context가 꽉 찼어", "토큰이 부족해" 등에 트리거합니다. 언제 압축해야 하고 언제 하면 안 되는지 판단 기준과 압축 전 체크리스트를 제공합니다.

전략적 컴팩션 가이드

핵심 원칙: 컴팩션은 컨텍스트가 가득 차서 어쩔 수 없이 하는 게 아니라, 작업 단위가 완전히 끝났을 때 전략적으로 하는 것이다. 잘못된 타이밍의 컴팩션은 중요한 컨텍스트를 잃게 만든다.

지금 당장 압축해야 하는 신호 ✅

아래 조건 중 하나라도 해당하면 압축 좋은 타이밍이다:

신호	이유
큰 리서치/분석 블록이 완료됨	결과물은 파일로 저장됐고 과정은 필요 없음
기능/마일스톤 구현 완료 + 테스트 통과	깨끗한 상태에서 새 작업 시작
디버깅 루프 완전 종료 (원인 확정 + 수정)	진단 과정 컨텍스트는 불필요
대규모 리팩토링 완료	중간 단계 흔적이 노이즈가 됨
컨텍스트 사용량이 약 70~80%	여유 있을 때 압축이 더 좋은 요약 생성
작업 전환 (완전히 다른 도메인으로 이동)	이전 컨텍스트가 새 작업에 도움 안 됨

압축하면 안 되는 신호 ❌

신호	이유
진행 중인 디버깅 사이클 중간	가설/사실 수집 컨텍스트가 사라짐
복잡한 멀티파일 리팩토링 중간	변경 계획과 진행 상태가 사라짐
아직 커밋 안 된 중요 결정사항 존재	decisions.md에 먼저 기록 후 압축
오류 메시지 + 수정 시도 반복 중	Iron Law 컨텍스트가 필수

압축 전 체크리스트

압축 명령 실행 전 반드시 확인:

• 현재 작업의 결과물이 파일로 저장됐는가?
• 중요한 결정이 .claude/memory/decisions.md에 ADR로 기록됐는가?
• 이번 작업에서 배운 함정이 lessons.md에 있는가?
• 미완료 테스트가 없는가? (git status 확인)
• 다음에 이어서 해야 할 작업이 명확히 정의됐는가?

압축 실행

/compact          # Claude Code 기본 컴팩션

또는 직접 요청:

"지금까지 작업을 요약하고 컨텍스트를 압축해줘"

압축 후 재시작 팁

압축 직후 첫 메시지에서:

1. 방금 완료한 작업의 상태를 1~2줄로 재확인한다
2. 다음에 할 작업을 명시한다
3. session-start.sh가 메모리를 자동 주입하므로 과거 실수는 자동으로 복원됨

안티 패턴

• 95% 도달할 때까지 기다리는 것 — 강제 압축은 요약 품질이 낮다.
• 중간 디버깅 중에 압축하는 것 — 문맥을 잃고 처음부터 다시 진단.
• 압축 전에 메모리 파일을 갱신 안 하는 것 — 교훈이 소멸된다.