Claude Platform Docs
ベストプラクティスプロンプトエンジニアリング

Claude Sonnet 5.5へのプロンプト

Claude Sonnet 5.5に固有のプロンプトパターン：エフォート、自発性と作業範囲、事前思考なしでの実行、JSON出力、進捗更新、ツール使用、ターン途中のメッセージ、コーディングでの検証、ツール呼び出し、視覚的入力、拒否。

このガイドでは、Claude Sonnet 5.5に固有のプロンプトパターンについて説明します。モデルのAPI変更については、Claude Sonnet 5.5の新機能を参照してください。現在のすべてのClaudeモデルに適用される手法については、プロンプトのベストプラクティスを参照してください。

既存のClaude Sonnet 5のプロンプトは変更しなくても良好に機能するはずです。また、Claude Sonnet 5へのプロンプトのパターンも引き続き妥当な出発点です。最も難しい長期的な作業には、Opusモデルの方が適しています。観察された状況に合ったセクションから始めてください。

エフォートを調整する

「effort」（エフォート）は、Claude Sonnet 5.5がどれだけ思考するか、そしてそれに伴う品質、レイテンシ、コストを制御する主要な手段です。そのレベルは再調整されており、あるレベルがClaude Sonnet 5の同じレベルと同じ量の思考を生み出すわけではありません。Claude Sonnet 5で使用していた設定をそのまま引き継ぐのではなく、独自の評価に対して改めてスイープを実行してください。ワークロードがエージェント型またはレイテンシに敏感なものでない限り、Claude APIのデフォルトであるhighから始めてください。エージェント型コーディングや複数ステップのツール使用では、仕様が明確なタスクにはmediumから始め、より難しいタスクや長いタスクにはhighに移行してください。チャットやその他のレイテンシに敏感な作業では、エフォートが高いほど返信が始まるまでの待ち時間が長くなるため、mediumまたはlowから始めてください。品質上必要であればエフォートを上げてください。

エフォートを下げると、モデルがエージェント型の作業を完了する方法も変わります。lowでは、思考を短く保ち、変更の検証を省略することがあります。コーディングタスクでの検証を参照してください。lowとmediumでは、長いエージェント型タスクにおいて、完了前に止まってユーザーに確認を求める可能性が高くなります。自発性と作業範囲を制御するを参照してください。

次の3つの調整が役立ちます。

  • max_tokensは、思考と想定される返信の両方に十分な余裕を持たせて設定してください。思考の内容が返されない場合でも、思考はmax_tokensにカウントされます。思考なしのリクエストに合わせたサイズの上限では、返信が途中で切れる可能性があります。エージェント型コーディングでは、max_tokensをモデルの最大値である128,000に設定し、レスポンスをストリーミングしてください。
  • xhighとmaxは、品質の向上を測定で確認できた作業のために取っておいてください。これらのレベルでは思考と返信が大幅に長くなるためです。これらのレベルではbetween_toolsが受け付けられないため、事前思考をオフにすることはできません。
  • 思考を減らしたい場合は、エフォートレベルを下げてください。medium以上では、モデルはほぼすべての返信の前に、挨拶に対してさえ短く思考するため、最初の可視トークンまでの時間が長くなります。システムプロンプトで思考を減らすよう求めても、思考が確実に減るわけではありません。lowでは、ほとんどの単純なリクエストで思考を省略します。

リクエスト間でトップレベルのeffortの値を変更すると、プロンプトキャッシングのキャッシュが無効になります。個々のターンを異なるレベルで実行するには、代わりにメッセージごとのエフォート変更（ベータ）を使用してください。これによりキャッシュが維持されます。たとえば、インタラクティブなセッションをlowで実行し、ユーザーが難しい問題を送信したときにエフォートをhighに上げます。メッセージごとのエフォート変更には「adaptive thinking」（適応型思考）が必要です。事前思考なしでの実行で説明しているように、between_toolsと併用すると400エラーが返されます。

自発性と作業範囲を制御する

Claude Sonnet 5.5がどこまで自発的に作業を進めるかは、エフォートレベルとリクエストによって異なります。エフォートが低い場合、コーディングタスクが完了する前に確認を求めることがあります。エフォートが高い場合や、自由度の高いリクエストの場合は、依頼した以上のことを行うことがあります。エフォートレベルとシステムプロンプト内の指示によって制御してください。

作業を最後までやり遂げさせる。 lowおよびmediumエフォートのエージェント型コーディングタスクでは、モデルが作業完了前に確認を求めることがあります。計画の確認のために一時停止したり、自分で答えられる質問をしたり、複数の部分からなるタスクの一部を終えた後に続行するかどうかを尋ねたりすることがあります。まずはより高いエフォートレベルを試してください。エフォートを変更せずにモデルに作業を続けさせるには、システムプロンプトに次の内容を追加してください。

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.

このプロンプトを使用すると、モデルはlowおよびmediumエフォートでもより多くの作業を最後までやり遂げるため、これらのレベルでのセッションは長くなり、コストも増加します。このプロンプトは、リスクのある操作や元に戻せない操作に関する独自のルールに代わるものではありません。それらのルールはシステムプロンプトに残しておいてください。

コーディング時の依頼されていない追加。 モデルは、依頼されていなくても、リポジトリの規約に沿ったテスト、ドキュメント、小さな補助ファイルを追加する傾向があります。これはすべてのエフォートレベルで発生し、エフォートが高いほど多くなります。依頼された変更自体は、依頼内容に近いものにとどまります。ほとんどのチームはこれを歓迎するでしょう。明示的に依頼された内容に変更を限定したい場合は、上記プロンプトの2番目の段落（「When the work the user asked for is done」で始まる段落）のみを追加してください。xhighおよびmaxエフォートでは、この段落によってこうした追加が減り、変更全体も小さくなります。

xhighおよびmaxエフォートでの徹底性。 これらのレベルでは、モデルは特に徹底的に作業します。タスクを完了した後、独自にレビューと検証のラウンドを開始することがあり、ハーネスが提供していれば「subagents」（サブエージェント）を使用することもあります。また、作業中に気づいた関連する修正を行うこともあります。これには時間とトークンがより多くかかるため、日常的な作業は、こうした動作がまれなhigh以下で実行してください。これらのエフォートレベルの追加の徹底性は活かしつつ、それをタスク自体に向けたい場合は、システムプロンプトに次の内容を追加してください。

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.

maxエフォートでのコーディングタスクのテストでは、これによりモデルがレビュー用サブエージェントを起動しなくなり、品質を変えることなくセッションコストが約3分の1削減されました。メインエージェントが自発的に開始するレビューラウンドの頻度は下がりますが、完全になくなるわけではありません。

自由度の高いリクエスト。 「これで何ができるか見せて」のような自由度の高いリクエストの場合、アイデアだけが欲しかったのに、モデルがプレゼンテーション、レポート、動画の作成を始めてしまうことがあります。まずアイデアや計画が欲しい場合は、リクエストでそのように伝えるか、システムプロンプトに次の内容を追加してください。

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.

事前思考なしでの実行

Claude Sonnet 5.5を事前思考なしで実行するには、thinking: {"type": "between_tools"}を送信します。これはこのモデルで最も低い思考設定であり、highエフォート以下で受け付けられます。現在、インテグレーションを思考オフで実行している場合は、between_toolsに切り替えて、次の点を確認してください。

  • between_toolsはhighエフォート以下で送信する。 xhighまたはmaxエフォートでは、between_toolsを含むリクエストは400エラーを返します。between_toolsでは、会話の途中でエフォートを変更することもできません。有効なレベルと異なるメッセージごとのoutput_config.effortは400エラーを返します。ターンごとにエフォートを変えるには、適応型思考を使用してください。between_toolsを使用する場合は、モデルに思考しないよう指示する記述をすべて削除してください。そのような指示があると、モデルが可視出力に内部XMLタグを書き込む可能性が高くなります。
  • レスポンスはブロックタイプごとに読み取る。 適応型思考では、レスポンスがthinkingブロックで始まることがあり、デフォルトのdisplay: "omitted"ではそのthinkingフィールドは空です。between_toolsでは、レスポンスが進捗更新のthinkingブロックで始まることがあります。最初のコンテンツブロックがテキストであると想定しないでください。
  • thinkingブロックは変更せずに返す。 between_toolsでは、モデルがツール呼び出しの間に書くメモは、1〜2文より長い場合、引き続きthinkingブロックとして返されます。各ブロックにはメモの要約が含まれます。アシスタントターンの残りの部分とともに、変更せずに返してください。返送したブロックによって、モデルには要約ではなく、自身が書いたメモの全文が渡されます。
  • ツールなしの推論タスクには適応型思考を使用する。 ツールなしのリクエストでは、between_toolsはモデルが事前に思考せずに回答することを意味します。数ステップの推論が必要なタスクには、代わりに適応型思考を使用してください。JSON出力を伴う推論タスクを参照してください。

JSON出力を伴う推論タスク

このセクションは、数ステップの推論が必要なタスクに対して、Claude Sonnet 5.5にJSON形式の回答を求める場合に適用されます。例としては、ドキュメントから数値を合計する、ルールを適用する、項目をランク付けするなどがあります。このようなタスクでは、特にlowおよびmediumエフォートにおいて、モデルが事前に思考せずに回答することがよくあります。何が役立つかは、JSONをどのように要求するかによって異なります。利用可能な場合は「structured outputs」（構造化出力）を使用してください。その場合、レスポンステキストはスキーマに一致するJSONになるため、パースする必要はありません。

構造化出力では、レスポンステキストにはJSONのみが含まれるため、モデルは思考の中でしか問題を解くことができません。思考を省略すると、これらのタスクでの精度が低下する可能性があります。次の変更は、精度を高く保つのに役立ちます。

モデルに先に思考するよう求める。 適応型思考を使用する場合は、システムプロンプトの末尾に次の行を追加してください。

Think the problem through before you answer.

この行を追加すると、モデルは回答前に思考することが多くなります。highエフォートでは、この行により、出力トークンの適度な増加と引き換えに、xhighで達成される精度に近い精度が得られます。lowおよびmediumエフォートでは精度が向上しますが、highで達成される精度には届かず、出力トークンの増加も大きくなります。

またはxhighエフォートを使用する。 適応型思考では、xhighはこの行がなくても、これらのタスクで最高の精度を実現します。highよりも多くの出力トークンを使用します。

between_toolsではなく適応型思考を使用する。 ツールなしのリクエストでは、between_toolsの下でモデルは回答前に思考しません。そこではこの行は効果がなく、これらのタスクでの精度は低くなります。これらのリクエストには、このセクションの手順とともに適応型思考を使用してください。テストでは、リクエストを2つ（回答用のリクエストとJSON用のリクエスト）に分割すると、回答の精度とJSONへの準拠性は高くなりましたが、コストとレイテンシが非常に高くなりました。

lowおよびmediumエフォートで構造化出力を使用すると、モデルがまれにmax_tokensに達するまで思考し続けることがあります。highエフォート以上では、これはほとんど発生しません。stop_reasonが"max_tokens"であるレスポンスは、テキストに有効なJSONが含まれていても失敗として扱い、再試行してください。max_tokensは、エフォートを調整するで説明しているように、思考とJSONに十分な大きさに設定しつつ、1回の試行に費やしてもよい量を超えないようにしてください。

構造化出力を使用できない場合は、代わりにプロンプトでJSONを要求してください。その場合、モデルはレスポンステキスト内で問題を解き、最後にJSONを書くことがよくあります。JSONには通常正しい回答が含まれていますが、レスポンス全体がJSONであることを前提とするパーサーは失敗します。次の2点が役立ちます。

  • レスポンス内の最後のJSON値をパースする。 textブロックのみを読み取り、stop_reasonが"max_tokens"であるレスポンスは失敗として扱ってください。各{または[から始めて、JSON値のパースを試みます。パースに成功したら、その値の末尾から続行し、その中にネストされた値が単独でカウントされないようにします。最後に見つかった値を保持してください。最初の{から最後の}までをすべて取得しないでください。モデルは最終的なJSONの前に下書きを書くことがまれにあり、その範囲には両方が含まれてしまいます。回答が1行に1レコードのように複数のJSON値の連続である場合は、スペース、カンマ、改行のみで区切られた最後の値の連続を保持してください。結果に期待するフィールドが含まれていることを確認し、含まれていない場合は1回再試行してください。テストでは、これにより精度を変えることなく、ほぼすべてのレスポンスが使用可能になりました。
  • 適応型思考でのxhighエフォートも検討する。 その場合、モデルは思考の中で問題を解き、ほぼ常にJSONのみを返します。推論の過程がレスポンステキストから思考に移るため、出力トークンの合計はhighの場合とほぼ同じです。

ユーザー向けの進捗更新

Claude Sonnet 5.5は、ツール呼び出しの間に、直前に見つけたことと次に行うことについてユーザー向けのメモを書きます。1〜2文より長いメモは進捗更新のthinkingブロックとして返されます。それより短いコメントはtextのままです。デフォルトのthinking.displayでは、進捗更新ブロックのテキストは空であるため、textブロックのみをレンダリングするクライアントでは、長いエージェント型ターンの間に何も表示されないように見えることがあります。これは、チャットインターフェースや、ユーザーがモデルの作業をリアルタイムで追うその他の製品で特に重要です。

これらのメモを表示するには、display: "updates"（ベータ、thinking-display-updates-2026-08-18ヘッダー）を設定してください。between_toolsでは、メモは要約テキスト付きで返されるため、displayフィールドは不要です。between_toolsは他のフィールドを受け付けません。display、budget_tokens、またはblock_bindingを併せて送信すると400エラーが返されます。メモのレンダリング方法は移行ガイドに示されています。長いターンの途中で、コードスニペットや回答が必要な質問など、正確なテキストをユーザーに示す必要がある場合があります。そのような場合のために、ユーザーにメッセージを送信するためのシンプルなツールをモデルに与えてください。そのツールはそのようなコンテンツにのみ使用するようモデルに指示してください。toolsリストが後で変わらないように、ツールはセッションの最初のリクエストで宣言してください。

次に、「すべての調査結果は最終レスポンスまで保持する」のような古い指示を削除してください。そのうえで、たとえば最初のツール呼び出しの前にモデルがこれから行うことを1行で示し、最後に短い要約を示すなど、予測可能なタイミングで更新が欲しい場合は、システムプロンプトでそのように伝えてください。モデルはこのような指示に従います。決まったタイミングでの更新は、「human-in-the-loop」（ヒューマンインザループ）の作業で最も役立ちます。

それでも長いツール呼び出しのターンが望む以上に長く沈黙する場合は、ハーネスから更新を促すことができます。ユーザーにテキストも進捗更新も送信しない連続したツール呼び出しステップの数をハーネスでカウントしてください。それが連続して数回（たとえば5回）続いたら、最新のツール結果の後に1ターン限りのリマインダーを追加します。次のようなテキストを、ターンスコープのシステムメッセージ（ベータ）として送信してください。

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

ターンが沈黙したままの場合は、2回目または3回目以降はリマインダーの送信を停止してください。ターン途中のユーザーメッセージで説明しているように、ツール結果の後にハーネスのテキストが頻繁に入ると、モデルが「prompt injection」（プロンプトインジェクション）を疑う可能性があります。各リマインダーは、以降のリクエストでもmessagesに残しておいてください。リマインダーは挿入して後で削除するのではなく追加されるため、プロンプトキャッシングのキャッシュと保持された思考はそのまま維持されます。highエフォートで、ユーザーにメッセージを送信するツールが利用可能な場合、このリマインダーによってモデルはユーザーへの更新をより頻繁に行うようになり、最も長い沈黙の時間が短くなります。タスク品質に測定可能な変化はありません。

チャットとナレッジワークにおけるツール使用

チャットやナレッジワークのタスクでは、Claude Sonnet 5.5は、Web検索をすれば変更された詳細を把握できる場面でも、訓練時の知識から回答することがあります。例としては、何が許可されているか、何が必要か、何が課金されるかなどがあります。

まず、「厳密に必要な場合にのみツールを使用する」や「ツール呼び出しを最小限にする」など、ツール使用を抑制する表現がプロンプトにないか確認し、あれば削除してください。次に、製品がモデルに検索ツールを提供している場合は、システムプロンプトに次の内容を追加してください。

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.

これは、回答が最新の詳細に依存するリサーチ製品やサポート製品で特に重要です。

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

Claude Sonnet 5.5は、「indirect prompt injection」（間接プロンプトインジェクション）、つまりタスク中に読み取るツール結果やその他のコンテンツを通じて届く悪意のある指示に抵抗するよう訓練されています。そのため、本物のユーザーメッセージを潜在的なインジェクションとして扱うことがあります。ユーザーがタスクの途中で入力したメッセージが、ツール結果の直後に配置された会話途中のシステムメッセージとして、またはtool_resultブロック内でモデルに届いたとします。その場合、モデルはツール結果にユーザーからのメッセージを装ったテキストが含まれていたとユーザーに伝え、そのメッセージを無視したり、ユーザーに確認を求めたりすることがあります。

ハーネスがすべてのツール結果の後に追加するトークンのカウントダウンが、これを引き起こすことがあります。モデルが複数ステップのターンの途中にある間にユーザーがメッセージを送信できるようにすることや、ハーネスがすべてのステップでツール結果の後に指示やコンテキストを追加することも同様です。いずれの場合も、ツール結果の直後にテキストが届きます。カウントダウンやステップごとの指示では、これがすべてのツール呼び出しで発生する可能性があります。ユーザー向けの進捗更新で紹介したような、時折送信される1ターン限りのリマインダーは、はるかに頻度が低くなります。独自のリマインダーに対してこのような反応が見られる場合は、リマインダーの送信頻度を下げてください。誤認を避けるには、次のようにします。

  • ユーザーのテキストをtool_resultブロック内に入れないでください。モデルはこの配置を最も頻繁に誤認します。
  • ターン途中のユーザー入力は、ユーザーターンとして渡してください。tool_resultブロックを含むユーザーメッセージ内で、最後のtool_resultの後に、ユーザーの言葉をテキストブロックとして追加します。
  • リマインダーなどのハーネスからの通知は、ユーザーの言葉の後に、別の会話途中のシステムメッセージとして配置してください。通知とユーザーの言葉を同じブロックに入れないでください。
  • ユーザーがターンの途中で入力できるインタラクティブなセッションでは、ツール結果の後に独自のトークンや予算のカウントダウンを追加しないでください。タスク予算（ベータ）も同様のカウントダウンを追加しますが、この誤認を引き起こすことは確認されていません。タスク予算を設定している間に誤認が見られる場合は、タスク予算なしでセッションを試してください。

コーディングタスクでの検証

エージェント型コーディングタスクでは、Claude Sonnet 5.5は通常、変更が完了したと報告する前に作業を確認します。ただし、lowエフォートでは、変更を実際に動作させる確認を実行せずに、変更が完了したと報告することがあります。たとえば、プロジェクトの依存関係がインストールされていないという理由で、プロジェクトのテストを省略することがあります。

トランスクリプトにテストやビルドの出力がないまま変更が完了したと報告されている場合は、次の段落、またはそれに類する段落をシステムプロンプトに追加してください。lowエフォートでは、これにより確認の省略や表面的な確認がまれになり、タスク品質に測定可能な変化はなく、タスクあたりのコストもわずかに増えるだけです。

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.

寛容なツール呼び出し処理

Claude Sonnet 5.5は、Bashに対してbashのように、大文字・小文字のみが異なる名前で宣言済みのツールを呼び出すことがまれにあります。また、既知のパラメータをわずかに異なる名前で渡すこともあります。このような呼び出しを致命的なエラーとして扱うのではなく、ハーネスで次の2つの方法のいずれかで処理してください。

  • 大文字・小文字が誤っていても、一致が明確な場合は呼び出しを受け入れる。
  • 期待される正確な名前を記載した、is_error: trueを含むtool_resultを返す。モデルは通常、次のターンで呼び出しを修正します。is_errorによるエラー処理を参照してください。

複雑な視覚的入力のためのツール

情報量の多いグラフや技術図面については、Claude Sonnet 5.5に画像の切り抜き、拡大、または画像に対するコード実行の手段を与えてください。このようなツールがあると、モデルはこれらの入力を著しく正確に読み取ります。グラフでは、ツールはすべてのエフォートレベルで役立ちます。技術図面では、highエフォート以上でのみ役立ち、xhighとmaxで最も効果があります。グラフについては、エフォートを上げるよりもツールを追加する方が効果的です。テストでは、highエフォートでツールを使用した場合、maxエフォートでツールを使用しない場合よりも、わずかなコストでグラフをより正確に読み取りました。切り抜きツールのレシピに、動作するツール定義があります。

セーフガードによる拒否

Claude Sonnet 5.5は、リクエストを拒否できる安全性分類器を実行しています。拒否はstop_reason: "refusal"を含む通常のレスポンスとして届き、stop_details.categoryが拒否カテゴリを示します。

  • cyber：マルウェアやエクスプロイトの開発など、サイバー上の危害を可能にする可能性のあるリクエスト。ソースコード内の脆弱性の発見は許可されています。高リスクのデュアルユースのサイバーセキュリティ作業は許可されていません。
  • bio：危険な実験手法など、生物学的な危害を可能にする可能性のあるリクエスト。日常的な健康に関する質問や教育的な質問は影響を受けません。
  • frontier_llm：競合するAIモデルの開発を支援する可能性のあるリクエスト。
  • reasoning_extraction：モデルの内部推論をレスポンステキストで再現するよう求めるリクエスト。
  • general_harms：その他の利用ポリシー領域に該当するリクエスト。無害な作業でもこのカテゴリがトリガーされることがあります。

bio分類器が組織のライフサイエンス関連の作業をブロックする場合は、Life Sciences Verification Programに申請できます。

サーバーサイドフォールバック（ベータ）を有効にすると、cyberおよびfrontier_llmによる拒否はClaude Sonnet 5で再試行されます。bio、reasoning_extraction、general_harmsによる拒否は再試行されません。拒否、フォールバック、課金を参照してください。

プロンプトでモデルにレスポンス内に推論を含めるよう求めている場合は、その指示を削除してください。そのような指示はreasoning_extractionによる拒否を招きます。適応型思考を使用する場合は、代わりに要約された思考ブロック（display: "summarized"）から推論を読み取ってください。

Was this page helpful?