Claude의 컨텍스트 편집 기능 완전 이해하기

컨텍스트 편집이란?

Claude의 컨텍스트 편집은 대화 내 내용이 너무 많아질 때 오래된 정보(특히 툴 사용 결과)를 자동으로 정리해주는 기능입니다. 이를 통해 모델이 최신 맥락에 집중하고, 불필요하게 많은 데이터를 처리하지 않아 효율이 높아집니다.

지원되는 모델과 활성화 방법

현재 Claude Opus 4.1, Opus 4, Sonnet 4.5, Sonnet 4에서만 사용할 수 있어요. 기능을 켜려면 API 요청에 다음 헤더를 추가해야 합니다:

anthropic-beta: context-management-2025-06-27

기본 사용법과 설정 예시

컨텍스트 편집 활성화는 매우 간단해요. 최소한의 설정으로 아래처럼 시작할 수 있습니다.

curl https://api.anthropic.com/v1/messages 
--header "x-api-key: $ANTHROPIC_API_KEY" 
--header "anthropic-version: 2023-06-01" 
--header "content-type: application/json" 
--header "anthropic-beta: context-management-2025-06-27" 
--data '{
  "model": "claude-sonnet-4-5",
  "max_tokens": 4096,
  "messages": [{ "role": "user", "content": "최근 AI 동향을 찾아줘" }],
  "tools": [{ "type": "web_search_20250305", "name": "web_search" }],
  "context_management": { "edits": [{ "type": "clear_tool_uses_20250919" }] }
}'

이 설정은 특별한 추가 옵션 없이 오래된 툴 결과만 관리해줍니다.

더 섬세하게 조절하기

컨텍스트 편집은 다양한 옵션으로 더 촘촘하게 설정할 수 있어요.

trigger: 언제 컨텍스트 편집이 시작될지 기준을 정합니다. 예를 들어, 입력 토큰이 30,000개를 넘으면 실행하게 할 수 있습니다.
keep: 최근 몇 번의 툴 사용 결과를 남길지 결정합니다.
clear_at_least: 무조건 몇 개의 토큰 이상은 지우도록 설정해, 편집의 효율을 극대화할 수 있습니다.
exclude_tools: 절대 지우지 않을 툴 이름을 지정해, 중요한 정보는 남겨둘 수 있어요.
clear_tool_inputs: 결과뿐 아니라 툴에 제공된 입력값도 동시에 지우고 싶을 때 true로 설정하면 됩니다.

설정 예시:

"context_management": {
  "edits": [
    {
      "type": "clear_tool_uses_20250919",
      "trigger": { "type": "input_tokens", "value": 30000 },
      "keep": { "type": "tool_uses", "value": 3 },
      "clear_at_least": { "type": "input_tokens", "value": 5000 },
      "exclude_tools": ["web_search"]
    }
  ]
}

컨텍스트 변경이 미치는 영향

편집이 이루어지면 캐시된 프롬프트가 무효화됩니다. 즉, 컨텍스트가 바뀐 만큼 새로 캐시를 저장하게 되니, 성능을 고려하면 한 번에 충분한 내용을 지우는 것이 좋습니다.

편집 결과 및 통계 확인법

API 응답에서 실제 뭐가 어떻게 바뀌었는지 확인할 수 있습니다. 적용된 편집 종류, 몇 번의 툴 사용 결과가 사라졌는지, 몇 개의 토큰이 정리됐는지 통계 값이 함께 제공됩니다.

"context_management": {
  "applied_edits": [
    {
      "type": "clear_tool_uses_20250919",
      "cleared_tool_uses": 8,
      "cleared_input_tokens": 50000
    }
  ]
}

토큰 계산과 시뮬레이션

컨텍스트 편집 이후 실제로 사용되는 토큰 수를 미리 계산해보고 싶을 때, 전용 엔드포인트를 사용할 수 있습니다.

curl https://api.anthropic.com/v1/messages/count_tokens 
--header "x-api-key: $ANTHROPIC_API_KEY" 
--header "anthropic-version: 2023-06-01" 
--header "content-type: application/json" 
--header "anthropic-beta: context-management-2025-06-27" 
--data '{ ... }'

이렇게 하면 정리 전과 후의 토큰 숫자를 비교할 수 있습니다.

왜 컨텍스트 편집이 중요한가?

대량의 대화나 도구 활용이 반복되는 상황에서 Claude가 성능 저하 없이 최신 정보를 잘 이해하려면, 적절한 컨텍스트 관리가 필수입니다. 자동화된 전략 덕분에 개발자가 직접 대화 기록을 정리할 필요가 없어지고, 비용‧속도‧정확성 모두 향상되죠.

출처 및 참고 : Context editing - Claude Docs