컨텍스트 엔지니어링 실패모드 위키

Claude Code — /compact와 자동 컴팩션

8 min read

상위: 08_00_MOC

Claude Code — /compact와 자동 컴팩션

컴팩션이란

/compact는 대화 히스토리 전체를 구조화된 요약으로 대체하는 명령이다. 컨텍스트 창이 가득 차기 전에 직접 호출할 수도 있고, 한계에 닿으면 자동으로 실행되기도 한다.

“Compaction replaces your message history with a summary. By design, this invalidates the conversation layer, since the next request has a new, shorter history that doesn’t share a prefix with the old one.” — How Claude Code uses prompt caching, Anthropic

컴팩션을 이해하는 열쇠는 “무엇이 살아남고 무엇이 사라지는가”다. 바로 여기가 05 부패 실패모드의 최전선이다.

/compact 이후 생존표

컴팩션 전후로 각 요소가 어떻게 되는지 정리하면 다음과 같다.

메커니즘컴팩션 후 상태비고
시스템 프롬프트✅ 유지메시지 히스토리 외부, 영향 없음
프로젝트 루트 CLAUDE.md✅ 디스크에서 재주입컨텐츠 변경 없으면 캐시 히트
Auto Memory (MEMORY.md)✅ 디스크에서 재주입첫 200줄/25KB 한도
User CLAUDE.md✅ 디스크에서 재주입동일
MCP 도구 목록✅ 재로드deferred 도구는 이름만
paths: 프론트매터 있는 규칙❌ 소실해당 경로 파일 재읽기 시 복원
하위 디렉토리 중첩 CLAUDE.md❌ 소실해당 디렉토리 파일 재읽기 시 복원
Skill 설명 목록❌ 소실호출된 Skill 본문만 재주입
호출된 Skill 본문⚠️ 재주입스킬당 최대 5,000토큰, 합산 25,000토큰
Hooks해당 없음코드로 실행, 컨텍스트 아님

Skill 설명 목록에 대해서는 공식 문서가 이렇게 못 박는다.

“Unlike the rest of the startup content, this listing is not re-injected after /compact. Only skills you actually invoked get preserved.” — Explore the context window, Anthropic

실무에서는 이렇게 읽으면 된다. 컴팩션 후 Claude가 “그 스킬이 있다는 걸 잊은” 듯 행동한다면, 스킬 설명 목록이 사라진 탓이다. 이 세션에서 실제로 호출한 스킬만 살아남는다.

graph TD
    subgraph startup["세션 시작 자동 로드"]
        SP["시스템 프롬프트"]
        AM["Auto Memory MEMORY.md<br/>첫 200줄/25KB"]
        ENV["환경 정보<br/>CWD·플랫폼·셸·git"]
        MCP["MCP 도구 목록<br/>기본 deferred"]
        SKILL["Skill 설명 목록"]
        UCMD["~/.claude/CLAUDE.md"]
        PCMD["프로젝트 CLAUDE.md"]
    end

    subgraph after["/compact 이후"]
        SP2["시스템 프롬프트 ✅"]
        AM2["Auto Memory ✅ 재주입"]
        PCMD2["프로젝트 CLAUDE.md ✅ 재주입"]
        PSR["Path-scoped Rules ❌ 소실"]
        NEST["중첩 CLAUDE.md ❌ 소실"]
        SKILLB["Skill 본문 ⚠️ 5K/스킬·25K 합산"]
        SKILLD["Skill 설명 목록 ❌ 소실"]
    end

    SP --> SP2
    AM --> AM2
    PCMD --> PCMD2
    SKILL --> SKILLD
    SKILL --> SKILLB

    style SKILLD fill:#f8d7da
    style PSR fill:#fff3cd
    style NEST fill:#fff3cd
    style SKILLB fill:#fff9c4

수동 /compact — 포커스 지시

/compact Focus on the auth bug fix
/compact Focus on code samples and API usage

포커스 지시를 붙이면 요약이 어느 쪽으로 향할지 직접 정할 수 있다. 지시 없이 호출하면 무엇이 중요한지 Claude가 알아서 판단한다.

CLAUDE.md에 컴팩션 지침을 넣어둘 수도 있다.

# Compact instructions
 
When you are using compact, please focus on test output and code changes

이렇게 하면 자동 컴팩션 시에도 해당 지침이 반영된다.

자동 컴팩션 (Auto-compaction)

컨텍스트 창 한계에 닿으면 자동으로 실행된다. 수동 /compact와 메커니즘은 같되, 포커스 지시를 줄 수 없다는 점만 다르다.

“Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching, which reduces costs for repeated content like system prompts, and auto-compaction, which summarizes conversation history when approaching context limits.” — Manage costs effectively, Anthropic

실무 팁이라면, 자동 컴팩션이 작업 한복판에서 터지는 일을 피하려면 작업을 전환하는 시점에 직접 /compact를 돌려두는 게 좋다. 컨텍스트 창 사용률은 /usage나 statusline으로 실시간 확인할 수 있다.

컴팩션과 캐시 비용

컴팩션 요약 생성 자체는 기존 캐시 prefix를 재사용하므로 비용이 크지 않다:

“To produce the summary, Claude Code sends a one-off request with the same system prompt, tools, and history as your conversation, plus a summarization instruction appended as a final user message. Because it shares your prefix, that request reads the existing cache rather than reprocessing the full history.” — How Claude Code uses prompt caching, Anthropic

정작 느려지는 대목은 그다음이다. 컴팩션 직후 첫 턴은 새로 짧아진 히스토리를 두고 캐시를 다시 쌓아야 해서 잠깐 더디게 느껴질 수 있다.

/rewind와의 차이는 이렇다.

  • /compact: 히스토리를 요약으로 대체하므로 새 prefix 캐시를 다시 쌓아야 한다.
  • /rewind: 이전 턴으로 되돌려 기존 캐시 prefix를 그대로 쓰므로 더 경제적이다. 방향이 잘못 틀어졌을 때는 이쪽이 낫다.

컴팩션 생존을 위한 실무 전략

  1. 늘 필요한 규칙은 루트 CLAUDE.md에 둔다. path-scoped 규칙은 컴팩션 후 사라지기 때문이다.
  2. 중요한 스킬은 세션 초반에 한 번 호출해 둔다. 본문이 재주입되는 건 실제로 호출한 스킬뿐이다.
  3. 중요한 결정은 컴팩션 전에 CLAUDE.md에 적어 둔다. 대화 히스토리는 날아가도 CLAUDE.md는 다시 주입된다.
  4. 포커스 지시를 적극 쓴다. /compact Focus on X로 요약 품질을 다잡을 수 있다.
  5. 작업이 자연스럽게 끊기는 시점에 직접 돌린다. 그래야 자동 컴팩션이 불쑥 끼어드는 일을 막는다.

참고문헌

관련 노트

그래프 뷰

백링크