Cmd. /compact
같은 대화를 이어가면서 지금까지의 기록을 구조화된 요약으로 압축해 컨텍스트 공간을 확보하는 명령. 선택 instructions로 요약 초점을 지정하고, 압축 후 보존 항목까지 다룹니다.
핵심 요약
- 현재 대화를 요약해 context 확보
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
현재 대화를 요약해 context 확보
/compact [instructions]사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-09-22 · Claude Code 2.1.278 |
설치본의 명령 메뉴와 계정·조직 설정에 따라 사용할 수 있는 항목이 달라집니다.
사용 예
/compact Preserve the migration decisions and failing test names/compact특정 주제에 초점을 맞추어 요약하도록 instructions를 전달할 수도 있습니다:
/compact auth 리팩터링/compact API 마이그레이션 진행 상황만 유지하고 나머지는 줄여줘선택 시점
- 긴 디버깅 세션에서 컨텍스트가 비대해졌을 때 핵심만 보존
- 특정 주제(예:
auth 리팩터링)를 instructions로 지정해 관련 없는 맥락을 더 많이 줄이기 - 응답 속도가 느려지거나 컨텍스트가 성능에 영향을 주기 시작할 때 공간 확보
- 같은 대화를 이어가면서 새로운 긴 작업을 시작하기 직전에 정리
/context로 사용량을 확인한 뒤, 필요하다고 판단되면/compact로 압축
관련 명령 선택
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/compact | 같은 대화를 유지하며 요약으로 컨텍스트 확보 | 세션을 이어가며 공간·속도 확보 |
/clear | 컨텍스트를 비우고 새 대화 시작(별칭 /reset, /new) | 처음부터 새로 시작 |
/context | 현재 컨텍스트 사용량을 색상 그리드로 시각화 | 압축 여부 판단·최적화 지점 확인 |
실행 결과와 유지 범위
대화를 요약해 사용 중인 컨텍스트를 줄입니다. 요약에 남겨야 할 결정·제약은 실행 전에 명시합니다.
공식 문서(/commands)의 설명은 다음과 같습니다.
/compact [instructions]— Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary.
/compact는 지금까지의 대화 기록을 구조화된 요약으로 압축해 컨텍스트 윈도우 공간을 확보하는 명령입니다. 컨텍스트가 길어져 응답 품질·속도에 영향을 주기 시작할 때, 또는 새로운 긴 작업을 시작하기 전에 실행합니다. 인자로 초점(instructions)을 넘기면 그 주제를 우선해 요약합니다.
/clear(대화 자체를 비우고 새로 시작)와 달리 /compact는 같은 대화를 이어가면서 공간만 확보합니다. 이 점이 두 명령의 핵심 차이입니다. 공식 문서도 /clear 항목에서 "같은 대화를 계속하면서 컨텍스트를 확보하려면 /compact를 쓰라"고 안내합니다.
compaction이 일어나면 대화 기록은 구조화된 요약으로 대체되고, 터미널에는 "Conversation compacted" 메시지가 표시됩니다. 요약 자체는 터미널에 출력되지 않고 백그라운드에서 처리됩니다.
압축 후 무엇이 남는가 (what survives compaction)
공식 컨텍스트 문서(context-window)는 항목별로 압축 후 동작을 명시합니다.
| 항목 | 압축 후 동작 |
|---|---|
| 시스템 프롬프트·output style | 그대로 유지 (메시지 기록에 포함되지 않음) |
프로젝트 루트 CLAUDE.md·미스코프 룰 | 디스크에서 다시 주입(re-injected) |
| Auto memory | 디스크에서 다시 주입 |
paths: 프론트매터가 있는 룰 | 손실 — 해당 파일을 다시 읽을 때까지 복원되지 않음 |
하위 디렉터리의 중첩 CLAUDE.md | 손실 — 그 디렉터리의 파일을 다시 읽을 때까지 복원되지 않음 |
| 호출된 스킬 본문 | 다시 주입(스킬당 5,000 토큰·전체 25,000 토큰 상한, 오래된 것부터 제거) |
| Hooks | 해당 없음 (훅은 컨텍스트가 아니라 코드로 실행) |
핵심: 프로젝트 루트 CLAUDE.md와 auto memory는 압축 후 디스크에서 자동으로 다시 주입되므로 별도 조치 없이 살아남습니다. 반면 paths: 스코프 룰이나 중첩 CLAUDE.md는 트리거 파일을 다시 읽기 전까지 사라집니다. 압축 후에도 꼭 유지해야 하는 규칙이라면 paths: 프론트매터를 빼거나 프로젝트 루트 CLAUDE.md로 옮기세요.
스킬 인덱스(스킬 목록 한 줄 설명)는 시작 시 컨텍스트와 달리 압축 후 다시 주입되지 않고, 실제로 호출했던 스킬의 본문만 남습니다. 큰 스킬은 상한에 맞춰 앞부분 위주로 잘리니, 중요한 지시는 SKILL.md 상단에 두는 게 좋습니다.
주의사항
- compact 후에는 이전 대화의 세부 내용에 직접 접근할 수 없음 — 중요한 결정사항은 미리 메모리(
/memory)나 문서에 남겨 두는 것이 안전 - 프로젝트 루트
CLAUDE.md와 auto memory는 압축 후 디스크에서 자동 재주입되지만,paths:스코프 룰과 중첩CLAUDE.md는 트리거 파일을 다시 읽기 전까지 손실됨 - 스킬 인덱스는 압축 후 재주입되지 않으며, 호출했던 스킬 본문만 상한(스킬당 5,000·전체 25,000 토큰) 안에서 보존됨 — 큰 스킬은 앞부분 위주로 잘림
- focus instructions를 지정하면 해당 주제 외 맥락이 더 많이 제거되므로 의도적으로 사용
v2.1.69이상에서는 이미지가 보존되어 prompt cache 재사용 효율이 향상됨- VS Code에서는 압축된 내용이 접을 수 있는 "Compacted chat" 카드로 표시됨
- compact 직후
--continue로 재개할 때는v2.1.72이상 권장 (이전 버전에는 최근 지점 복원 버그가 있었음)
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록