목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Compaction(컴팩션 — 자동 요약) 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/build-with-claude/compaction 마지막 확인: 2026-05-18
1. 한 줄 요약 #
대화가 길어지면 Claude가 앞부분을 알아서 짧은 요약본으로 갈아 끼워 끊김 없이 이어줍니다.
2. 무엇이고 왜 좋을까 #
긴 회의에 뒤늦게 합류한 사람에게 비서가 “여기까지 이런 얘기 나왔어요"라고 핵심만 정리해주는 것과 같습니다.
Claude는 한 번에 기억할 수 있는 글자 수(이걸 컨텍스트 윈도우, 즉 “지금 보고 있는 종이의 크기"라고 부릅니다)에 한도가 있습니다. 대화가 그 한도에 가까워지면 더 이상 답을 못 하거나, 앞 내용을 잊어버리기 시작합니다. Compaction을 켜두면 Claude가 알아서 “지금까지 우리 이런 얘기 했죠"라는 요약본을 만들어 앞 내용을 그 요약본으로 교체합니다.
기본 설정은 입력이 15만 토큰(한국어 기준 대략 책 한 권 분량)에 가까워지면 자동으로 요약이 시작됩니다. 최소 5만 토큰부터 조정할 수 있습니다.
💡 베타 기능입니다. 사용하려면 요청에
compact-2026-01-12라는 베타 표시를 함께 넣어야 합니다. 지원 모델은 Opus 4.7, Opus 4.6, Sonnet 4.6입니다.
3. 이런 상황에서 써요 #
상황 1: 졸업 논문을 며칠에 걸쳐 정리하는 학생 #
“오늘 자료 5개를 정리하고, 내일 또 자료 3개를 추가해서 같은 대화방에서 분석을 이어가고 싶어요.” 평소엔 대화가 너무 길어지면 새로 시작해야 하지만, Compaction을 켜두면 Claude가 앞 자료를 요약본으로 압축해두고 새 자료를 계속 받아줍니다. 처음부터 “내 주제가 뭐였더라"를 다시 설명하지 않아도 됩니다.
상황 2: 회사 매뉴얼 챗봇을 운영하는 사무팀 #
회사 정책 문서가 100페이지인데, 직원들이 하루 종일 한 챗봇에 여러 질문을 던집니다. “휴가 신청은요?” “출장비는요?” “재택근무 규정은요?” 질문이 쌓이면서 대화가 점점 길어지지만, Compaction이 알아서 앞쪽을 요약해주니 챗봇이 도중에 멈추지 않습니다. 사용자 입장에서는 “오늘도 잘 대답하네"가 전부입니다.
상황 3: 가족 여행 계획을 천천히 다듬는 일반인 #
“항공권부터 보자 → 호텔도 비교해줘 → 그럼 식당은? → 아이가 알레르기 있으니 다시 조정해줘 → 일정표로 만들어줘.” 이런 식으로 며칠 동안 같은 대화에서 다듬다 보면 글이 산처럼 쌓입니다. Compaction은 앞쪽의 항공권·호텔 비교를 요약본으로 만들어두고, 마지막 대화에 집중해서 답을 줍니다. 마치 비서가 노트를 정리하면서 따라오는 느낌입니다.
4. 가볍게 시작하기 #
💻 개발 경험 있으신가요? 아래 코드는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “한 줄만 더하면 켜지는구나” 정도로 보고 넘어가셔도 좋습니다.
import anthropic
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "여행 계획 짜줘"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"], # 베타 표시 (필수)
model="claude-opus-4-7",
max_tokens=4096,
messages=messages,
context_management={
"edits": [{"type": "compact_20260112"}] # ← 이 한 줄이 자동 요약 활성화
},
)
# 답변(요약본 블록까지 포함)을 대화 기록에 그대로 붙여서 다음 질문 이어가기
messages.append({"role": "assistant", "content": response.content})핵심은 두 가지입니다. 첫째, context_management 안에 compact_20260112를 적어주면 그 다음부터는 알아서 요약이 시작됩니다. 둘째, Claude의 답을 받은 뒤에는 그 답을 그대로 messages 목록에 붙여줘야 합니다. 답변 속에 요약본이 들어 있는데, 이걸 빼버리면 다음 대화에서 앞 내용을 다 잊어버립니다.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “기본값 그대로 두면 너무 늦게 요약되지 않나요?” #
기본 임계점은 15만 토큰입니다. 책 한 권 분량이라 평범한 대화에서는 한참 멀어요. 하지만 PDF나 긴 문서를 한 번에 넣는다면 빨리 닿을 수 있습니다. 일찍 요약하고 싶다면 trigger 값으로 5만 토큰 이상부터 조정할 수 있습니다.
⚠️ 함정 2: “요약했는데 왜 비용이 더 나온 것 같죠?” #
요약본을 만드는 것도 Claude를 한 번 더 부르는 일이라 비용이 듭니다. 응답에 usage.iterations라는 항목이 있는데, 거기 compaction이라고 표시된 줄이 요약 비용입니다. 총 비용은 iterations 안의 항목을 모두 합쳐야 정확합니다. 짧은 대화에 무리하게 켜둘 필요는 없습니다.
⚠️ 함정 3: “갑자기 Claude가 앞 내용을 모르는 것 같아요” #
요약본 블록을 다음 요청에 그대로 넣어주지 않으면, 앞 대화가 통째로 빠집니다. 코드에서 messages.append({"role": "assistant", "content": response.content})를 빼먹지 않는 것이 핵심입니다. 요약본은 Claude가 자기 자신에게 남긴 메모 같은 것이라, 다음 요청에 동봉해야 의미가 있습니다.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
요약이 시작될 때 잠깐 멈춰 세우고, 최근 몇 개 메시지는 요약하지 말고 원본 그대로 보존하고 싶을 수 있습니다. 예를 들어 “지금 막 나눈 대화"는 너무 중요해서 요약본으로 뭉뚱그리면 아쉽잖아요. 이럴 때는 pause_after_compaction 옵션을 켜둡니다.
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-4-7",
max_tokens=4096,
messages=messages,
context_management={
"edits": [{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 100000}, # 10만 토큰부터 요약
"pause_after_compaction": True, # 요약 직후 일시 정지
}]
},
)
# 요약 후 멈췄다면, 원하는 최근 메시지를 직접 붙여서 다시 호출하면 됩니다.
if response.stop_reason == "compaction":
print("요약이 끝났습니다. 최근 대화를 보존하고 이어갈게요.")요약 직후 응답의 stop_reason이 "compaction"으로 표시되면 “지금 막 요약이 끝났다"는 신호입니다. 이때 마지막 두세 개의 메시지를 직접 골라 요약본 뒤에 붙여서 다시 호출하면, “옛 대화는 요약 + 최근 대화는 원본” 형태로 깔끔하게 이어집니다. 자매 가이드 #7 프롬프트 캐시와 함께 쓰면 요약본을 캐시에 올려둬 다음 호출이 더 빨라집니다.
7. 한 마디 #
긴 대화가 끊기는 게 답답해서 매번 새 채팅창을 여신 경험, 누구나 한 번쯤 있으실 거예요. Compaction은 그 답답함을 “한 줄 더하기"로 풀어주는 기능입니다. 처음엔 “요약이 잘 될까” 걱정되시겠지만, 막상 켜보면 의외로 매끄럽게 이어집니다. 만약 답이 어색해진다면 함정 1~3 중 하나일 가능성이 큽니다 — 임계점, 비용 계산, 답변 붙이기 세 가지만 확인해보세요.
다음 글에서는 #9 Context Editing — 도구 결과나 추론 블록을 골라서 비우는 기능을 다룰 예정입니다. Compaction이 “통째로 요약"이라면, Context Editing은 “필요 없는 부분만 골라 지우기"에 가깝습니다. 두 가지를 알아두면 긴 대화를 훨씬 가볍게 다룰 수 있습니다.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
