컨텍스트 편집



개요

컨텍스트 편집을 사용하면 대화 기록이 증가함에 따라 특정 콘텐츠를 선택적으로 지울 수 있습니다. 비용을 최적화하고 제한 내에 머무르는 것을 넘어, 이는 Claude가 보는 내용을 능동적으로 큐레이션하는 것입니다. 컨텍스트는 수확 체감이 있는 유한한 자원이며, 관련 없는 콘텐츠는 모델의 집중력을 저하시킵니다. 컨텍스트 편집은 이러한 큐레이션에 대한 세밀한 런타임 제어를 제공합니다. 컨텍스트 관리의 더 넓은 원칙에 대해서는 효과적인 컨텍스트 엔지니어링을 참조하세요. 이 페이지에서 다루는 내용:

• 도구 결과 지우기 - 오래된 도구 결과가 더 이상 필요하지 않은, 도구 사용이 많은 에이전트 워크플로에 가장 적합합니다
• 사고 블록 지우기 - 확장 사고를 사용할 때 사고 블록을 관리하며, 컨텍스트 연속성을 위해 최근 사고를 보존하는 옵션을 제공합니다
• 클라이언트 측 SDK 컴팩션 - 요약 기반 컨텍스트 관리를 위한 SDK 기반 대안입니다(일반적으로 서버 측 컴팩션이 선호됩니다)



서버 측 전략



도구 결과 지우기

clear_tool_uses_20250919 전략은 대화 컨텍스트가 구성된 임계값을 초과하면 도구 결과를 지웁니다. 이는 도구 사용이 많은 에이전트 워크플로에 특히 유용합니다. 오래된 도구 결과(파일 내용이나 검색 결과 등)는 Claude가 처리한 후에는 더 이상 필요하지 않습니다.

활성화되면 API는 가장 오래된 도구 결과를 시간순으로 자동으로 지웁니다. API는 지워진 각 결과를 자리 표시자 텍스트로 대체하여 Claude가 제거되었음을 알 수 있도록 합니다. 기본적으로 도구 결과만 지워집니다. clear_tool_inputs를 true로 설정하여 도구 결과와 도구 호출(도구 사용 매개변수)을 모두 지우도록 선택할 수도 있습니다.



사고 블록 지우기

clear_thinking_20251015 전략은 확장 사고가 활성화된 경우 대화에서 thinking 블록을 관리합니다. 이 전략은 사고 보존에 대한 제어를 제공합니다. 추론 연속성을 유지하기 위해 더 많은 사고 블록을 유지하거나, 컨텍스트 공간을 절약하기 위해 더 적극적으로 지울 수 있습니다.

어시스턴트 대화 턴에는 여러 콘텐츠 블록(예: 도구 사용 시)과 여러 사고 블록(예: 인터리브 사고 사용 시)이 포함될 수 있습니다.



컨텍스트 편집은 서버 측에서 발생합니다

컨텍스트 편집은 프롬프트가 Claude에 도달하기 전에 서버 측에서 적용됩니다. 클라이언트 애플리케이션은 수정되지 않은 전체 대화 기록을 유지합니다. 클라이언트 상태를 편집된 버전과 동기화할 필요가 없습니다. 평소처럼 전체 대화 기록을 로컬에서 계속 관리하세요.



컨텍스트 편집과 프롬프트 캐싱

컨텍스트 편집과 프롬프트 캐싱의 상호 작용은 전략에 따라 다릅니다:

• 도구 결과 지우기: 콘텐츠가 지워지면 캐시된 프롬프트 접두사가 무효화됩니다. 이를 고려하여 캐시 무효화가 가치 있을 만큼 충분한 토큰을 지우세요. clear_at_least 매개변수를 사용하여 매번 최소한의 토큰 수가 지워지도록 하세요. 콘텐츠가 지워질 때마다 캐시 쓰기 비용이 발생하지만, 후속 요청은 새로 캐시된 접두사를 재사용할 수 있습니다.

• 사고 블록 지우기: 사고 블록이 컨텍스트에 유지되면(지워지지 않으면) 프롬프트 캐시가 보존되어 캐시 히트가 가능하고 입력 토큰 비용이 줄어듭니다. 사고 블록이 지워지면 지우기가 발생하는 지점에서 캐시가 무효화됩니다. 캐시 성능을 우선시할지 컨텍스트 윈도우 가용성을 우선시할지에 따라 keep 매개변수를 구성하세요.



지원되는 모델

컨텍스트 편집은 지원되는 모든 Claude 모델에서 사용할 수 있습니다.



도구 결과 지우기 사용법

도구 결과 지우기를 활성화하는 가장 간단한 방법은 전략 유형만 지정하는 것입니다. 다른 모든 구성 옵션은 기본값을 사용합니다:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)



고급 구성

추가 매개변수로 도구 결과 지우기 동작을 사용자 정의할 수 있습니다:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    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"],
            }
        ]
    },
)



사고 블록 지우기 사용법

확장 사고가 활성화된 경우 컨텍스트와 프롬프트 캐싱을 효과적으로 관리하기 위해 사고 블록 지우기를 활성화하세요:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)



사고 블록 지우기 구성 옵션

clear_thinking_20251015 전략은 다음 구성을 지원합니다:

구성 예시:

마지막 3개의 어시스턴트 턴의 사고 블록 유지:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

모든 사고 블록 유지(캐시 히트 최대화):

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)



전략 결합

사고 블록 지우기와 도구 결과 지우기를 함께 사용할 수 있습니다:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)



도구 결과 지우기 구성 옵션



컨텍스트 편집 응답

context_management 응답 필드를 사용하여 요청에 적용된 컨텍스트 편집 내용과 함께 지워진 콘텐츠 및 입력 토큰에 대한 유용한 통계를 확인할 수 있습니다.

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

스트리밍 응답의 경우 컨텍스트 편집 내용은 최종 message_delta 이벤트에 포함됩니다:

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}



토큰 계산

토큰 계산 엔드포인트는 컨텍스트 관리를 지원하므로 컨텍스트 편집이 적용된 후 프롬프트가 사용할 토큰 수를 미리 볼 수 있습니다.

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

응답에는 컨텍스트 관리가 적용된 후의 최종 토큰 수(input_tokens)와 지우기가 발생하기 전의 원래 토큰 수(original_input_tokens)가 모두 표시됩니다.



메모리 도구와 함께 사용

컨텍스트 편집은 메모리 도구와 결합할 수 있습니다. 대화 컨텍스트가 구성된 지우기 임계값에 가까워지면 Claude는 중요한 정보를 보존하라는 자동 경고를 받습니다. 이를 통해 Claude는 도구 결과나 컨텍스트가 대화 기록에서 지워지기 전에 메모리 파일에 저장할 수 있습니다.

이 조합을 통해 다음을 수행할 수 있습니다:

• 중요한 컨텍스트 보존: Claude는 도구 결과가 지워지기 전에 필수 정보를 메모리 파일에 기록할 수 있습니다
• 장기 실행 워크플로 유지: 정보를 영구 저장소로 오프로드하여 컨텍스트 제한을 초과할 수 있는 에이전트 워크플로를 가능하게 합니다
• 필요에 따라 정보 접근: Claude는 모든 것을 활성 컨텍스트 윈도우에 유지하는 대신 필요할 때 메모리 파일에서 이전에 지워진 정보를 조회할 수 있습니다

예를 들어, Claude가 많은 작업을 수행하는 파일 편집 워크플로에서 컨텍스트가 증가함에 따라 Claude는 완료된 변경 사항을 메모리 파일에 요약할 수 있습니다. 도구 결과가 지워지면 Claude는 메모리 시스템을 통해 해당 정보에 계속 접근할 수 있으며 효과적으로 작업을 계속할 수 있습니다.

두 기능을 함께 사용하려면 API 요청에서 활성화하세요:

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

명령 및 예제를 포함한 전체 메모리 도구 참조는 메모리 도구를 참조하세요.



클라이언트 측 컴팩션 (SDK)

컴팩션은 토큰 사용량이 너무 커지면 요약을 생성하여 대화 컨텍스트를 자동으로 관리하는 SDK 기능입니다. 콘텐츠를 지우는 서버 측 컨텍스트 편집 전략과 달리, 컴팩션은 Claude에게 대화 기록을 요약하도록 지시한 다음 전체 기록을 해당 요약으로 대체합니다. 이를 통해 Claude는 컨텍스트 윈도우를 초과할 수 있는 장기 실행 작업을 계속 수행할 수 있습니다.



컴팩션 작동 방식

컴팩션이 활성화되면 SDK는 각 모델 응답 후 토큰 사용량을 모니터링합니다:

1. 임계값 확인: SDK는 총 토큰을 input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens로 계산합니다.
2. 요약 생성: 임계값이 초과되면 요약 프롬프트가 사용자 턴으로 삽입되고 Claude는 <summary></summary> 태그로 감싼 구조화된 요약을 생성합니다.
3. 컨텍스트 대체: SDK는 요약을 추출하고 전체 메시지 기록을 이것으로 대체합니다.
4. 계속: 대화는 요약에서 재개되며 Claude는 중단된 지점부터 계속합니다.



컴팩션 사용

토큰 사용량이 임계값을 초과할 때 자동 요약을 활성화하려면 tool_runner 호출에 compaction_control을 추가하세요.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



컴팩션 중에 발생하는 일

대화가 증가함에 따라 메시지 기록이 누적됩니다:

컴팩션 전(100k 토큰에 근접):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

토큰이 임계값을 초과하면 SDK는 요약 요청을 삽입하고 Claude는 요약을 생성합니다. 그런 다음 전체 기록이 대체됩니다:

컴팩션 후(약 2–3k 토큰으로 복귀):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude는 이 요약이 원래 대화 기록인 것처럼 계속 작업합니다.



구성 옵션



토큰 임계값 선택

임계값은 컴팩션이 발생하는 시점을 결정합니다. 임계값이 낮을수록 더 작은 컨텍스트 윈도우로 더 자주 컴팩션이 발생합니다. 임계값이 높을수록 더 많은 컨텍스트를 허용하지만 제한에 도달할 위험이 있습니다.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    # 값이 낮을수록 더 자주 압축합니다. 작업에 더 많은 컨텍스트가 필요하면 150000으로 올리세요
    compaction_control={"enabled": True, "context_token_threshold": 50000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



요약에 다른 모델 사용

요약 생성에 더 빠르거나 저렴한 모델을 사용할 수 있습니다:

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "model": "claude-haiku-4-5",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



사용자 정의 요약 프롬프트

도메인별 요구 사항에 맞는 사용자 정의 프롬프트를 제공할 수 있습니다. 프롬프트는 Claude가 요약을 <summary></summary> 태그로 감싸도록 지시해야 합니다.

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")



기본 요약 프롬프트

내장된 요약 프롬프트는 Claude에게 다음을 포함하는 구조화된 연속 요약을 작성하도록 지시합니다:

1. 작업 개요: 사용자의 핵심 요청, 성공 기준 및 제약 조건.
2. 현재 상태: 완료된 작업, 수정된 파일 및 생성된 아티팩트.
3. 중요한 발견 사항: 기술적 제약 조건, 내린 결정, 해결된 오류 및 실패한 접근 방식.
4. 다음 단계: 필요한 구체적인 조치, 차단 요소 및 우선순위.
5. 보존할 컨텍스트: 사용자 선호도, 도메인별 세부 정보 및 약속한 사항.

이 구조를 통해 Claude는 중요한 컨텍스트를 잃거나 실수를 반복하지 않고 효율적으로 작업을 재개할 수 있습니다.



제한 사항



서버 측 도구

서버 측 도구를 사용할 때 SDK가 토큰 사용량을 잘못 계산하여 컴팩션이 잘못된 시점에 트리거될 수 있습니다.

예를 들어, 웹 검색 작업 후 API 응답은 다음과 같이 표시될 수 있습니다:

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDK는 총 사용량을 63,000 + 0 + 270,000 + 1,400 = 334,400 토큰으로 계산합니다. 그러나 cache_read_input_tokens 값에는 실제 대화 컨텍스트가 아니라 서버 측 도구가 수행한 여러 내부 API 호출에서 누적된 읽기가 포함됩니다. 실제 컨텍스트 길이는 63,000 input_tokens에 불과할 수 있지만 SDK는 334k를 보고 컴팩션을 조기에 트리거합니다.

해결 방법:

• 토큰 계산 엔드포인트를 사용하여 정확한 컨텍스트 길이를 확인하세요
• 서버 측 도구를 광범위하게 사용할 때는 컴팩션을 피하세요



도구 사용 엣지 케이스

도구 사용 응답이 대기 중인 상태에서 SDK가 컴팩션을 트리거하면 요약을 생성하기 전에 메시지 기록에서 도구 사용 블록을 제거합니다. Claude는 여전히 필요한 경우 요약에서 재개한 후 도구 호출을 다시 실행합니다.



컴팩션 모니터링

컴팩션이 트리거되는 시점을 이해하면 임계값을 조정하고 예상되는 동작을 확인하는 데 도움이 됩니다.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# 로그에 다음과 같이 표시됩니다:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500



컴팩션을 사용해야 하는 경우

적합한 사용 사례:

• 많은 파일이나 데이터 소스를 처리하는 장기 실행 에이전트 작업
• 대량의 정보를 축적하는 연구 워크플로
• 명확하고 측정 가능한 진행 상황이 있는 다단계 작업
• 대화 외부에 지속되는 아티팩트(파일, 보고서)를 생성하는 작업

덜 적합한 사용 사례:

• 초기 대화 세부 정보의 정확한 회상이 필요한 작업
• 서버 측 도구를 광범위하게 사용하는 워크플로
• 많은 변수에 걸쳐 정확한 상태를 유지해야 하는 작업



다음 단계