Claude 가이드 #26: 컨텍스트 편집 — 대화가 길어져도 토큰 한계 걱정 없이

이 글은 Claude API 공식 문서의 Context editing 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/build-with-claude/context-editing 마지막 확인: 2026-06-09

1. 한 줄 요약
#

대화가 길어져 AI의 기억 공간이 가득 차기 전에, 오래된 자료부터 자동으로 비워주는 기능입니다.

2. 무엇이고 왜 좋을까
#

책상이 좁아지면 다 본 책부터 책장에 꽂아두는 것과 같습니다.

Claude(클로드)는 한 번에 기억할 수 있는 양(컨텍스트 윈도우, context window — ‘대화 기억 공간’)이 정해져 있습니다. 대화를 오래 이어가거나 PDF·검색 결과를 많이 주고받으면, 이 기억 공간이 금방 가득 차죠. 그러면 새 질문을 못 받거나, 비용이 점점 비싸집니다.

컨텍스트 편집(Context Editing)은 대화 중에 오래된 자료(예: 이미 다 읽은 PDF, 한참 전 검색 결과)를 골라서 비워줍니다. 클로드는 “여기 있던 내용은 정리됐어요"라는 짧은 메모만 보게 되고, 새 질문은 깨끗한 책상에서 받게 되죠.

핵심 수치 하나만 기억하세요. 기본 설정은 입력 토큰이 10만 개를 넘으면 정리를 시작합니다. 토큰(token)은 ‘AI가 글자를 세는 단위’로, 한국어 기준 대략 글자 1~2개가 1토큰이에요.

3. 이런 상황에서 써요
#

이 기능이 가장 빛을 발하는 건 대화가 길어졌을 때입니다. 세 가지 그림을 보여드릴게요.

상황 1: 학생이 논문 여러 편을 연속으로 요약시킬 때
#

학기말 과제로 논문 10편을 차례로 클로드에게 요약시킨다고 해볼게요. 1편씩 첨부하고 “요약해줘"를 반복하면, 5~6편쯤부터 클로드는 1편 본문을 통째로 들고 있느라 기억 공간이 비좁아집니다. 컨텍스트 편집을 켜두면 이미 요약이 끝난 1·2편 원문은 자동으로 정리되고, 7편째도 처음처럼 가볍게 요약할 수 있어요.

상황 2: 회사에서 매뉴얼을 보며 하루 종일 질문할 때
#

100페이지짜리 사내 매뉴얼을 첨부해두고 오전부터 오후까지 “휴가 신청은?”, “출장비 한도는?” 하고 30번쯤 물어본다고 해봅시다. 옛 질문에 클로드가 매뉴얼 일부를 인용해 길게 답했다면, 그 답변들이 점점 쌓여 기억 공간을 먹습니다. 컨텍스트 편집은 오래된 답변에 딸린 자료부터 살짝 비워줘, 오후 늦게도 첫 질문처럼 매끄럽게 답을 받게 해줍니다.

상황 3: 책 한 권을 통째로 정리하면서 계속 후속 질문을 할 때
#

소설책 한 권을 첨부하고 “전체 줄거리 알려줘 → 3장만 더 자세히 → 등장인물 관계도는?” 하고 끝없이 물어볼 때. 매번 책 본문이 같이 따라다니지는 않지만, 그동안 나눈 대화가 쌓여서 무거워집니다. 컨텍스트 편집을 켜두면 대화가 길어져도 한계에 부딪히지 않고, 마지막 장까지 편하게 질문할 수 있어요.

4. 가볍게 시작하기
#

💻 개발 경험이 있으신가요? 아래 코드는 Python(파이썬) 기준 가장 짧은 예시입니다. 비개발자라면 “아, 이렇게 한 줄 추가하는구나” 정도만 보고 넘어가셔도 좋습니다.

import anthropic
client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{"role": "user", "content": "최근 AI 동향 검색해줘"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    # 컨텍스트 편집 베타 기능 켜기
    betas=["context-management-2025-06-27"],
    # 오래된 검색 결과는 자동으로 정리해줘
    context_management={
        "edits": [{"type": "clear_tool_uses_20250919"}]
    },
)

진짜 핵심은 마지막 두 줄입니다. betas에 베타 헤더 한 줄을 넣고, context_management에 “오래된 도구 결과를 비워라"라는 한 줄짜리 지시를 적은 거예요. 나머지 설정은 다 기본값으로 작동하니, 처음에는 이렇게 시작해도 충분합니다.

5. 흔한 오해와 함정
#

⚠️ 함정 1: “이거 켜면 무조건 싸지죠?”
#

아쉽지만 항상 그렇진 않아요. 컨텍스트 편집은 자료를 비울 때마다 캐시(잠깐 기억해두기)를 새로 만들어야 하는 비용이 살짝 듭니다. 너무 조금 비우면 캐시 새로 만든 비용이 더 클 수도 있죠. 공식 문서도 “충분히 많이 비울 때만 활성화되도록” clear_at_least(최소 몇 토큰은 비워야 작동) 같은 안전장치를 권장합니다. 작은 대화에서는 굳이 안 켜셔도 돼요.

⚠️ 함정 2: “나는 대화 기록을 다 갖고 있는데, 같이 줄여야 하나요?”
#

아닙니다. 정리는 클로드 서버 쪽에서만 이뤄집니다. 내 PC나 앱에 저장된 대화 기록은 그대로 두셔도 돼요. 그러니까 “내가 갖고 있는 채팅 로그를 일부러 잘라내야 하나?” 하고 걱정하실 필요 없습니다. 평소처럼 다 보내시면, 클로드가 받기 직전에 알아서 정리해서 봐요.

⚠️ 함정 3: “오래된 자료가 사라지면 클로드가 헷갈리지 않나요?”
#

비워진 자리에는 “여기 있던 내용은 정리됐어요"라는 안내 문구가 남습니다. 그래서 클로드는 “예전 자료가 있었다"는 사실은 알고 있죠. 하지만 그 내용을 다시 봐야 한다면 곤란해질 수 있어요. 그래서 정말 중요한 자료(예: 사용자가 처음에 준 요구사항)는 exclude_tools 같은 옵션으로 “이건 절대 비우지 마세요"라고 따로 지정할 수 있습니다.

6. 한 단계 더 (관심 있는 분만)
#

🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 들여다보고 싶은 분을 위한 보너스입니다. 본문만 읽으셨어도 충분합니다.

조금 더 정교하게 쓰고 싶다면, 언제·얼마나 정리할지 직접 지정할 수 있어요.

context_management = {
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            # 입력 토큰이 3만 개를 넘으면 정리 시작
            "trigger": {"type": "input_tokens", "value": 30000},
            # 최근 도구 사용 3개는 남겨두기
            "keep": {"type": "tool_uses", "value": 3},
            # 한 번에 최소 5천 토큰은 비워야 작동
            "clear_at_least": {"type": "input_tokens", "value": 5000},
            # 웹 검색 결과는 비우지 않기
            "exclude_tools": ["web_search"],
        }
    ]
}

이 네 옵션만 알아도 충분합니다. 표로 정리하면 이래요.

옵션	뜻	비유
`trigger`	언제 정리 시작?	“책상이 이만큼 차면 치우기 시작”
`keep`	몇 개는 남겨둘까?	“최근 본 책은 책상에 두기”
`clear_at_least`	최소 얼마나 치울까?	“이만큼 못 치우면 안 치우기”
`exclude_tools`	절대 안 치울 자료는?	“이 책은 늘 책상에 두기”