설정 파일은 단 한 글자도 바꾸지 않았습니다. 그럼에도 이 글을 쓰고 있는 세션은 Opus 5로 동작하고 있었습니다.

{
"model": "opus[1m]"
}

opus[1m]은 모델명이 아니라 **에일리어스 (Alias, 별칭)**입니다. "Opus 계열의 최신 버전을 100만 토큰 컨텍스트로 사용한다"는 지정이며, 버전은 명시하지 않았습니다. Claude Code를 v2.1.219로 올린 시점에서, 이 opus가 가리키는 대상은 Opus 4.8에서 Opus 5로 바뀌었습니다.

Before v2.1.219,

opus resolved to Opus 4.8 on the Anthropic API from v2.1.154

(v2.1.219 이전에는 Anthropic API 상에서 opus는 Opus 4.8을 가리키고 있었습니다)

에일리어스로 지정하고 있는 사람은 스스로 아무것도 하지 않아도 모델이 교체됩니다.

이 글은 "Opus 5가 무엇이 대단한가"가 아니라, 이미 교체된 후에 무엇을 수정해야 하는가만을 다룹니다. 수정해야 할 것은 3가지입니다.

출력 상한 설정 — 아무것도 지정하지 않으면 "생각한 뒤에 답변하기"로 변경됨
지금까지 추가해 온 지시사항 — 공식에서 직접 "삭제하라"고 명시한 것이 있음
effort 설정 — "다시 측정하라"고 권고받고 있음에도, Claude Code는 자동으로 이를 계승함

이 중 2번째가 프롬프트 본체에 관한 이야기이며, 1번과 3번은 그 주변 설정에 관한 이야기입니다.

긴 글이므로, 먼저 이 글에서 실제로 측정한 결과를 나열해 두겠습니다. 관심 있는 행의 장(Chapter)만 읽어도 이해할 수 있도록 작성했습니다.

차례대로 살펴보겠습니다.

• 대상: Claude Code 또는 Claude API를 일상적으로 사용하는 사람
• 전제 지식: 프롬프트를 작성해 본 적이 있음. API 파라미터 이름은 몰라도 읽을 수 있음
• 검증 시점: 2026-07-25 아침 (수치는 모두 이 시점의 것. 이유는 4장에서 설명합니다)
• 정보원: 공식 문서를 9페이지까지 정독한 후, 망가지는 방식을 API로 실제로 재현했습니다 (400 에러, max_tokens에 의한 중단, 캐시 무효화). 모델 간 수치 비교에는 제3자 벤치마크(Artificial Analysis)의 측정값을 사용했습니다. 직접 측정하지 않은 부분은 본문에서 그때마다 밝힙니다.

1. 아무것도 지정하지 않으면, 생각한 뒤에 답변하게 되었다

무엇이 바뀌었나

Opus 4.8에서는 요청에 thinking 지정이 없으면 모델은 생각하지 않고 바로 답변했습니다. Opus 5는 다릅니다.

On Claude Opus 4.8, requests without a thinking field run without thinking; on Claude Opus 5, the same requests run with adaptive thinking. max_tokens remains a hard limit on total output, thinking plus response text, so revisit it for workloads that ran without thinking on Claude Opus 4.8.

(Opus 4.8에서는 thinking...

필드가 없는 요청은 사고(thinking) 없이 실행되지만, Opus 5에서는 동일한 요청이 적응형 사고(adaptive thinking)로 실행됩니다. max_tokens는 사고와 답변 텍스트를 합친 총 출력에 대한 상한선인 상태이므로, Opus 4.8에서 사고 없이 동작시키던 처리 방식은 재검토가 필요합니다.

읽어야 할 부분은 두 번째 문장입니다. max_tokens는 "답변의 길이 상한"이 아니라, 사고와 답변을 합친 합계의 상한입니다. 이 부분은 이전부터 사양(specification)으로서 변하지 않았습니다. 변한 점은, 지금까지 0이었던 사고 분량이 갑자기 상한선을 차지하기 시작했다는 것입니다.

예를 들어 max_tokens: 4096으로 분류 태스크(classification task)를 돌리고 있었다면, 이전에는 4096 토큰 전체를 답변에 사용할 수 있었습니다. Opus 5에서는 그중 일부를 사고가 먼저 사용합니다. 답변이 중간에 끊기는 이유는 바로 이것 때문입니다.

이는 실제로 재현되었습니다. max_tokens: 2000 및 thinking 지정 없음이라는, Opus 4.8 시대의 흔한 설정 그대로 모델명만 교체했습니다.

동일한 요청입니다. Opus 4.8은 682 토큰으로 말을 마쳤는데, Opus 5는 상한인 2,000을 다 써버리고 중간에 끊겼습니다. 중지 이유가 end_turn(말을 마침)에서 max_tokens(상한에 의해 멈춤)로 바뀐 것이 결정적이며, 이는 애플리케이션 측면에서 보면 "답변이 뒷부분이 잘린 채로 돌아오는" 방식으로 고장 나는 것입니다.

400 에러가 발생하는 조합

사고를 끄는 것은 지금도 가능합니다. 다만 조건이 붙었습니다.

thinking: {type: "disabled"}를 사용하여 여전히 사고를 끌 수 있지만, effort 레벨이 high 이하인 경우에만 가능합니다. thinking: {type: "disabled"}와 effort xhigh 또는 max를 조합한 요청은 400 에러를 반환합니다.

(You can still turn thinking off with thinking: {type: "disabled"}, but only at an effort level of high or below. A request that combines thinking: {type: "disabled"} with effort xhigh or max returns a 400 error.)

Opus 4.8에서는 통과되었던 다음 코드는 모델명을 교체하면 에러가 발생합니다.

# Opus 4.8에서는 통과 / Opus 5에서는 400 에러
client.messages.create(
    model="claude-opus-5",
    ...
)

실제로 요청을 보내면 다음과 같이 반환됩니다.

HTTP 400 invalid_request_error
output_config.effort 'xhigh' is not supported when thinking is disabled
on this model. Use effort 'high' or below, or enable thinking.

세 가지 조건으로 확인한 결과입니다. 공식 기술 문서의 내용대로 결과가 나왔습니다.

해결 방법은 두 가지입니다. 사고를 다시 켜거나, effort를 낮추는 것입니다.

# 해결책 A: 사고를 다시 켬 (Opus 5는 기본값이 On이므로 thinking을 작성하지 않음)
client.messages.create(
    model="claude-opus-5",
    ...
)

이 검증은 요청마다 독립적으로 수행됩니다. 대화 도중에 effort를 높이는 순간 에러가 발생하는 방식으로 고장 납니다.

사고를 끄는 방식은 권장되지 않음

또한 공식은 사고(thinking)를 끄는 것보다 effort를 낮추는 것을 권장하고 있습니다. 사고를 꺼버리면 가시적인 출력물에 두 종류의 쓰레기(garbage)가 섞일 수 있기 때문입니다.

도구 호출(tool call)이 문장으로 새어 나옴— 구조화된 tool_use 블록이 아니라, 사용자용 텍스트 안에 도구 호출이 작성되어 버립니다. 단순히 작성만 된 것이기에 해당 도구는 실행되지 않습니다. 게다가 에이전트적인 루프에서는 새어 나온 텍스트가 대화 기록에 남아 이후의 턴에도 영향을 미칩니다.

내부 태그가 출력에 나타남— <thinking> 등의 태그가 답변 중에 나타납니다. 이에 대한 대책으로 시스템 프롬프트에 "생각하지 마라", "추론하지 마라"라고 적는 것은 역효과를 불러오며, 공식은 "그런 규칙이 있다면 삭제하라"고 말합니다.

둘 다 "가끔 발생하는" 수준의 문제이지만, 도구 호출이 실행되지 않고 그냥 지나쳐 버리는 경우는 성공한 것처럼 보이면서 처리가 누락되기 때문에 더 까다롭습니다.

할 일: max_tokens를 재검토할 것. xhigh / max를 사용한다면 64k 이상이 공식적인 출발점입니다. 사고를 꺼서 회피하는 것은 최후의 수단으로 남겨두세요.

2. 지금까지 추가해 온 지시사항이 역효과를 냈다

이 부분이 이번 내용 중 실무에 가장 유용합니다. 프롬프트 개선은 보통 "추가하는" 방향으로 논의되지만, Opus 5에서 필요한 것은 빼는 방향입니다.

공식이 직접적으로 "삭제하라"고 명시한 것들

If your prompt contains explicit verification instructions ("include a final verification step for any non-trivial task," "use a subagent to verify"), remove them: instructions like these cause over-verification on Claude Opus 5, and removing them reduces wasted tokens with no loss in quality.

(프롬프트에 명시적인 검증 지시("자명하지 않은 작업에는 마지막에 검증 단계를 포함할 것", "서브 에이전트를 사용하여 검증할 것")가 포함되어 있다면 삭제하십시오. 이러한 지시사항은 Claude Opus 5에서 과잉 검증(over-verification)을 유발하며, 이를 삭제하면 품질 저하 없이 낭비되는 토큰을 줄일 수 있습니다.)

Avoid instructing re-checks it already performs ("double-check your answer," "re-verify before responding")

(모델이 이미 수행하고 있는 재확인을 지시하지 마십시오 ("답변을 더블 체크하세요", "응답 전에 재검증하세요").)

정리하자면, 삭제 대상은 다음과 같습니다.

이유는 공통적입니다. Opus 5는 말하지 않아도 스스로 검증하고 자신의 실수를 바로잡기 때문입니다. 거기에 지시를 겹치면 같은 작업을 두 번 하게 만드는 셈입니다.

사내 공통 프롬프트나 에이전트의 기반 구조(공식은 "legacy harness scaffolding"이라고 부릅니다)에 이러한 지시가 쌓여 있는 조직이 많을 것입니다. Opus 5로 전환한다면, 우선 그 부분을 깎아내는 작업부터 시작해야 합니다.

실제로 측정해 보니 출력이 2.3배 증가했다

공식이 그렇게 말하는 것만으로는 움직이기 어려우므로, 직접 측정해 보았습니다.

세 가지 작업(문장을 3줄로 요약 / 회의록에서 결정 사항과 할 일 추출 / CSV를 JSON으로 변환)을 다음 두 가지 조건으로 각각 3회씩 실행했습니다.

순수 상태 (Raw): 작업 내용만 전달

검증 지시 포함: 작업 내용 뒤에 "자명하지 않은 작업에 대해서는 마지막에 검증 단계를 넣어주세요. 답을 더블 체크하고, 응답 전에 재확인해 주세요"를 추가

조건은 claude-opus-5 / effort high / 2026-07-25 08:24 실행입니다.

3개 태스크 모두 증가했습니다. 소요 시간도 약 2배입니다 (요약: 3.8초 → 10.5초).

그렇다면, 2.3배의 비용을 들여 품질이 올라갔는가. 이 부분이 핵심이기에 결과물을 대조해 보았습니다.

CSV → JSON 변환은 정답이 유일하게 결정되는 태스크입니다 (카테고리 A = 15, B = 12). 결과는 6회 모두 정답이었습니다. 검증 지시가 포함된 회차는, 그곳에 10 + 3 + 2 = 15라는 검산 내역이 추가되었을 뿐, 결과물 자체는 동일했습니다.

요약 태스크는 실물을 나란히 놓고 보는 편이 빠릅니다.

있는 그대로 (165자)

- 기존에는 모든 카테고리 일괄적으로 재고가 100개 미만일 때 발주했으나, 리드 타임 (Lead Time)이
3~9영업일로 차이가 있어 장납기 품목의 결품이 빈번했다.
- 새로운 방식에서는 카테고리별 리드 타임과 평균 출하량을 바탕으로 발주점을 산출한다.
...

검증 지시 포함 (715자)

## 요약 (3줄)
1. 재고 관리 시스템 쇄신에 따라 발주점을 재검토했다. 기존에는 모든 카테고리 일괄적으로 재고가 100개
미만일 때 발주했었다.
...

요약의 내용은 둘 다 원문의 3요소(기존 방식의 문제점·새로운 방식·결산월의 과제)를 정확하게 짚고 있습니다. 증가한 550자는 전부 「자신의 답을 검증한 보고」입니다.

3줄 요약을 요청했는데, 요약의 3배 분량에 달하는 검증 리포트가 따라옵니다. 게다가 독자가 알고 싶은 것은 요약이지, 모델이 자신의 답을 어떻게 점검했는가가 아닙니다.

출력 단가 $25 / 100만 토큰 (Token)으로 환산하면, 1 요청당 약 460 토큰이 추가되는 셈입니다. 하루에 100번 구동한다면, 한 달에 약 $35 정도를 검증 리포트에 지불하고 있는 것이 됩니다.

(측정하지 않은 점: 「품질이 동등한가」는 정답이 유일한 태스크에서의 정오 일치와 요약 내용 대조를 통해 판단했습니다. 어려운 추론 태스크에서 검증 지시가 효과를 발휘하는 장면이 없다고까지는 말할 수 없습니다.)

리뷰 용도의 함정

또 하나, 코드 리뷰에 사용하고 있는 분들은 주의해야 합니다.

If your review prompt says "only report high-severity issues" or "be conservative," the model may follow that instruction literally and report less; ask it to report everything and filter in a separate pass instead.

(리뷰용 프롬프트에 「중대한 문제만 보고해」 또는 「보수적으로 판단해」라고 적혀 있으면, 모델은 그 지시를 문자 그대로 따라 보고를 줄일 수 있다. 대신, 모든 것을 보고하게 한 뒤 별도의 패스 (Pass)에서 필터링할 것)

「중대한 문제만 보고해」는 노이즈를 줄이기 위해 누구나 쓰는 지시입니다. 이것이 Opus 5에서는 문자 그대로 적용되어, 포착했어야 할 문제까지 보고되지 않게 됩니다. 지시에 따르고 있는 것이므로, 모델 입장에서는 올바른 동작입니다.

대처법은 필터링을 공정(Process)으로 분리하는 것입니다. 1단계(1st Pass)에서 전부 출력하게 하고, 2단계(2nd Pass)에서 압축하는 방식입니다. 공식 문서에서 「Opus 5는 리뷰의 정밀도와 재현율이 높고, 낮은 노력(Effort)으로도 정밀도가 유지된다」고 설명하고 있으므로, 1단계를 저렴하고 빠르게 돌리고 압축 단계를 별도로 두는 구성과 궁합이 잘 맞을 것입니다.

(이 절에 대해서만은 실측하지 않았습니다. 전 절의 토큰 비교와 달리 검출 수의 비교는 수행하지 않았으므로, 공식의 기술로서 읽어주시기 바랍니다.)

반대로, 추가해야 할 지시

깎아내는 것뿐만 아니라, Opus 5에서 새롭게 필요해지는 지시도 있습니다. 공식에서 언급한 것은 주로 3가지입니다.

답변이 길어졌으므로, 간결함을 명시적으로 지시할 것

Keep responses focused, brief, and concise. Keep disclaimers and caveats short,
and spend most of the response on the main answer. When asked to explain something,
give a high-level summary unless an in-depth explanation is specifically requested.

태스크의 범위를 멋대로 넓히는 경우가 있으므로, 좁은 태스크에서는 범위를 고정할 것

Opus 5는 요청하지 않은 절차를 추가하거나, "본래 이래야 한다"는 자신의 판단을 적용하는 경우가 있습니다. 범위를 한정하고 싶다면 그렇게 명시해야 합니다.

서브 에이전트 (Sub-agent)의 과도한 사용을 중단할 것

위임이 쉬워진 만큼, 아주 작은 태스크에까지 사용하게 되어 비용과 시간을 늘립니다. 공식 가이드에서는 "정말로 독립적이고 큰 작업에만 위임할 것", "자신의 작업을 검증하는 데 서브 에이전트를 사용하지 말 것"이라고 명시적으로 작성할 것을 권장하고 있습니다.

할 일: 프롬프트에서 "검증하라" 계열의 4가지를 삭제할 것. 리뷰용 "중요한 것만" 남기고, 필터링은 별도 공정으로 분리할 것.

3. effort 설정은 이전 모델로부터 멋대로 상속된다

effort란 무엇인가

effort는 "모델이 얼마나 많은 토큰을 사용하여 생각할지"를 5단계(low / medium / high / xhigh / max)로 지정하는 파라미터입니다. 기본값은 high입니다. 지정하지 않는 것과 high를 지정하는 것은 동일하게 동작합니다.

Opus 5에서는 이 5단계의 의미가 바뀌었습니다.

low and medium effort are stronger on Claude Opus 5 than on earlier Opus models: use them liberally as your primary control for token cost and response time wherever your evals show quality holds

(low와 medium effort는 이전의 Opus 모델보다 Opus 5에서 더 강력합니다. 평가(evals)를 통해 품질이 유지됨을 확인했다면, 토큰 비용과 응답 시간을 제어하는 주요 수단으로서 이를 적극적으로 활용하십시오.)

그리고 이어서 다음과 같이 적혀 있습니다.

If you carried effort settings over from an earlier model, run a fresh effort sweep on your evals rather than reusing them.

(이전 모델에서 effort 설정을 가져왔다면, 기존 설정을 재사용하지 말고 자신의 평가 세트에서 effort를 새로 측정(sweep)하십시오.)

그런데 Claude Code는 Opus 5만 설정을 상속한다

이 부분이 서로 맞지 않습니다. Claude Code의 문서에는 다음과 같이 적혀 있습니다.

When you first run Fable 5, Opus 4.8, or Opus 4.7, Claude Code applies that model's default effort even if you previously set a different level for another model, and holds it across sessions until you make an explicit effort choice.

Opus 5 has no such hold: a level you previously set carries over.

(Fable 5, Opus 4.8, 또는 Opus 4.7을 처음 실행할 때, Claude Code는 이전에 다른 모델에 대해 다른 레벨을 설정했더라도 해당 모델의 기본 effort를 적용하며, 사용자가 명시적으로 선택할 때까지 세션을 넘어서 이를 유지합니다. Opus 5에는 이러한 유지 기능이 없습니다. 즉, 이전에 설정한 레벨이 그대로 이어집니다.)

다른 모델은 "이전 설정을 무시하고 기본값으로 돌아가는" 반면, Opus 5만은 이전 설정을 그대로 가져옵니다. 공식 문서의 다른 페이지에서는 "가져오지 말고 다시 측정하라"고 말하는 바로 그 모델이, Claude Code에서는 유일하게 자동으로 가져오는 쪽이 되어 있습니다.

즉, Opus 5로 업그레이드한 사람의 설정에는 이전 모델용으로 결정했던 값이 다시 선택할 기회도 없이 남아 있을 가능성이 있습니다. 의도적으로 다시 설정한 기억이 없다면, /effort 명령어로 한 번 다시 설정하는 것이 안전합니다. 특히 코딩이나 에이전트 용도로는 xhigh를 시작점으로 사용하는 것이 공식 권장 사항이므로, high 상태로 두면 권장 사항보다 한 단계 낮은 상태로 계속 사용하게 됩니다.

5단계를 실제로 측정해 보았다

공식 가이드에는 다음과 같이 적혀 있습니다.

Effort는 사고량 (thinking volume)을 제어하는 것이지, 눈에 보이는 답변 길이 (visible response length)를 제어하는 것이 아닙니다: Claude Opus 5에서는 effort를 변경해도 답변 길이가 안정적으로 짧아지지 않으므로, 대신 프롬프트로 길이를 지정하십시오.

(effort는 사고량을 제어하는 것이며, 눈에 보이는 답변의 길이가 아니다. Opus 5에서는 effort를 바꿔도 답변이 확실히 짧아지는 것은 아니므로, 길이는 프롬프트로 지정할 것)

"답변이 길어서 effort를 낮춘다"는 방식은 통하지 않는다는 취지입니다. 그런데 실제로 측정해 보니, 답변의 길이도 함께 움직였습니다.

동일한 질문(재고 관리 시스템 이관 시 주의해야 할 점 정리)을 5단계로 각 3회씩, max_tokens: 16000으로 실행한 결과입니다 (claude-opus-5, 2026-07-25 08:33).

표의 2열과 3열을 나누어 놓은 이유를 먼저 적어둡니다. 출력 토큰 (output tokens)은 "사고(thinking) + 답변(response)"의 합계이며, 비용은 이 기준으로 결정됩니다. 답변의 글자 수는 화면에 실제로 표시된 문장의 길이입니다. 사고 부분은 과금되지만, 독자의 눈에는 보이지 않습니다.

low에서 max로 갈 때, 출력 토큰은 +147%, 화면에 표시된 답변 글자 수는 +73% 증가했습니다.

주목해야 할 점은 이 두 증가율의 차이입니다. 출력 토큰이 거의 두 배 가까이 늘어났습니다. 즉, 그 차이분은 사고에 사용되었다는 뜻입니다. 일본어는 대체로 1글자당 1토큰이므로 개략적인 수치이지만, 사고에 할당된 토큰은 low에서 200 내외, max에서 1,900 내외로 추정됩니다. 8배 이상의 차이입니다.

"effort의 영향은 주로 사고에 미친다"는 공식 가이드의 설명은 이 데이터와도 일치합니다. 다만 이 태스크에서는 화면에 나오는 답변의 길이도 함께 움직였습니다. effort를 높이면 늘어나고, 낮추면 짧아지는 관계가 나타난 것입니다. 공식이 "확실하게 짧아지지는 않는다 (does not reliably shorten)"라고 명시한 대로, 짧아질지 여부는 보장되지 않는다고 읽는 것이 정확합니다. 길이를 확실하게 제어하고 싶다면 프롬프트로 지정한다는 결론 자체는 변하지 않습니다.

또 하나, 실무적으로 유효한 발견이 있었습니다. low와 medium이 거의 비슷합니다 (2,142 대 2,350 토큰, 1,944 대 1,961 글자, 45.3 대 46.8 초). 이 태스크에 한해서는 medium을 선택할 이유가 보이지 않습니다. 비용을 낮추는 목적으로 단계를 낮춘다면, medium에서 멈추지 말고 low까지 낮추는 것이 더 효과적입니다. (1개 태스크에 대해 각 3회 측정한 결과입니다. 태스크의 성격에 따라 경향은 달라질 수 있습니다. 공식이 "자신의 평가 세트에서 effort를 다시 조정하라"고 말하는 이유가 바로 이것입니다.)

대화 도중에 변경하면 캐시가 깨집니다

Because effort shapes the rendered prompt, changing it between requests does not preserve cached prefixes from earlier turns; if you rely on prompt caching across a long session, pick an effort level at the start and keep it constant.

(effort는 프롬프트 구성에 영향을 미치기 때문에, 요청(request) 사이에 이를 변경하면 이전 턴의 캐시된 프리픽스(cached prefixes)가 유지되지 않는다. 긴 세션 동안 프롬프트 캐싱 (prompt caching)에 의존한다면, 처음에 effort를 결정하고 일정하게 유지하라)

프롬프트 캐싱 (prompt caching)은 동일한 서문 (시스템 프롬프트 (system prompt)나 긴 자료)을 반복해서 보낼 때 비용을 낮춰주는 메커니즘입니다. effort를 도중에 변경하면 해당 캐시가 작동하지 않게 됩니다.

이 부분은 실제로 측정해 보았습니다. 7,521 토큰의 서문을 캐싱한 상태에서 4회 연속으로 요청을 보냈으며, 도중에 effort를 high에서 medium으로 변경했습니다 (2026-07-25 08:12 실행, claude-opus-5).

3회차에서 캐시가 완전히 재생성되었습니다. 내용도 전송 내용도 단 한 글자도 바꾸지 않았으며, 바꾼 것은 effort 값뿐입니다.

이것이 비용에 어떤 영향을 미치냐면, 캐시 읽기는 일반 입력 비용의 0.1배, 쓰기는 1.25배입니다. 즉, effort를 한 번 바꿀 때마다 동일한 서문에 대해 12.5배의 비용을 지불하게 됩니다. 7,521 토큰이라면 1회당 몇 원 정도겠지만, 서문이 수만 토큰에 달하는 긴 세션에서 여러 번 전환한다면 무시할 수 없는 금액이 됩니다.

변경할 것이라면 대화 시작 시점에 결정하고 고정하라. 도중에 기분에 따라 올리고 내리는 것이 가장 손해입니다.