사고 조정하기

Claude의 사고(thinking)는 적응형입니다. 모델은 각 요청을 평가하고 사고할지 여부와 얼마나 사고할지를 스스로 결정합니다. 여러분은 의도를 설정하고, 선택적으로 effort를 지정하며, 모델은 추론이 도움이 될 것이라고 판단하는 곳에 추론을 할당합니다.

이 덕분에 사고는 사소한 요청과 복잡한 요청이 섞여 있는 워크로드, 그리고 단계마다 적절한 추론의 양이 달라지는 장기 에이전트 워크플로에 매우 적합합니다.

사고를 켜는 방법, 사고 출력을 읽는 방법, 그리고 Claude Fable 5 및 Claude Mythos 5의 사고 출력에 대해 알아보려면 사고 개요를 참조하세요. 이 페이지에서는 Claude가 언제 사고할지 결정하는 방식, 그 결정을 조정하는 방법, 그리고 그에 따른 캐싱, 비용, 가격 책정 메커니즘을 다룹니다.

Claude가 언제 사고할지 결정하는 방식

사고는 모델에게 선택 사항입니다. 각 요청에서 Claude는 입력의 복잡성을 가늠하고 더 깊은 추론이 답변을 개선할지 결정합니다. 단순한 사실 질문은 사고 블록 없이 바로 응답을 받을 수 있으며, 여러 단계의 수학 문제나 까다로운 디버깅 작업은 더 깊은 추론을 유발합니다.

이 결정은 요청마다 이루어집니다. 같은 대화 안에 사고가 있는 턴과 없는 턴이 함께 있을 수 있으며, Claude가 사고하지 않기로 선택한 턴에는 사고 블록이 없습니다. 모든 어시스턴트 턴이 사고 블록으로 시작한다고 가정하는 애플리케이션 로직을 만들지 마세요.

이 결정에 대한 주요 제어 수단은 effort(노력 수준) 파라미터로, Claude가 얼마나 기꺼이 사고해야 하는지, 얼마나 깊이 사고해야 하는지에 대한 부드러운 지침 역할을 합니다. 각 수준이 무엇을 하는지는 이 페이지의 Effort 수준을 참조하세요.

Claude가 덜 자주 사고하기를 원한다면, 프롬프트 기반 조정을 사용하기 전에 먼저 effort 수준을 낮추세요.

사고는 또한 도구 사용과 자동으로 교차(interleave)됩니다. Claude는 도구 호출 사이에 사고하며, 다음에 무엇을 할지 결정하기 전에 각 도구 결과를 되돌아볼 수 있습니다(interleaved thinking(인터리브 사고)). 이를 위해 베타 헤더나 추가 구성이 필요하지 않습니다.

사고 구성과 effort 파라미터가 어떻게 상호작용하는지에 대한 전체 그림은 사고와 effort를 참조하세요.

Claude가 얼마나 자주 사고하는지 조정하기

Claude가 특정 턴에서 사고할지 여부는 프롬프트로 조정할 수 있습니다. Effort가 전반적인 태도를 설정하지만, 시스템 프롬프트에서 전역적으로 또는 사용자 턴에서 메시지별로 자연어 지침을 통해 그 결정을 직접 형성할 수도 있습니다.

두 가지 수단을 다음 순서로 함께 사용하세요:

1. 워크로드의 기본적인 품질과 지연 시간 균형에 맞는 effort 수준을 설정합니다.
2. 해당 수준에서 Claude의 사고 유발이 여전히 요구 사항에 맞지 않는 경우에만 프롬프트 지침을 추가합니다.

사고와 관련된 더 폭넓은 프롬프팅 지침은 사고 및 인터리브 사고 기능 활용하기를 참조하세요.

Effort 수준

Effort는 사고를 위한 주요 조정 수단입니다. 각 수준은 Claude가 얼마나 자주, 얼마나 깊이 사고하는지에 대해 서로 다른 기본값을 설정합니다:

이 표는 각 수준이 사고 동작을 어떻게 바꾸는지 설명합니다. 모델별 권장 사항을 포함하여 특정 워크로드에 어떤 수준을 선택할지에 대한 지침은 effort 페이지의 effort 파라미터를 조정해야 하는 경우를 참조하세요.

Effort는 thinking 객체 내부가 아니라 output_config.effort에서 설정합니다. 언어별 전체 예제는 Effort를 참조하세요.

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

수준 가용성은 모델에 따라 다릅니다. 각 모델이 어떤 수준을 지원하는지에 대해서는 effort 페이지의 effort 가용성 표가 기준입니다.

시스템 프롬프트 지침

시스템 프롬프트 지침은 대화의 모든 요청에 대해 Claude의 사고 임계값을 이동시킵니다. Claude가 워크로드에 필요한 것보다 더 자주 사고한다면, 시스템 프롬프트에 다음과 같은 지침을 추가하세요:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.

반대로 사고를 장려하려면 다음과 같은 문구를 사용하세요:

This task involves multistep reasoning. Think carefully before responding.

조정 효과는 정확한 문구에 민감할 수 있습니다. 한 가지 표현이 원하는 동작을 만들어내지 않는다면, 더 직접적인 변형을 시도해 보세요.

메시지별 조정

시스템 프롬프트와 독립적으로, 사용자 턴에서 메시지별로 사고를 조정할 수도 있습니다. 사용자 메시지에 "Please think hard before responding."을 덧붙이면 Claude가 해당 턴에서 사고하도록 장려하고, "Answer directly without deliberating."은 사고를 억제합니다.

메시지별 조정은 대화의 일부 요청만 확장된 추론을 필요로 할 때 유용합니다. 예를 들어 에이전트 하네스는 시스템 프롬프트를 건드리거나 턴 사이에 요청 파라미터를 변경하지 않고도, 계획 단계에는 장려 문구를, 일상적인 확인에는 억제 문구를 덧붙일 수 있습니다.

워크로드에서 조정 효과 검증하기

프롬프트 기반 조정은 모델 동작을 바꾸므로, 다른 프롬프트 변경과 마찬가지로 취급하세요. 즉, 배포하기 전에 측정하세요. 지침이 있는 경우와 없는 경우로 트래픽의 대표 샘플을 실행하고, 사고가 얼마나 자주 유발되는지(응답에 사고 블록이 있는지), 출력 토큰 사용량, 지연 시간, 그리고 중요한 사례에서의 답변 품질을 비교하세요.

메커니즘

Claude가 자신의 사고를 스스로 관리한다는 점에서 세 가지 메커니즘이 따라옵니다: 턴 검증, 프롬프트 캐싱, 그리고 비용을 제한하는 방법입니다.

턴 검증

어시스턴트 턴은 사고 블록으로 시작할 필요가 없습니다. (레거시 수동 사고 예산을 사용하는 모델은 사고가 활성화된 요청의 마지막 어시스턴트 턴이 사고 블록으로 시작하도록 강제합니다. 수동 모드의 턴 구조를 참조하세요.)

멀티턴 애플리케이션의 경우, 이는 대화 기록을 가지고 있는 형태 그대로 다시 전달할 수 있다는 뜻입니다:

• Claude가 사고하지 않기로 선택한 어시스턴트 턴은 그대로 유효한 기록입니다.
• 사고 없이 시작했거나 다른 사고 구성을 사용한 대화를 기록을 다시 작성하지 않고 재개할 수 있습니다.
• 여러 출처에서 조합된 기록은 검증을 통과하기 위해 각 어시스턴트 턴의 시작 부분에 사고 블록을 다시 삽입할 필요가 없습니다.

이 완화는 검증에 관한 것이지, 무엇을 보내야 하는지에 관한 것이 아닙니다. 사고 블록이 있다면 수정하지 않고 그대로 다시 전달하세요. 특히 도구 사용 중에는 사고 블록이 Claude의 도구 호출 뒤에 있는 추론을 담고 있으므로 더욱 그렇습니다. 전체 규칙은 사고 개요를 참조하세요.

프롬프트 캐싱

동일한 사고 구성과 effort 수준을 유지하는 연속 요청은 "prompt caching"(프롬프트 캐싱)을 보존합니다. 전체 규칙은 사고와 프롬프트 캐싱을 참조하세요. 확정된 effort 값은 프롬프트에 렌더링되므로, 요청 사이에 이를 변경하면 캐시 브레이크포인트가 무효화됩니다. 이는 레거시 budget_tokens 파라미터를 사용하는 모델에서 해당 파라미터를 변경할 때와 마찬가지입니다. effort를 모델의 기본값으로 명시적으로 설정하는 것은 생략하는 것과 동일하며 캐시를 깨뜨리지 않습니다.

실질적인 결론: 대화마다 사고 구성과 effort 수준을 하나 정하고 유지하세요. 일부 턴에 더 많거나 적은 사고가 필요하다면 메시지별 프롬프팅으로 조정하세요. 가장 최근 사용자 메시지에 덧붙인 지침은 이전 캐시 브레이크포인트를 그대로 유지하지만, 구성이나 effort 변경은 그렇지 않습니다.

다음 예제는 직접 실행해 볼 수 있는 멀티턴 스크립트로 무효화를 보여줍니다:

import requests

client = Anthropic()


def fetch_article_content(url):
    text = requests.get(url).text
    lines = (line.strip() for line in text.splitlines())
    return "\n".join(line for line in lines if line)


# 문서의 내용을 가져옵니다
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# 캐싱에 충분한 만큼의 텍스트만 사용합니다 (처음 몇 개 챕터)
LARGE_TEXT = book_content[:10000]

# 시스템 프롬프트 없음 - 대신 메시지에서 캐싱합니다
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Analyze the tone of this passage."},
        ],
    }
]

# 첫 번째 요청 - 캐시를 생성합니다
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})

# 두 번째 요청 - 동일한 구성 (캐시 히트 예상)
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})

# 세 번째 요청 - 다른 effort 수준 (캐시 미스 예상)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=MESSAGES,
)

print(f"Third response usage: {response3.usage}")

First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }

Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }

Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }

비용 제어

사고 토큰 예산은 설정하지 않습니다. 두 가지 제어 수단이 비용을 제한합니다:

• max_tokens는 사고와 응답 텍스트를 합친 요청의 총 출력에 대한 하드 캡입니다. Claude는 절대 이를 넘어서 생성하지 않습니다. 도구 사용 루프에서는 턴 내의 각 요청이 자체 max_tokens를 가지므로, 전체 턴의 지출을 제한하지는 않습니다.
• effort는 Claude가 그 출력 중 얼마를 사고에 할당할지에 대한 부드러운 지침입니다. 동작을 형성하지만 토큰 수를 보장하지는 않습니다.

사고는 max_tokens에 포함되므로, 추론과 답변 모두를 위한 여유가 남도록 충분히 높게 설정하세요. 사고가 없는 응답에 맞춰 크기를 정한 max_tokens는 Claude가 어려운 요청에서 사고하기 시작하면 너무 작은 경우가 많습니다.

high effort 이상에서는 Claude가 광범위하게 사고할 수 있으며 예산을 소진할 가능성이 더 높습니다. 응답에서 stop_reason: "max_tokens"가 보인다면 두 가지 해결책이 있습니다:

• max_tokens를 높여 모델에 사고와 답변을 위한 더 많은 여유를 줍니다.
• effort 수준을 낮춰 Claude가 덜 사고하고 예산의 더 많은 부분을 응답 텍스트에 남기도록 합니다.

어느 쪽이 맞는지는 잘린 응답에 추론이 필요했는지에 달려 있습니다. 해당 요청의 품질이 중요하다면 캡을 높이고, 과도하게 사고한 것이었다면 effort를 낮추세요.

가격 책정

사고에는 다음에 대한 요금이 발생합니다:

• Claude가 사고하는 동안 사용하는 토큰(출력 토큰으로 청구)
• 보존 기본값에 따라 컨텍스트에 남아 있는 이전 어시스턴트 턴의 사고 블록: keep-all 모델에서는 기본적으로 모든 턴, 그 외에는 마지막 턴만(입력 토큰으로 청구)
• 표준 텍스트 출력 토큰

청구되는 내용은 display 설정과 관계없이 동일하며, 보이는 것만 달라집니다:

내부 추론에 청구된 출력 토큰이 얼마나 사용되었는지 확인하려면 응답의 usage.output_tokens_details.thinking_tokens를 읽으세요. 이 값은 모델이 생성한 원시 추론을 반영하며(본문에 반환된 요약 텍스트가 아님), 항상 output_tokens보다 작거나 같습니다. 이를 output_tokens에서 빼면 출력의 비추론 부분을 근사할 수 있습니다. 스트리밍 시 이 세부 내역은 마지막 message_delta 이벤트에만 나타납니다.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens는 여전히 청구에 사용되는 포괄적이고 권위 있는 총계입니다. output_tokens_details는 관측 가능성을 위한 읽기 전용 세부 내역입니다. 기본 요금, 캐시 쓰기, 캐시 히트, 출력 토큰을 포함한 전체 가격 정보는 가격 책정을 참조하세요.

다음 단계