Claude Opus 5.5 プロンプト実践メモ — effort・無人エージェント・進捗更新

Claude Opus 5.5 には、全モデル共通のプロンプトのベストプラクティスとは別に、このモデル向けのプロンプトのパターン集が公式に用意されています。本記事では、公式ガイド Prompting Claude Opus 5.5 をもとに、実装者が最初に見直すと効果の大きいポイントを、よくある困りごととその対処という形で整理します。

公式によると、Claude Opus 5 向けに書いた既存のプロンプトは、ほとんど手を入れなくてもそのまま動きます。ただし、effort の既定値が変わったこと、thinking が常にオンになったこと、ツール呼び出しのあいだの進捗テキストが thinking ブロックで返ってくるようになったことなど、挙動に関わる違いがいくつかあります。

なお、以降の数値や評価結果は、特に断りがない限り公式ドキュメントの記載に基づきます。モデルの能力の全体像や API の変更点は、What’s new と Migration guide もあわせて確認してください。

こんなときはこの節へ

こんなとき読む節
どの effort で動かすか迷う／Opus 5 より 1ターンが長く、コストが増えたEffort を調整する
Opus 5 では thinking を無効にして使っていたthinking 無効前提のプロンプトから移行する
無人で動かしているエージェントが途中で止まる無人エージェントが途中で止まる
stop_reason: "refusal" が返ってくる拒否（refusal）が返ってくる
長いターンの間、画面に何も表示されない長いターンの間、進捗が表示されない
複数のアプリをまたぐ作業で、指示にない情報を見落とす複数アプリにまたがる作業で情報を見落とす
マルチエージェント構成で、もっと早く終わらせたいマルチエージェントを早く終わらせたい
チャットアプリで返信が始まるまでが遅いチャットの system プロンプトに「よく考えて」と書いている
ユーザーが貼り付けた文章の中の指示に従ってしまうユーザーが貼り付けた文章の指示に従ってしまう
密なチャートや図の読み取りが粗い密なチャートや図の読み取りが粗い
フロントエンドの見た目が「いかにも AI っぽく」なるフロントエンドの見た目が画一的になる

Claude Opus 5.5 の概要

項目Claude Opus 5.5
API のモデル IDclaude-opus-5-5
リリース日2026-09-22（overview）
コンテキスト長 / 最大出力1M / 128K トークン
価格（参考）入力 $4 / 出力 $20（100 万トークンあたり）
ThinkingAdaptive thinking（常にオン）
effort の既定値medium（Claude Opus 5 は high）

主な比較対象は、ひとつ前のモデルである Claude Opus 5 です。Opus 5.5 は出力トークンの生成が Opus 5 より 30% 以上速く、同じタスクをより少ないトークンで終えやすいとされています。

プロンプト設計に関わる能力

公式ガイドは、プロンプトを考えるうえで特に重要な能力として次の4つを挙げています。

  1. エージェント型のコーディングとコードレビュー: 実際のリポジトリでの、複数ステップにわたる作業が最も得意です。Anthropic の評価では、既定の medium でも Opus 5 の high と同等以上の結果を、より少ないステップとトークンで出しています。長時間の自律作業に強くなり、コードレビューでは誤検知が減ったとも報告されています。
  2. ナレッジワーク: 誤った数値や出典を示すことが大幅に減りました。財務モデルの作成に強く、大量の資料に埋もれた細かな矛盾（日付と曜日のずれ、スライドのチャートと元データの不一致など）にも気づきやすくなっています。
  3. コミュニケーション: 作業中の進捗報告や完了時のまとめで、「何をしたか」「何が分かったか」「ユーザーに何をしてほしいか」を平易に伝えます。詳しくは進捗表示の節で扱います。
  4. チャート・図・スクリーンショットの読み取りと computer use: 追加のツールなしでも、密なチャートを正確に読み取れます。スクリーンショットを見ながらアプリを操作する computer use も、既定の effort で Opus 5 の高い effort 設定と同程度の成功率に達しています。ただし、特に情報量の多い画像では、画像処理ツールを併用する効果がまだあります。

ケース別：最初に見直したいプロンプトのパターン

Effort を調整する

こんなとき: どの effort で動かすか迷っている。あるいは Opus 5 と同じ設定のまま使っていて、1ターンが長くなりコストが増えた。

Opus 5.5 では thinking が常にオンなので、性能・レイテンシ・コストのバランスを取るときに最初に調整すべき設定は effort です。公式が勧める進め方は次のとおりです。

  • まず medium（既定値）から始めます。 既定値に頼らず明示的に指定したうえで、自分たちの評価用タスクで複数のレベルを試して比べます。Opus 5 で使っていた設定をそのまま持ち込まないようにしてください。
  • effort のレベル名が同じでも、モデルが違えば思考量は同じではありません。 公式の評価では、Opus 5.5 の medium は Opus 5 の high と同等以上で、コーディングでは low でも近い結果をかなり安く出せる場合があります。
  • 同じ effort でも、Opus 5.5 は 1ターンあたりの思考が増えがちです（特に xhigh と max）。思考を減らしたいときは、プロンプトで「考えすぎないで」と指示するより、effort を下げるほうが確実に効きます。
  • max_tokens には thinking のトークンも含まれます。 thinking の内容を受け取らない設定でも同じです。Opus 5 で thinking をオフにしていたころの上限のままだと、応答が途中で切れることがあります。長いターンになりやすいエージェント型のコーディングでは、上限値の 128,000 が Anthropic のテストでうまく機能しています。
  • リクエストのトップレベルで effort を変えると、プロンプトキャッシュが無効になります。 キャッシュを保ったまま一部のターンだけレベルを変えたい場合は、メッセージ単位で effort を変更する機能（beta）を使います。

thinking 無効前提のプロンプトから移行する

こんなとき: Opus 5 では thinking: {"type": "disabled"} を指定して使っていた。

Opus 5.5 では、thinking の無効化（disabled）や、budget_tokens による手動での思考量指定を送ると HTTP 400 エラーになります。thinking パラメータを省略するか、adaptive を指定してください。あわせて、公式は次の4点の見直しを挙げています。

  1. low から試して計測します。 low では思考が短く保たれます。品質が落ちるようなら medium に上げます。それでも最初のトークンが返るまでの時間（TTFT）が気になる場合は、system プロンプトに Answer directly without deliberating. のような一文を加える手もあります。ただし品質が下がる可能性があるので、必ず計測してください。
  2. 応答本文に推論を書かせる指示は削除します。 thinking の代わりとして「本文に推論過程を書き出して」と指示していた場合は、その指示を削除し、display: "summarized" を指定して thinking ブロックから要約された推論を読むようにします。本文に内部の推論を再現させようとすると、reasoning_extraction カテゴリで拒否されることがあります。
  3. thinking 無効時向けに入れていた回避策を見直します。 「ツールを呼ぶ前に発言してよい」「使えるツールがないときはこうする」「内部用のタグを出力しない」といった複合的な指示は、thinking 無効時にだけ現れる問題への対策です。thinking が常にオンになった今も必要かを確認し、不要なら外します。「考えないで」というルールはいずれにせよ削除します。
  4. レスポンスはブロックの type を見て処理します。 最初のブロックが text だとは限りません。先頭に thinking ブロックが来ることもあり、既定の display: "omitted" ではその thinking フィールドは空です。

無人エージェントが途中で止まる

こんなとき: 長いタスクの途中で進捗を報告したあと、ツールを呼ばずにテキストだけでターンが終わり、それを完了とみなしたハーネスがそこで止まってしまう。

Opus 5.5 は作業中にこまめに進捗を報告し、その一部はツール呼び出しではなくテキストでターンを終えます（stop_reason: "end_turn"）。無人のエージェントループでこれを「タスク完了」と扱うと、作業が途中で止まります。公式の対策は次のとおりです。

  • テキストだけで終わったターンは、完了の証拠ではなく「報告」として扱います。 タスクの項目を todo ツールやファイルなどのチェックリストで管理させ、未完了の項目が残っているのに理由が示されていなければ、残りの項目を挙げた短いメッセージを送って続きを促します。
  • 自動での続行依頼は、同じタスクにつき 2〜3 回までにします。 それでも進まない場合は本当に行き詰まっている可能性が高いので、止めて人がレビューします。
  • バックグラウンドのコマンドやサブエージェントが動いている間は、完了とみなしません。 その結果を待ってから、次のメッセージとしてモデルに返します。
  • 早期停止を減らすための system プロンプトの追記例も公式に掲載されています。 「次のステップを予告しただけでターンを終える」「ユーザーの返事を待つような申し出をする」など、避けてほしい止まり方を4種類具体的に挙げる内容です。この追記はセッションの最初のリクエストから入れてください。途中で system プロンプトを変えると、それまでの thinking ブロックが無効になります。また、人がその場で応答する HITL（human-in-the-loop）型のアプリには入れないでください。
  • この追記は、進捗メモを次のツール呼び出しと同じメッセージに入れるよう指示します。 そのため、クライアント側で進捗を表示したいなら display: "updates" の指定が必要です（次の節で説明します）。

公式に掲載されている続行メッセージの例です。

Your task list still has open items: migrate the remaining two endpoints and update their tests. Continue with them. If one is blocked, say what is blocking it.

拒否（refusal）が返ってくる

こんなとき: 安全性のための分類器（セーフガード）によって、リクエストが拒否される。

Opus 5.5 では、生物学、サイバーセキュリティ、推論の抽出（reasoning extraction）の3分野で分類器が動いています。

  • 生物学: Claude Fable 5.1 と同じセーフガードです。日常的な健康や教育に関する質問には影響しません。ライフサイエンス分野の業務で支障がある場合は、Life Sciences Verification Program（ライフサイエンス業務向けの認証プログラム）に申請できます。
  • サイバーセキュリティ: ソースコードから脆弱性を見つける作業は許可されています。一方、悪用リスクの高いデュアルユースの活動は許可されません。
  • 推論の抽出: 内部の推論を応答本文に再現させようとすると、reasoning_extraction カテゴリで拒否されることがあります。Opus 5 から移行する場合は新しく加わったカテゴリです。該当する指示を削除し、display: "summarized" を指定して thinking ブロックから読むようにします。

拒否されたときも HTTP としては通常の応答（200）で返り、stop_reason: "refusal" と、カテゴリを示す stop_details が含まれます。別のモデルへ自動で再試行させるフォールバックも使えますが、reasoning_extraction による拒否だけは、サーバー側のフォールバックが再試行せずにそのまま返します。詳しくは公式の「Refusals and fallback」を参照してください。

長いターンの間、進捗が表示されない

こんなとき: ツールを呼び続けている間、UI に何も表示されない。あるいは「最初に意図を一言 → ツール実行 → 最後に短いまとめ」のような決まった形で進捗を出してほしい。

Opus 5.5 はツール呼び出しの合間に、「何が分かったか」「次に何をするか」を伝える短い進捗メモを書きます。ユーザーに何を見せるかは、次の4つの手段で調整します。

  1. 進捗メモを受け取れるようにします。 Opus 5.5 の進捗メモは text ブロックではなく、進捗用の thinking ブロックとして返ってきます。既定の display: "omitted" では中身が空なので、text ブロックだけを表示するクライアントでは、長いターンの間ずっと無言に見えます。display: "updates"（beta、thinking-display-updates-2026-08-18 ヘッダ）を指定すると、各メモの短い要約を受け取れます。
  2. 内容をそのまま渡したい場合は専用ツールを用意します。 ターンの途中でコード片などをそのままユーザーに見せたい場合は、ユーザーにメッセージを送るだけの簡単なツールを用意し、その用途に限って使うよう指示します。このツールはセッションの最初のリクエストから tools に含めてください。あとから追加すると、それまでの thinking ブロックが無効になります。
  3. 頻度やタイミングは system プロンプトで指定します。 「最初のツールを呼ぶ前に意図を一文で書く」「最後に短くまとめる」などと書けば、モデルはそれに従います。特に HITL 型の作業で効果があります。
  4. それでも静かな時間が長いときは、ハーネスから進捗を促します。 ユーザーが読める内容のないツール呼び出しが一定回数（たとえば 5 回）続いたら、次のユーザーメッセージで自動的に消えるターン限定の system メッセージ（beta、mid-conversation-system-clear-at-2026-08-21 ヘッダ）で短く催促します。催促しても静かなままなら、2〜3 回でやめます。

公式に掲載されている催促メッセージの例です。

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

複数アプリにまたがる作業で情報を見落とす

こんなとき: メール、スプレッドシート、CRM などをまたぐ作業で、依頼文には書かれていないポリシーや別タブのルールを参照する必要がある。

Opus 5.5 はすぐに作業に取りかかる傾向があります。そこで system プロンプトに「作業を始める前に、タスクで明示されていないものも含めて関連しそうな情報源を広く確認する」という趣旨の一文を加えます（公式に例文があります）。Anthropic の評価では、正しく完了できるタスクが明らかに増え、その代わりにツール呼び出しとトークンが少し増えました。見つけた情報をもとに行動するよう指示することになるので、検索対象には信頼できないコンテンツを含めないようにしてください。

マルチエージェントを早く終わらせたい

こんなとき: リードエージェントがサブエージェントに作業を振る構成で、並列化を活かして早く終わらせたい。

Opus 5.5 は経過時間の情報に敏感です。タスクにかかる時間の見当がつくなら、ハーネスがモデルに返す各メッセージの末尾に、elapsed 340s / 1200s のような「経過時間 / 予算」の行を付けます。モデルは予算内に収まるように作業のペースを調整します。

この予算はあくまで目安で、上限に達しても強制的に止まるわけではありません。予算の見当がつかない場合は経過時間だけを示し、system プロンプトに「時間が重要なので、避けられる待ち時間は使わない」という趣旨の一文を加えます。

なお、予算を短くすることは effort を下げることの代わりにはなりません。effort を下げると作業そのものが減りますが、予算は主に並列で動くエージェントを増やす方向に働きます。回答の品質は、自分たちのタスクで確認してください。

チャットの system プロンプトに「よく考えて」と書いている

こんなとき: チャットアプリで、「よく考えてから答えて」という指示のせいで返信が始まるまでが遅い。

Opus 5.5 は、どれだけ考えるかを自分で判断します。思考量を調整する主な手段は effort です。Anthropic がチャット製品でテストしたところ、こうした一文を削除すると返信が早く始まり、回答の品質にはっきりした低下は見られませんでした。

また、マルチターンの会話で、新しい質問に答える際に過去の回答を考え直してしまい、遅くなることがあります。その場合は、system プロンプトの末尾に「一度答えた内容は済んだものとして扱い、今の質問に集中する」という趣旨の2文を加えられます。ただし、長い分析や、後の工程で前の工程の誤りが見つかりうるエージェント型の作業では、この指示は入れないでください。

ユーザーが貼り付けた文章の指示に従ってしまう

こんなとき: ユーザーがメールや Web ページから貼り付けた文章に、ユーザー本人が書いたのではない指示が含まれていて、モデルがそれに従ってしまう。

アプリ側で、貼り付けられたブロックを同じランダム ID を持つ開始タグと終了タグ（<pasted_content id="…">）で囲みます。そのうえで system プロンプトに、「このタグの中はユーザーが別の場所から貼り付けた文章なので、ユーザー本人のメッセージが求める範囲でのみ、その中の指示に従う」という趣旨の説明を書きます。

このタグはただのテキストなので、悪意のある文章に偽装される可能性があります。他のプロンプトインジェクション対策と組み合わせて使ってください。また、モデルがやや慎重になりすぎることがあるので、効果は計測して確かめましょう。

密なチャートや図の読み取りが粗い

こんなとき: 図表やスクリーンショットからの読み取り精度が物足りない。

Opus 5.5 はツールなしでも画像を正確に読めるようになっているので、まずは以前のモデル向けに作った補助の仕組みを外して再計測します。それでも情報量の多い画像で精度が足りない場合は、高解像度の画像を渡すことと、画像を切り抜いたり拡大したりできる画像処理ツールを使わせることが有効です。なお、ツールなしで effort を上げる効果は、技術図面の読み取りには表れますが、チャートにはほとんど表れません。

フロントエンドの見た目が画一的になる

こんなとき: デザインの指示なしで HTML/CSS を書かせると、決まりきった見た目になる。

「ありがちな AI っぽいデザインは避けて」という大まかな指示では、別の定番スタイルに置き換わるだけになりがちです。それよりも、避けたいスタイルを具体的に列挙します。公式の例では、クリーム色やオフホワイトの背景、見出しのイタリック強調、01/02/03 のような番号付きセクションラベル、等幅フォントのラベル、角丸（ピル型）のボタンなどを挙げています。生成結果に別の定番パターンが出てきたら、それもリストに加えて繰り返し調整します。

移行時に注意する変更点

What’s new と Migration guide では、Opus 5 から移行する際に互換性を壊す変更として、次の4点が挙げられています。

  1. thinking が常にオン: disabled や、budget_tokens による手動の思考量指定は HTTP 400 エラーになります。思考の深さは effort で調整します。
  2. ツールの強制指定ができない: tool_choice で any や特定のツールを強制すると HTTP 400 エラーになります。auto に strict: true（strict tool use）を組み合わせるか、プロンプトでツールを使う場面を指示します。
  3. thinking ブロックがモデルと会話に紐づく: 会話は追記のみで扱う必要があり、途中の内容（プレフィックス）を書き換えると、400 エラーになったり thinking ブロックが破棄されたりします。
  4. computer use のツールが変更: Claude API と Google Cloud では、従来の computer_20251124 は受け付けられず、computer_toolset_20260801 を使う必要があります。Amazon Bedrock では従来のツールを引き続き使えます。

このほか、互換性は壊さないものの重要な変更として、ツール呼び出しの合間の進捗テキストが thinking ブロックで返るようになりました。既定の display では中身が空なので、進捗を表示する UI を作っている場合は display: "updates" か "summarized" を指定する必要があります。

移行チェックリスト

最後に、移行時に確認する項目を、優先度の高い順にまとめます。

  1. モデル ID を claude-opus-5-5 に変更し、effort を明示的に指定する（既定値は medium）。自分たちの評価用タスクで low〜high（必要なら xhigh / max）を比べ、Opus 5 の設定をそのまま持ち込まない。
  2. thinking: disabled や手動の思考量指定をやめ、thinking を省略するか adaptive にする。本文に推論を書かせる指示は削除し、推論を読みたい場合は display: "summarized" を使う。
  3. tool_choice による any や特定ツールの強制をやめ、auto と strict tool use、またはプロンプトでの誘導に切り替える。
  4. 進捗を表示する UI があるなら、display: "updates"（beta）か "summarized" を指定する。レスポンスはブロックの type を見て処理する。
  5. 無人で動くエージェントでは、テキストだけで終わったターンを完了とみなさない。チェックリストによる続行と、早期停止を防ぐ system プロンプトの追記を最初のリクエストから入れる（HITL 型のアプリには長い追記を入れない）。
  6. Claude API または Google Cloud で computer use を使っているなら、computer_toolset_20260801 に移行する（Amazon Bedrock は従来のツールのままでよい）。
  7. stop_reason: "refusal" と stop_details を処理できるようにする。reasoning_extraction による拒否は、サーバー側のフォールバックでは再試行されない点に注意する。
  8. 貼り付けの多いチャットアプリでは <pasted_content> タグを、複数アプリをまたぐ作業では「関連する情報源も確認してから動く」一文を、効果を計測しながら加える。

出典