/compact

어떻게 동작하나

/compact [지시문]을 실행하면 Claude Code가 지금까지의 대화를 구조화된 요약으로 바꿉니다. 같은 대화가 이어지므로 작업 맥락은 요약 형태로 남습니다. 컨텍스트가 한도에 가까워지면 Claude Code가 자동으로도 같은 작업을 합니다. 그래서 컨텍스트가 가득 차도 세션이 곧바로 끝나지는 않습니다.

공식 문서가 정리한 압축 후 상태는 다음과 같습니다. 사용하는 쪽이 알아야 할 부분만 추렸습니다.

• 프로젝트 루트의 CLAUDE.md와 경로 조건이 없는 규칙: 디스크에서 다시 주입됩니다.
• 자동 메모: 디스크에서 다시 주입됩니다.
• 하위 폴더의 CLAUDE.md, paths: 조건이 있는 규칙: 필요할 때 다시 불러옵니다.
• 읽거나 고친 파일: 최근 수정 순으로 최대 5개를 다시 읽습니다. 5,000토큰을 넘는 파일은 내용 없이 경로만 참조로 돌아옵니다.
• 대화 속에서만 말한 지침: 요약에 포함되지 않으면 사라질 수 있습니다. 오래 지켜야 하면 CLAUDE.md에 적으세요.

사용 방법

입력창에 /compact를 치면 됩니다. 뒤에 지시문을 붙이면 요약이 무엇을 남길지 정할 수 있습니다. 공식 문서 예시는 /compact focus on the auth bug fix 입니다. 긴 새 작업을 시작하기 전에 직접 압축하면, 자동 압축이 중요하다고 짐작한 것 대신 내가 고른 내용이 남습니다.

CLAUDE.md에 "Compact instructions" 같은 제목으로 압축 때 집중할 내용을 적어 둘 수도 있습니다. 비용 문서에 이 방식이 예시로 나옵니다.

/compact
/compact 인증 로직과 실패한 테스트 위주로 남겨줘

# CLAUDE.md에 적어 두는 방식
# Compact instructions
When you are using compact, please focus on test output and code changes

그 밖의 선택지

• /rewind에서 메시지를 고른 뒤 "Summarize from here" 또는 "Summarize up to here"로 대화의 일부만 요약할 수 있습니다.
• /autocompact <토큰 수>(예: /autocompact 500k)로 자동 압축이 시작되는 시점을 정합니다. auto를 주면 모델에 맞춘 기본값으로 돌아갑니다. v2.1.221 이상에서 쓸 수 있습니다.
• 큰 파일을 읽는 조사 작업은 서브에이전트에 맡기면 파일 내용이 내 컨텍스트에 쌓이지 않습니다.

/clear, /context와의 차이

/clear는 빈 컨텍스트로 새 대화를 시작합니다. 이전 대화는 저장되어 /resume으로 돌아갈 수 있습니다. /compact는 같은 대화를 요약해서 이어갑니다. 주제가 바뀌면 /clear, 같은 주제를 이어가면 /compact가 맞습니다.

/context는 컨텍스트를 무엇이 차지하는지 보여 주는 진단 명령입니다. 압축 전에 확인하면 압축이 필요한 상황인지, 다른 원인인지 가를 수 있습니다.

비용 측면의 주의점도 있습니다. /compact는 요약할 대화를 읽어야 하므로 큰 컨텍스트를 압축하는 것 자체가 큰 요청입니다. 연속성이 필요 없는 새 출발이라면 /clear가 비용이 들지 않습니다.

실제 예시

/compact 원인 분석 결과와 수정 대상 파일 목록 위주로 남겨줘

"테스트는 항상 병렬로 돌리지 마"를 CLAUDE.md의 규칙 항목에 추가한 뒤 /compact

/clear 결제기능

흔한 실수와 쓰지 말아야 할 때

• 주제가 완전히 바뀌었는데 /compact를 쓰는 것. 이전 작업의 요약이 새 작업에 계속 따라다닙니다. 이럴 땐 /clear가 맞습니다.
• 대화로만 한 지시가 압축 뒤에도 남을 거라고 믿는 것. 오래 가야 하는 규칙은 CLAUDE.md에 적으세요.
• 압축 후 파일 내용을 안다고 가정하는 것. 큰 파일(5,000토큰 초과)은 경로만 돌아오므로 다시 읽혀야 할 수 있습니다.
• 한도 직전까지 미루다 자동 압축에 맡기는 것. 어떤 내용이 남을지 내가 정하고 싶다면 작업 단락마다 지시문을 붙여 직접 압축하세요.

자주 묻는 질문