Prompting Claude Sonnet 5.5

原典: Prompting Claude Sonnet 5.5 ／ 日本語版

一行要約

Sonnet 5 の prompt はそのまま動くが、effort のレベルが較正し直されたので sweep をやり直す。低い effort では途中で確認しに来たり検証を飛ばしたりし、高い effort では頼んでいない追加や自前のレビューに走る —— どちらも system prompt の一文で寄せられる。

要点

出発点

Existing Claude Sonnet 5 prompts should perform well without changes, and the patterns in Prompting Claude Sonnet 5 remain a reasonable starting point. For the hardest long-horizon work, an Opus model is the better choice.

既存の Claude Sonnet 5 の prompt は変えずによく動くはずで、Prompting Claude Sonnet 5 のパターンも出発点として妥当である。最も難しい長時間の作業には、Opus のモデルのほうが良い選択である。

effort を較正する

Its levels are recalibrated: a level doesn’t produce the same amount of thinking as the same level on Claude Sonnet 5. Run a fresh sweep against your own evals rather than carrying over the setting you used on Claude Sonnet 5.

レベルは較正し直されている。同じレベルでも、Claude Sonnet 5 の同じレベルと同じ量の thinking にはならない。 Claude Sonnet 5 で使った設定を持ち越さず、自分の eval で sweep をやり直せ。

用途	出発点
既定	high（Claude API の既定）
agentic coding・多段のツール使用	仕様のはっきりしたタスクは medium、難しい・長いものは high
チャットなど遅延に敏感なもの	medium か low（高いほど返答が始まるまで待たせる）

• max_tokens は thinking と返答の両方の分を取る（thinking の中身が返らなくても数えられる）。agentic coding では最大の 128,000 にしてストリーミング
• xhigh / max は品質の向上を測れた作業にだけ。そこでは between_tools を受け付けない
• 思考を減らしたいなら effort を下げる。medium 以上では挨拶にさえ短く考える。system prompt で「考えるな」と頼んでも確実には減らない。low なら単純な依頼の多くで考えない
• top-level の effort をリクエスト間で変えると prompt cache が壊れる。ターン単位で変えるならメッセージごとの effort 変更（beta。adaptive thinking が要る）

自発性と範囲を寄せる

• 低い effort（low / medium）の agentic coding では、終わる前に確認しに来る（計画の確認、自分で答えられる質問、複数部分の途中で続けるかを聞く）。まず effort を上げる。上げずに続けさせるなら下の system prompt の1段落目。ただし長く走ってコストが増え、危険・不可逆な操作についての自分の規則の代わりにはならない
• 頼んでいないテスト・ドキュメント・小さな補助ファイルを、リポジトリの流儀に合わせて足す —— どの effort でも、高いほど多い（変更そのものは頼んだ範囲に留まる）。頼んだものだけにしたいなら2段落目だけを足す
• xhigh / max では、終わった後に自前のレビューと検証の周回に入る（harness があれば subagent も使う）。下の一文で、max の coding タスクで reviewer subagent の起動が止まり、セッションのコストが約3分の1下がり、品質は変わらなかった（試験での結果）
• 「何ができるか見せて」のような開かれた依頼では、アイデアだけ欲しいのにプレゼン・レポート・動画を作り始めることがある

事前の thinking なしで走らせる（between_tools）

Sonnet 5.5 で事前の thinking を切るのは thinking: {"type": "between_tools"}（最も低い thinking 設定。high 以下でだけ受け付ける）。今 thinking オフで動かしているなら切り替えて確かめる:

• xhigh / max との組み合わせは 400。メッセージごとの effort がその時点のレベルと違っても 400 —— ターンごとに変えるなら adaptive
• 「考えるな」という指示は消す —— 内部の XML タグが可視出力に漏れやすくなる
• ブロックの型で読む —— 応答は進捗更新の thinking ブロックで始まりうる。最初のブロックがテキストだと仮定しない
• thinking ブロックはそのまま返す —— 送り返したブロックは、要約ではなく書いたノートの全文を model に渡す
• ツールの無い推論タスクには adaptive を使う —— ツールが無いと between_tools は考えずに答える

推論が要るタスクで JSON を返させる

合計、規則の適用、順位付けのように数段の検討が要るタスクで JSON を求めると、特に low / medium では考えずに答えがち。structured outputs では応答は JSON だけなので、考える場所は thinking しかない。

• adaptive で、system prompt の最後に Think the problem through before you answer. —— high ならほぼ xhigh の精度に、出力トークンは少し増えるだけ
• または xhigh（この一文無しでも最高精度。出力は high より多い）
• between_tools ではなく adaptive（ツール無しの between_tools ではこの一文も効かない）
• stop_reason が "max_tokens" の応答は、JSON として正しくても失敗として扱い再試行する（low / medium の structured outputs では、たまに max_tokens まで考え続ける）
• structured outputs が使えないなら、応答の最後の JSON 値を取る —— 最初の { から最後の } までを取らない（最終 JSON の前に下書きを書くことがあり、両方を含んでしまう）。試験では、これでほぼすべての応答が使えるようになった

ユーザー向けの進捗更新

ツール呼び出しの合間のノートのうち、1〜2文より長いものは進捗更新の thinking ブロックとして返り、既定の display では本文が空。text だけを描くクライアントは長いターンの間黙って見える。

• 見せるなら display: "updates"（beta、thinking-display-updates-2026-08-18）。between_tools なら display 無しで要約テキストが付く（between_tools に display / budget_tokens / block_binding を付けると 400）
• 途中で正確な文（コード片や答えが要る質問）を見せる必要があるなら、ユーザーにメッセージを送る簡単なツールを渡し、それ専用に使うよう指示する。セッションの最初のリクエストで宣言する（tools を後で変えない）
• 「所見は最後の応答まで溜めよ」のような古い指示は消す
• それでも静かすぎるなら、harness が、ユーザーに何も送らないツール呼び出しの連続を数え、たとえば5回続いたら turn-scoped の system message で1回だけ促す（下記）。2〜3回で打ち切る —— ツール結果の後に harness の文が頻繁に来ると、prompt injection を疑わせる。促しは後のリクエストでも messages に残す（足すだけで後から消さないので、cache と preserved thinking が保たれる）

チャットと知識作業でのツール使用

検索すれば変わった細部（何が許されるか、要るか、いくらか）を拾えるのに、学習した知識で答えることがある。 まず「ツールは本当に必要なときだけ」「ツール呼び出しを最小に」のようなツールを抑える言い回しを消し、検索ツールがあるなら下の一文を足す。

ターン途中のユーザーメッセージ

Claude Sonnet 5.5 is trained to resist indirect prompt injection, meaning malicious instructions that arrive through tool results and other content it reads during a task. Sometimes it treats a genuine user message as a possible injection.

Claude Sonnet 5.5 は、ツール結果などタスク中に読む内容を通って届く悪意ある指示（間接 prompt injection）に抵抗するよう訓練されている。そのため、本物のユーザーメッセージを injection の疑いとして扱うことがある。

ツール結果の直後に置いた会話途中の system message や、tool_result の中に入れたユーザーの文が誤読される。毎回のツール結果の後に足すトークンのカウントダウンや、ステップごとの指示も同じ原因になる。

• ユーザーの文を tool_result の中に入れない（最も誤読されやすい）
• ターン途中のユーザー入力はユーザーターンとして、tool_result を運ぶ user メッセージの中で、最後の tool_result の後に text ブロックで足す
• harness の通知は、ユーザーの文の後に別の会話途中の system message で。同じブロックに混ぜない
• ユーザーが途中で打てる対話セッションでは、自前のトークン・予算のカウントダウンをツール結果の後に足さない（task budgets ではこの誤読は見られていない）

coding での検証

low では、変更を検証せずに完了と報告することがある（依存が入っていないのでテストを飛ばす、など）。transcript にテストやビルドの出力が無いまま完了報告が出るなら、下の段落を足す —— low で、飛ばしや表面的な検査がまれになり、品質は変わらず、コストはわずかに上がるだけだった。

その他

• ツール名の大文字小文字違い（bash と Bash）や、少し違う名前の引数で呼ぶことがある —— 曖昧さが無ければ受け付けるか、正しい名前を書いた is_error: true の tool_result を返す（次のターンでたいてい直す）
• 密なグラフや技術図面には、切り抜き・拡大・コード実行のツールを渡す —— グラフではツールのほうが effort を上げるより効く（ツールありの high が、ツールなしの max より正確で、コストは何分の1）。技術図面では high 以上でだけ効く
• 安全分類器による拒否（stop_reason: "refusal"、stop_details.category）は cyber / bio / frontier_llm / reasoning_extraction / general_harms。サーバ側フォールバック（beta）は cyber と frontier_llm だけを Sonnet 5 で再試行し、bio / reasoning_extraction / general_harms は再試行しない。推論を応答に含めさせる指示は消す（要約された thinking を読む。答えの短い説明や行動の要約なら頼んでよい）

そのまま使える具体例

途中で確認しに来させず最後まで進めさせる（1段落目）／頼んだものだけにする（2段落目だけ）:

Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step.
 
When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.

xhigh / max の自前レビューを止める:

When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.

開かれた依頼で勝手に作り始めさせない:

When the user asks for ideas, options or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.

推論の要る JSON タスク（adaptive で system prompt の最後に）:

Think the problem through before you answer.

長く黙っているときの1回限りの促し（turn-scoped system message）:

The user hasn't heard from you in a while — say in a few words what you're doing, then continue.

検索で現在の細部を確かめさせる:

Use the search tool to check specifics that may have changed since your training, such as what is allowed, required or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge.

coding で本物の検査を走らせる:

When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done.

原典で言及されている関連文書

• prompting-claude-sonnet-5 — 出発点として妥当なパターン
• claude-prompting-best-practices — 全モデル共通の技法
• sonnet-5-5-migration-guide — 破壊的な API 変更5つ
• effort — effort とメッセージごとの変更
• thinking — 進捗更新の thinking ブロック、要約された thinking
• prompt-caching — effort の変更と cache