보존된 사고

Claude Fable 5.1에서는 대화의 이전 턴(system 프롬프트, tools, 또는 이전 메시지)을 변경하면 API 응답에 영향을 미칩니다. 기본적으로 이는 API가 오류와 함께 요청을 거부하게 만들며, 대신 영향을 받는 사고 블록을 모델이 보는 내용에서 삭제하도록 선택하지 않는 한 그렇습니다(prefix_mismatch_behavior: "drop_block"). 이 검사는 2026년 8월 31일 00:00 UTC 이후에 생성된 새 계정에 대해 기본적으로 적용됩니다. 자세한 내용은 작동 방식 및 영향을 받는 대상 에 있습니다.

블록을 다시 보낼 때, API는 해당 블록의 signature를 사용하여 이전 대화가 변경되지 않았는지, 그리고 현재 모델이 해당 블록을 읽을 수 있는지 확인합니다. 이 검사는 한 가지 지침 집합 하에서 생성된 추론이 잠재적으로 적대적일 수 있는 다른 지침 집합 하에서 재생될 수 없도록 하기 위해 존재합니다.

API는 대화가 진행됨에 따라 대화를 수정할 수 있는 일급(first-class) 대안을 제공하며, 이는 대부분의 트랜스크립트 편집 사용 사례를 다룹니다: 새로운 지침을 위한 대화 중 시스템 메시지, 턴별 리마인더를 위한 턴 범위 시스템 메시지, 도구 추가 및 제거를 위한 대화 중 도구 변경, 그리고 턴별 사고 깊이를 조정하기 위한 메시지별 노력. 이 페이지의 나머지 부분에서는 통합이 영향을 받는지 여부를 확인하는 방법과 일반적인 하네스 패턴을 이러한 기능으로 마이그레이션하는 방법을 다룹니다. 추가적인 이점으로, 각 사고 블록 이전의 모든 내용을 바이트 단위로 변경하지 않고 유지하면 프롬프트 캐싱을 위한 접두사도 안정적으로 유지됩니다.

무언가를 해야 하는지 여부는 대화 기록을 관리하는 주체에 따라 달라집니다:

• 공식 Claude 제품 또는 SDK를 사용하는 경우: Claude Code, claude.ai, Claude Managed Agents, 또는 Claude Agent SDK. 이들은 접두사를 그대로 유지해 줍니다.
• Messages API를 직접 호출하는 경우, 자체 에이전트 루프 또는 기타 설정에서. 코드를 확인하고 messages 배열이 추가 전용(append-only)으로 처리되는지 확인해야 합니다. 다음과 같은 일반적인 패턴은 접두사를 편집하고 편집 이후의 사고를 무효화합니다:
  • 오래된 턴을 잘라내거나 삭제하기
  • 클라이언트에서 오래된 턴을 요약하고 최근 턴을 유지하기
  • 이전 턴에 리마인더를 삽입하고 다음 요청에서 제거하기
  • 각 요청마다 system 프롬프트를 재구성하기(현재 시간, 토큰 예산, 모드 플래그)
  • 세션 중간에 tools에서 항목을 추가하거나 제거하기

How it works

새 요청에 대해 API는 다음을 확인합니다:

• 모델이 동일하거나 더 최신인지. 블록은 그것을 생성한 모델과 이후 모델에서 읽을 수 있으며, 이전 모델에서는 읽을 수 없습니다. 더 최신 모델로 이동하는 대화는 추론을 유지합니다. 더 오래된 모델로 이동하는 대화는 해당 블록에 대한 모델 검사에 실패하며, API는 해당 요청에 대해 이를 삭제합니다. 정확한 모델별 목록은 보존된 사고를 참조하세요.
• 블록 이전의 어떤 것도 변경되지 않았는지. 최상위 system 프롬프트, tools의 도구 집합, 그리고 블록 이전의 모든 메시지. 서버 측 압축(compaction)을 사용하면 검사되는 접두사는 가장 최근의 압축 블록에서 시작됩니다.
• 이전 사고 블록의 체인이 끊기지 않았는지. 이전 thinking 및 redacted_thinking 블록은 접두사의 일부가 아니지만, 각 사고 블록은 턴을 넘어 그 이전 블록을 기록합니다. 기록의 앞부분에서 사고 블록을 제거할 수 있습니다. 중간에서 하나를 제거하면 그 이후의 모든 사고 블록이 무효화됩니다.

모델 검사에 실패한 블록은 항상 삭제됩니다. 접두사 불일치의 경우 thinking.block_binding.prefix_mismatch_behavior로 어떤 일이 일어날지 선택하며, 이는 thinking-binding-controls-2026-08-01 베타 헤더가 필요합니다:

• "drop_block": API는 해당 블록과 대화에서 그 이후의 모든 사고 블록을 제거하고, 요청은 성공합니다. 삭제된 블록은 청구되지 않습니다. 응답은 이를 최상위 input_transformations 배열에 나열합니다(스트리밍 시 message_start 이벤트에서).
• "error": API는 첫 번째 실패한 블록을 명시하는 400 invalid_request_error와 함께 요청을 거부합니다.

기본값은 "error"입니다. 헤더를 사용하면 필드를 설정하고 응답에 input_transformations를 추가할 수 있습니다.

Who is affected

Claude Fable 5.1. 모델 목록은 보존된 사고를 참조하세요.

Claude Fable 5.1에서 API는 새 계정에 대해 검사를 적용합니다. 새 계정은 2026년 8월 31일 00:00 UTC 이후에 생성된 계정입니다. 동일한 정의가 Claude API와 클라우드 플랫폼에 적용됩니다. 이후 모델은 모든 사용자에 대해 검사를 적용할 것입니다.

prefix_mismatch_behavior를 설정하는 요청은 계정 연령과 관계없이 적용을 선택하며, 이것이 오래된 계정에서 테스트하는 방법입니다. 계정이 기본적으로 적용되는지 확인하려면 베타 헤더 없이 기록을 편집하는 요청을 보내세요: 헤더를 명시하는 400은 적용됨을 의미합니다.

How to tell whether your integration is impacted

제품이 압축이나 도구 변경을 수행하는 경우 이를 포함하여, 몇 번의 정상적인 턴에 걸쳐 통합이 보내는 정확한 요청 본문을 캡처하세요. 연속된 각 요청 쌍에 대해 system, tools, 그리고 messages의 공유 부분을 비교하세요. 새로 추가된 턴까지는 바이트 단위로 동일해야 합니다.

그런 다음 API에 대해 확인하세요. thinking-binding-controls-2026-08-01 베타 헤더와 claude-fable-5-1을 사용하여 thinking.block_binding.prefix_mismatch_behavior를 "drop_block"으로 설정하고 통합을 통해 정상적인 멀티턴 세션을 실행하세요. 이 요청은 그러한 세션의 두 번째 턴으로, 첫 번째 응답의 어시스턴트 턴을 받은 그대로 정확히 다시 보냅니다:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: thinking-binding-controls-2026-08-01" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 16000,
    "thinking": {
      "type": "adaptive",
      "block_binding": { "prefix_mismatch_behavior": "drop_block" }
    },
    "system": "You are a coding agent.",
    "messages": [
      { "role": "user", "content": "Fix the failing test." },
      {
        "role": "assistant",
        "content": [
          { "type": "thinking", "thinking": "", "signature": "EqQBCkYIBxgCKkD..." },
          { "type": "text", "text": "I need to see the test first. Which file is it in?" }
        ]
      },
      { "role": "user", "content": "tests/test_auth.py" }
    ]
  }'

그러면 모든 응답은 최상위 input_transformations 배열을 포함합니다. 각 턴마다 이를 로깅하세요:

{
  "input_transformations": [
    {
      "type": "thinking_dropped",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

• 모든 턴에서 비어 있음: 통합이 기록을 그대로 유지합니다.
• reason: "prefix_binding_mismatch": path의 블록 이전의 무언가가 이 요청과 이전 요청 사이에 변경되었습니다. 해당 턴까지 system, tools, messages를 비교하여 찾으세요.
• reason: "model_binding_mismatch": 대화가 이전 모델의 블록을 읽을 수 없는 모델로 이동했습니다(라우터, 폴백). 통합의 버그가 아닙니다. 계속 블록을 보내고 현재 모델이 읽을 수 없는 것을 API가 삭제하도록 하세요.

이는 필드를 설정하면 요청이 적용을 선택하기 때문에 모든 계정에서 작동합니다. 대신 CI에서 큰 소리로 실패하게 하려면 "error"를 설정하세요. 400은 다음과 같이 시작합니다:

messages.1.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

요청에 베타 헤더가 없으면 메시지는 다음과 같이 계속됩니다: That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header. 메시지는 보통 무엇이 변경되었는지 명시하는 문장으로 끝나며, 예를 들어 system 프롬프트나 tools 목록이 블록이 생성되었을 때와 다르다는 것입니다.

이 오류의 모든 변형에 대해서는 사고 문제 해결을 참조하세요.

What counts as an edit

두 연속 요청 사이에서:

Update your integration

각 패턴은 한 종류의 기록 편집을, 이전 바이트를 변경하지 않고 모델에 동일한 효과를 주는 API 기능으로 대체합니다.

Append assistant turns exactly as returned

각 응답의 content 배열을 저장하고 변경 없이 어시스턴트 턴으로 다시 보내세요. 받은 순서대로 모든 블록 유형을 포함하며, thinking 필드가 비어 있는 thinking 블록도 포함합니다. 알 수 없는 블록 유형이나 빈 필드를 삭제하는 중간 유형을 통해 재직렬화하지 마세요.

Add instructions with a mid-conversation system message, not by editing system

코드가 각 요청마다 최상위 system 프롬프트를 재구성하는 경우(현재 시간, 토큰 예산, 모드 플래그, 새로 발견된 프로젝트 컨텍스트), 대화의 모든 사고 블록이 검사에 실패합니다. 세션 시작 시 system을 고정하고, 무언가가 변경되면 그것이 참이 되는 messages의 지점에 role: "system" 메시지를 추가하세요:

{
  "role": "system",
  "content": "The user switched the workspace to read-only mode. Do not write files until told otherwise."
}

모델은 이를 시스템 프롬프트 권한으로 취급하며, 그 이전의 모든 것은 변경되지 않습니다. Claude Fable 5.1에서는 베타 헤더가 필요하지 않습니다. 도구 루프에서는 tool_result 사용자 메시지 뒤에 배치하고, 어시스턴트 tool_use와 그 tool_result 사이에는 절대 배치하지 마세요(제한 사항 참조).

Send per-turn reminders as turn-scoped system messages

가장 일반적인 기록 편집은 턴별 넛지입니다: 각 도구 결과 배치 뒤에 추가되는 한 줄("독립적인 읽기를 함께 요청하세요", "한동안 사용자에게 업데이트하지 않았습니다")이며, 리마인더가 쌓이지 않도록 다음 요청에서 제거됩니다. 이를 제거하는 것이 편집입니다.

대신, tool_result 사용자 메시지 뒤에 clear_at: "next_user_message"가 있는 대화 중 시스템 메시지로 넛지를 보내세요(베타 헤더 mid-conversation-system-clear-at-2026-08-21). 이 messages 배열은 두 번의 도구 라운드 이후의 요청입니다. messages[3]은 제자리에 남겨진 이전 요청의 넛지이고, messages[6]은 이 요청의 복사본입니다:

[
  { "role": "user", "content": "Fix the failing test." },
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_01",
        "name": "read_file",
        "input": { "path": "tests/test_auth.py" }
      }
    ]
  },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }]
  },
  {
    "role": "system",
    "clear_at": "next_user_message",
    "content": "Request every independent read in one turn."
  },
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_02",
        "name": "read_file",
        "input": { "path": "src/auth.py" }
      }
    ]
  },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "toolu_02", "content": "..." }]
  },
  {
    "role": "system",
    "clear_at": "next_user_message",
    "content": "Request every independent read in one turn."
  }
]

tool_result만 있는 사용자 메시지는 "다음 사용자 메시지"로 간주되므로, messages[3]은 이미 지워졌습니다: 아무것도 렌더링하지 않고 입력 토큰 비용이 들지 않지만, 여전히 배열에 있으므로 messages[4]의 사고는 유효하게 유지됩니다. messages[6]은 이번 턴에 모델이 보는 것입니다. 이후 요청에서는 둘 다 제자리에 유지하고 다음 tool_result 메시지 뒤에 다음 복사본을 추가하세요. 턴 범위 메시지는 text만 포함하며 cache_control을 받지 않습니다. 캐시 중단점은 앞선 사용자 턴에 두세요. 턴 범위 시스템 메시지를 참조하세요.

베타 없이는, 동일한 사용자 메시지에서 tool_result 블록 뒤에 넛지를 text 블록으로 추가하고, 이전 복사본을 제자리에 남겨두세요. 모델은 가장 최신 것에 따라 행동합니다.

Change tools with tool_addition and tool_removal, not by editing tools

세션 중간에 도구 집합이 변경되는 경우(인증 후 도구가 잠금 해제되거나, 모드 전환 후 위험한 도구가 철회됨), tools를 편집하지 마세요. 세션 시작 시 전체 집합을 선언하고 대화 중 도구 변경을 사용하여 그 지점부터 도구를 제공하거나 철회하세요(베타 헤더 mid-conversation-tool-changes-2026-07-01). 아직 사용할 수 없는 도구는 defer_loading: true와 이후의 tool_addition 블록을 받으며, 이 tool_removal과 동일한 형태입니다:

{
  "role": "system",
  "content": [
    { "type": "tool_removal", "tool": { "type": "tool_reference", "name": "delete_branch" } },
    { "type": "text", "text": "Branch deletion is disabled for the rest of this session." }
  ]
}

세션 중간에 스키마를 알게 되는 도구(런타임에 발견된 MCP 서버)는 defer_loading: true로 tools에 추가하고 tool_addition으로 제공할 수 있습니다. 참조되지 않은 지연 도구는 접두사의 일부가 아니므로 추가하는 것이 안전합니다. 일반 도구를 추가하는 것은 안전하지 않습니다.

Trim context on the server where you can

클라이언트 측 잘라내기와 요약은 두 번째로 일반적인 편집입니다: 가장 오래된 턴을 삭제하거나 요약하고 최근 턴을 그대로 유지합니다. 최근 턴의 사고 블록은 여러분이 제거한 기록이 아직 제자리에 있는 동안 생성되었으므로 검사에 실패합니다. 서버 측 등가물은 편집으로 간주되지 않는데, 검사가 여러분이 보낸 대로의 대화를 비교하기 때문입니다:

• 압축은 컨텍스트가 여러분이 설정한 임계값에 접근할 때 오래된 턴을 압축 블록으로 요약하며, 검사되는 접두사는 해당 블록에서 다시 시작됩니다. 그 instructions 매개변수는 여러분 자신의 요약 프롬프트를 받습니다("모든 티커, 포지션 크기, 명시된 가정을 보존하세요").
• 컨텍스트 편집은 규칙에 따라 오래된 도구 결과(clear_tool_uses_20250919) 또는 오래된 사고 블록을 오래된 것부터(clear_thinking_20251015) 지웁니다.

Custom compaction on the client

이 검사는 클라이언트 측 압축을 금지하지 않습니다. 규칙은 더 좁습니다: 여러분이 재작성한 접두사 뒤에 사고 블록을 유지하지 마세요.

단순 압축은 권장되는 형태이며 변경이 필요하지 않습니다. 대화가 너무 길어지면 이를 하나의 메시지로 요약하고 그 요약과 새 사용자 턴으로 다음 요청을 시작하며, 이전 턴이나 사고 블록을 재생하지 않습니다: messages는 [{"role": "user", "content": "<summary of the session so far>\n\n<the next instruction>"}]이 됩니다. 이전 사고가 남아 있지 않으므로 아무것도 실패하지 않으며, 모델은 압축된 대화에 대해 새롭게 사고합니다. Claude 모델은 이 방식으로 장기 작업에 대해 학습되었으며, 대부분의 워크로드에서 더 정교한 방식과 비슷하게 수행됩니다. 이는 모든 압축이 그렇듯이 압축 지점에서 프롬프트 캐시를 재설정합니다.

다른 두 가지 일반적인 형태는 작성된 대로 실패하며 각각 한 가지 변경이 필요합니다:

• **꼬리 유지 압축(keep-tail compaction)**은 오래된 턴을 요약하고 가장 최근 턴을 그대로 유지합니다. 유지된 턴의 사고 블록은 전체 기록에 대해 생성되었으므로 요약 뒤에서 실패합니다. 수정: 넘겨받는 모든 어시스턴트 턴에서 thinking과 redacted_thinking을 제거하고 text와 tool_use를 유지하거나, prefix_mismatch_behavior: "drop_block"을 보내 API가 이를 제거하도록 하세요.
• **백그라운드 압축(background compaction)**은 중요 경로 밖에서 요약을 구축하고 대화가 계속되는 동안 이를 교체하므로, 그 사이에 생성된 모든 턴은 교체 이전의 사고를 가집니다. 수정: 교체 이전에 생성된 사고 블록을 여전히 포함하는 모든 요청에 "drop_block"을 보내거나(또는 해당 블록을 직접 제거하세요; 교체 후 첫 번째 응답의 input_transformations가 정확히 어떤 것인지 나열합니다), 동기적으로 압축하세요.

트랜스크립트 중간에서 개별 턴을 잘라내면 그 이후의 모든 것이 무효화되며, 어떤 클라이언트 측 형태도 이를 피할 수 없습니다. 여러분이 하려던 지침 변경에는 대화 중 시스템 메시지를 사용하거나, 선택적 제거에는 서버 측 컨텍스트 편집을 사용하세요.

도구 라운드 중간에 압축하지 마세요: tool_use가 여전히 tool_result를 기다리고 있는 어시스턴트 턴은 사고를 그대로 유지한 채 다시 보내야 하며, 그래야 모델이 추론과 함께 라운드를 완료합니다(사고 블록 보존 참조).

Reference files by ID, not by URL that changes content

url 소스가 있는 image 또는 document 블록의 경우, 가져온 바이트는 검사되는 접두사의 일부이고 URL 문자열은 그렇지 않습니다. "최신 스크린샷" 엔드포인트나 편집된 문서는 이후 사고를 무효화합니다. 동일한 파일에 대한 회전하는 서명된 URL은 그렇지 않습니다. 턴을 넘어 참조하는 콘텐츠의 경우, Files API로 한 번 업로드하고 file_id를 사용하거나 base64를 보내세요.

Decide what happens on a mismatch

통합이 추가 전용이 되면, 프로덕션을 위한 prefix_mismatch_behavior를 선택하세요. 이는 접두사 불일치만 관리합니다. 현재 모델이 읽을 수 없는 블록(라우터 전환 또는 서버 측 폴백 이후)은 항상 삭제되며, 베타 헤더가 전송되면 input_transformations에 보고됩니다.

• "error"(기본값) 접두사 불일치가 코드의 버그만을 의미할 수 있는 경우. 조용히 삭제된 블록이 아니라 테스트 중 400에서 알게 됩니다. Message Batches API에서는 설정되지 않은 기본값이 배치 항목을 실패시키는 대신 실패한 블록을 삭제합니다; 항목이 오류를 내기를 원하면 "error"를 명시적으로 설정하세요.
• "drop_block" 실패하기보다는 영향을 받는 블록을 삭제하고 싶은 경우. input_transformations를 로깅하세요.

프로덕션에서 400을 포착하면, 동일한 요청을 재시도해도 이를 해결하지 못합니다. prefix_mismatch_behavior: "drop_block"(및 베타 헤더)으로 재시도하면, tool_use가 여전히 tool_result를 기다리고 있는 어시스턴트 턴의 블록을 포함하여 실패하는 블록을 정확히 제거합니다. 삭제는 해당 요청에만 적용되므로, 세션의 나머지 부분에 대해 계속 "drop_block"(및 베타 헤더)을 보내세요. 베타 없이는, 기록에서 모든 thinking 및 redacted_thinking 블록을 제거하고 각 턴의 text와 tool_use 블록을 제자리에 남겨둔 채 한 번 재시도하세요. 그런 다음 이를 유발한 편집을 수정하세요.

API features used on this page

한 요청에서 헤더를 결합하려면:

anthropic-beta: thinking-binding-controls-2026-08-01,mid-conversation-system-clear-at-2026-08-21,mid-conversation-tool-changes-2026-07-01

동일한 베타 이름이 Amazon Bedrock과 Google Cloud에 적용됩니다. 각 SDK로 이를 보내는 방법은 베타 헤더를 참조하세요.

Checklist

• 공식 Claude 제품 또는 SDK(Claude Code, claude.ai, Claude Managed Agents, Claude Agent SDK)가 대화 기록을 관리하는 경우, 여기서 멈추세요.
• 연속된 요청 본문이 system, tools, 그리고 공유 messages 접두사에서 바이트 단위로 동일합니다.
• prefix_mismatch_behavior: "drop_block" 하의 전체 세션이 prefix_binding_mismatch 항목을 로깅하지 않습니다.
• 어시스턴트 턴이 반환된 대로 바이트 단위로 다시 보내지며, 모든 블록 유형이 포함됩니다.
• 최상위 system과 tools가 세션에 대해 고정됩니다. 변경 사항은 role: "system" 메시지와 tool_addition / tool_removal 블록에 들어갑니다.
• 턴별 리마인더는 새로 추가되고 절대 제거되지 않는 턴 범위 시스템 메시지(또는 후행 텍스트 블록)입니다.
• 컨텍스트는 압축이나 컨텍스트 편집으로, 또는 재작성된 접두사 뒤에 사고 블록을 남기지 않고 도구 라운드를 절대 분할하지 않는 클라이언트 측 압축으로 잘립니다.
• 턴을 넘는 파일은 변경 가능한 URL이 아니라 file_id 또는 base64입니다.
• 프로덕션 prefix_mismatch_behavior가 설정되어 있고 그 400 또는 삭제된 항목이 모니터링됩니다.

Next steps