AI Agent API のプロンプト エンジニアリング

Claude、GPT、Gemini API を使用して AI エージェントを構築するためのシステム プロンプト、ツール説明、エージェント指示を記述するためのガイドライン。プロンプト エンジニアリング（指示テキストの作成）と、より広い分野であるコンテキスト エンジニアリング（モデルが見るすべてのもの（ツール、メモリ、取得したドキュメント、状態）を編成して、望ましい動作の可能性を最大化すること）の両方をカバーします。

プロセス

既存のプロンプトを編集する場合、以下の順序に従います：

1. 読む — 完全な既存プロンプトを読みます。その意図、構造、ターゲット プロバイダーを理解します。
2. 特定する — 必要な特定の失敗モードまたは改善を特定します。壊れていないものは書き直さないでください。
3. ドラフト — 以下のガイドラインに従って、問題に対処する最小限の変更を作成します。
4. 再読 — 編集後にプロンプト全体を再読して、矛盾や流れの破断がないか確認します。
5. テスト — ターゲット プロバイダー上で代表的な入力を使用してプロンプトをテストします。

新しいプロンプトの場合：最小限から始め（ロール+制約+例+出力形式）、テストして、失敗モードを観察した場合のみ指示を追加します。

プロンプト編集を送信する前に：矛盾をチェック（2つのルールが競合する場合、モデルは任意に選択します — 1つを削除）し、明確性を確認（コンテキストなしの同僚がこのプロンプトに明確に従えるか？）します。

A. 普遍的なベストプラクティス

これらは 3 つのプロバイダーすべてに適用され、プロンプト エンジニアリング作業の約 70% をカバーします。

システム プロンプト構造

• トップで明確なロールを設定します — 1 文で。すべてのプロバイダーがペルソナ フレーミングを尊重します。
• XML タグを使用します （<role>、<constraints>、<examples>、<output_format>）セクションを区切るため。3 つのプロバイダーすべてが XML を解析します — それはプロバイダー間で最も安全な区切り文字です。
• 明示的で具体的になります。 何をするかだけでなく、なぜその動作が重要なのかを説明します。モデルは厳格なルールよりも説明からよりよく一般化します。
• モデルに何をすべきかを伝えます。 何をしてはいけないかではなく。肯定的なフレーミング（「散文段落で書く」）は否定的（「マークダウンを使用しないでください」）に勝ります。
• 最小限から始めて、反復します。 失敗モードを観察した場合のみ指示を追加します。過度にエンジニアリングされたプロンプトは、Gemini での過度な分析と Claude での過度なトリガーの原因になります。

少数ショット例

• 3〜5 つの多様な例を含めます — すべてのプロバイダー全体で最も信頼性の高いステアリング メカニズムの 1 つ。
• 典型的なケース、エッジケース、少なくとも 1 つの「やってはいけないこと」の例をカバーします。
• <example> タグで <input> および <output> サブタグでラップします。
• バジェット モデルはより多くの例（最小 5〜6）とより単純なパターンが必要です。

出力形式

• 出力形式を明示的に定義します — JSON スキーマ、マークダウン テンプレート、または構造化テキスト。
• 説明だけでなく、期待される出力の具体的な例を提供します。
• 説明ではなく有効な値として列挙配列を使用します — すべてのプロバイダーで機能し、精度を向上させます。

コンテキスト エンジニアリング

• コンテキスト ウィンドウは作業メモリです。すべてのトークンが注意をめぐって競合します — 多いほど常に良いわけではありません。望ましい結果の可能性を最大化する最小限の高シグナル トークン セットを見つけます。
• 長いドキュメントをトップに配置し、クエリと指示をボトムに配置します。 この順序は、複雑なマルチドキュメント入力で応答品質を最大 30% 向上させます。
• 段階的発見を優先します — エージェントがツール経由でコンテキストを検索できるようにします。すべての情報を前もって読み込まないでください。軽量識別子（パス、名前、リンク）を維持し、完全なコンテンツを動的に読み込みます。事前取得（高速、既知の関連）と自律的な探索（未知を発見）を組み合わせます。
• 技術 ID より意味的な名前を優先します — UUID、MIME タイプ、内部コードを人間が読める名前（ファイル名、説明的なラベル）で置き換えます。LLM は不透明な識別子より自然言語でより正確に推論します。
• コンテキストが大きくなると、モデルに最初に関連セクションを引用するように求めます。その後推論します — これはノイズを切り抜き、応答を根拠とします。
• マルチターン エージェントの場合：会話履歴をコンパクトで要約します コンテキスト制限時に、重要な決定と発見を保存します。要約には廉価モデル（Flash、Haiku）を使用します。
• 長期のタスクの場合：構造化ノート（スクラッチパッド、状態 JSON）をコンパクション後も生き残る必要がある情報として会話外に保持します。
• 関連のないコンテキストは活発にパフォーマンスを低下させます — 現在のステップが必要としないものを容赦なくトリミングします。パフォーマンスはコンテキストが増えるにつれて段階的に低下します（崖ではなく）。

幻覚を減らす

幻覚は 1 つの問題ではありません — 異なるタイプは異なる軽減を必要とします。

事実の捏造（モデルが事実を作る）：

• 「すべてのクレームを [ソース] に根拠があります。答える前に関連セクションを引用します。」
• 「に従って...」プロンプト — モデルを特定の信頼できるソースを引用するように指導します。
• 訓練データに依存するのではなく、検索/取得ツールを使用して検証済み情報に接続します。

前提の受け入れ（モデルが偽/矛盾した前提に基づく）：

• 「答える前に、質問の仮定が有効かどうかを評価します。概念が一緒に属さない場合、または前提が矛盾している場合、具体的に言います — 間違っていることを識別し、単に避けないでください。」
• 一般的な免責事項（「AI として...」）と丁寧なヘッジは前提の受け入れを減らしません。欠陥の具体的な特定のみが機能します。
• エージェント的システムの場合：エージェントに事実的クレームをツール経由で確認してから述べるよう指示します。

推論エラー（論理的に一貫していますが、事実的に間違ったチェーン）：

• Step-Back プロンプティングを使用します：「最初に関連する高レベルの原則を特定し、次に特定のケースについて推論します。」（連鎖思考を最大 36% 上回ります。）
• Chain-of-Verification：回答を生成 → 検証質問を作成 → 実行 → 修正を組み込んだ最終回答を作成します。

混合捏造（知識ギャップを尤もらしい虚構で埋める）：

• 明示的なフォールバック動作を定義します：「提供されたコンテキストが X について情報を含まない場合、「X について情報がありません」と言います — 推測しないでください。」
• ツール応答で：「はじめに含まれていないもの（「financial_data を含まない — get_project_details を使用」）を述べます。

ツール幻覚（間違ったツール、捏造されたパラメータ）：

• ツール説明品質で対処されます（セクション B を参照）— これはツール説明が最も高レバレッジの品質ファクターである理由です。

統一の原則：モデルに外部現実に対してチェック（ツール、ドキュメント、検索）するように指示するのではなく、パラメータのみから生成するのです。根拠がより確定的であるほど、幻覚率は低くなります。

タスク分解

• 複雑なタスクをフェーズに分割し、明確なハンドオフポイントを持ちます。
• 各フェーズの成功基準を定義して、モデルが自己チェックできます。
• 異なるサブタスク（分析、抽出、生成）に別のプロンプト テンプレートを使用します。
• 複雑なワークフローの場合、連鎖したプロンプトに分割します — あるプロンプトの出力が次のプロンプトの入力になります。GPT と Gemini はバンドルされたメガプロンプトより焦点を絞ったプロンプトでより良くパフォーマンスを発揮します。

エージェント的システム

マルチステップまたはマルチエージェント ワークフローを設計する場合：

• サブエージェント設計 — 各サブエージェントに焦点を絞ったプロンプトと最小限のツール セットを付与します。親コンテキストを渡すかどうかを選択します：分離されたサブエージェント（継承されたコンテキストなし）はコンテキスト汚染を防止します。コンテキスト認識サブエージェント（注入された状態）は継続性を有効にします。どちらの方法でも、生の探索ではなく、要約された概要（1-2K トークン）をオーケストレーターに返します。
• 状態管理 — 追跡可能な状態（フェーズ進捗、スコア、合格/不合格）には構造化 JSON を使用し、定性的なメモ（発見、推論）には自由テキストを使用します。オーケストレーターが作用できる状態更新を発行します。
• ウィンドウ間のコンテキスト — タスクが複数のコンテキスト ウィンドウにまたがる場合、新しいウィンドウを生の会話履歴ではなく、以前の発見の構造化された要約で開始します。
• 自律性キャリブレーション — エージェントが自律的に何を行うことができるか、対して確認が必要なものを明示します。デフォルト：読み取り操作は自律的、書き込み/削除操作は確認が必要。Claude 4.6 は非常にプロアクティブです — 積極的なプロンプトを抑えるか、それは過度に行動します。
• 委譲規律 — Claude 4.6 は単純なタスクに対してサブエージェントを過度に生成します。追加：「タスクが専門的なツールまたはクリーンなコンテキストが必要な場合にのみ委譲します。単純な検索の場合、自分で行います。」

B. ツール説明

ツール説明は、3 つのプロバイダーすべてにおけるツール使用精度のための最も単一の影響を与える品質ファクターです。

最小要件

• フルモデル：最小 3〜4 文。 バジェット モデル：5〜6 文。
• すべてのツール説明は以下をカバーする必要があります：
  1. それが何をするか — 1 つの明確な文
  2. いつ使用するか — 特定のトリガーと条件
  3. いつ使用しないか — 一般的な間違いと重複するツール
  4. パラメータ — 各パラメータのタイプ、制約、有効な値、形式
  5. 戻り値 — 戻ってくるものと戻らないもの
  6. 注意事項 — レート制限、データの鮮度、エラー条件

アーキテクチャ

• アクティブなツールを 10〜20 に制限します すべてのプロバイダーで最高の精度のため。より大きなセットにはツール検索または動的読み込みを使用します — Anthropic と OpenAI の両方が、頻繁に使用されないツールを延期することを推奨します。
• 最小限のセットをキュレーションします — 人間が 2 つのツール間で確実に選択できない場合、モデルもできません。
• ワークフロー周辺のビルド ツール、API ラッパーではなく。schedule_event（可用性を見つけてスケジュール）は分離した list_users + list_events + create_event に勝ります。より少なくて、より高い価値のツールが多くの狭いツールをしのぎます。
• 意味のある名前空間の名前を snake_case で使用します（github_list_prs、list ではなく）。接頭辞でグループ化された関連ツール。一部のプロバイダーはスペースまたは特殊文字を含む名前を拒否します。
• ツール応答を慎重に設計します — 以下のツール応答設計を参照。
• 3 つのプロバイダーすべてが並列ツール呼び出しをサポートします — 独立的に呼び出し可能なツールを設計します。
• 評価による反復：小さな説明の改善は劇的な利益をもたらします。現実的なマルチツール テスト ケースを作成し、プログラム的に実行し、トランスクリプトを分析します。ツールが誤用された場合、最初に説明を修正します — それは最も高レバレッジの修正です。

プロバイダー固有のツール ガイダンス

側面	Claude	GPT	Gemini
説明スタイル	詳細なナレーティブ（3-4 文）	CTCO：コンテキスト、タスク、制約、出力	短くて直接的。列挙配列を大量に使用
厳密なスキーマ	サポートされています	strict: true 100% スキーマ準拠	最大 512 宣言。10-20 アクティブ推奨
ツール前文	不要	「ツールを呼び出す前に、なぜを説明」精度を高める	不要
エラー復旧	ネイティブでよく処理	ネイティブでよく処理	追加：「同じ引数で失敗した呼び出しを繰り返さないでください」
スコープ クリープ リスク	低い	高い — 「要求されたことだけを行う」を追加	中程度

本番システムからの効果的なパターン

Claude Code のツール説明と他の本番エージェントからのパターン：

• 決定木ルーティング：「X で Y を常に使用します。Z は決して使用しません — 代わりに W を使用します。」直接、明確なツール選択。
• 使用時期/非使用時期を第 1 級セクション — パラメータ ドキュメント後にそれらを埋めるのではなく、説明の上に配置します。単なる「関連がある場合」ではなく、特定のトリガーを含めます。
• 代替案を明示的に名付けます：「従業員を検索するために使用しないでください — search_employees を代わりに使用します。」モデルは何を呼び出すか知る必要があります。
• 安全の制約を分離 — 機能説明から完全に復帰可能、または危険な操作を区別します。
• 具体的なしきい値 — 「複雑なタスク」ではなく「3+ ステップ」「十分なテキスト」ではなく「最低 2 文字」数値が可能な限り。

入力例

ネストされたオブジェクト、形式に敏感なパラメータを持つ複雑なツール、または互いに容易に混乱するツール — 現実的なパラメータ値を示す 1-5 の入力例を追加します。これはパラメータ精度を 72% から 90% に改善します。

完全な構造化形式については、${CLAUDE_SKILL_DIR}/templates/tool-description-template.md を参照してください。

ツール応答設計

ツール応答はコンテキストです — 肥えた応答はトークンを浪費し、後続のステップでの推論を低下させます。

• 高シグナル情報のみを返します。 内部 ID、メタデータ、モデルが使用しないフィールドを削除します。
• 技術的なもりより意味的な値を使用 — mime_type: "application/vnd.openxmlformats..." ではなく file_type: "spreadsheet" を返します。status_code: 3 ではなく status: "approved" を返します。
• 大きな結果をページネーション 、適切なデフォルト付き。合計数とガイダンス メッセージを含めます：「487 結果のうち 20 を表示。クエリを絞り込むか、次のページは offset を使用します。」— モデルを対象の検索に向かうステアリングします。
• 長いテキストを構造的な概要で切る — 最初の N 行と概要（ヘッダー、セクション）を返して、モデルが特定の部分をリクエストできます。
• 明示的な不在 — 含まれていないものを述べます：「financial_data を含まない — get_project_details を使用。」これは幻覚フィールドを防止します。
• 実行可能なエラー — 不透明なコードではなく、特定のアクション可能なエラー メッセージを返します。「'XYZ' の結果なし。より広い用語を試すか、スペルを確認します。」は「エラー 404」に勝ります。
• 応答形式パラメータ — format パラメータ（"detailed" vs "concise"）を公開して、エージェントが出力の詳細度を選択できます。簡潔な応答は詳細なものより 3 倍少ないトークンになる可能性があり、推論のコンテキストを節約します。

C. プロバイダーの違い

システム プロンプト ロールと配置

側面	Claude	GPT	Gemini
システム ロール名	system	developer（ユーザーより優先）	system_instruction
指示配置	トップは最高に機能	開始と終了の両方（最新性バイアス）	重要な制約は最後に
マルチターン ドリフト	システム プロンプトは十分に永続します	主要な指示を 3-5 メッセージごとに再追加	システム指示は十分に永続します
デフォルト詳細度	詳細 — 必要に応じて簡潔さをリクエスト	中程度 — text.verbosity パラメータを使用	簡潔 — 必要に応じて詳細をリクエスト

プロンプト スタイル

側面	Claude	GPT	Gemini
積極的な言語	避ける — 4.6 はデフォルトでプロアクティブです。積極的なプロンプトは過度なトリガーと過度なアクションの原因になります	GPT-5 では不要（最もステアラブルなモデル）。矛盾は積極的に有害です	避ける — 過度な分析の原因になります
Chain-of-thought	不要 — 適応的な思考を使用	有害 推理モデルで — パフォーマンスを低下させます	不要 — thinkingLevel を使用
プロンプト長	中程度の長さのプロンプトがよく機能	より長いプロンプトが許容される	短く直接的なプロンプトがよく機能
構造化	XML タグ（最強のサポート）	XML またはマークダウン（JSON ラッピングはパフォーマンスを低下させます）	XML、マークダウン、またはプレーン テキスト — 一貫性を保ちます
ペルソナ ハンドリング	従うが、ガードレールを維持	かなり従う	ペルソナを非常に真剣に受け取る — 他の指示をオーバーライドする可能性
非英語出力	プロンプト言語を自然に従う	軽くナッジが必要	積極的に必要：「{LANGUAGE} で応答します。あなたは {LANGUAGE} で明確に応答しなければなりません。」

推論と思考

側面	Claude	GPT	Gemini
メカニズム	デフォルトで適応的。effort パラメータで制御（low/medium/high/max）	reasoning.effort：minimal/medium/high/xhigh。複数のエージェント ターン全体でピーク	thinkingLevel：minimal/low/medium/high（Gemini 3）。thinkingBudget トークン数（Gemini 2.5）
デフォルト状態	適応的（モデルが決定）— 設定不要	オフ — 明示的に有効にする必要があります	最新の Pro モデルで無効化できません
温度	0.0-1.0 典型的な範囲	0.0-1.0 典型的な範囲	1.0 に保ちます — 低下させるとループ/低下の原因になります
トレース再利用	サポートされていません	previous_response_id マルチターンでトークンを保存	サポートされていません

キャッシング

側面	Claude	GPT	Gemini
メカニズム	開発者制御キャッシュ ブレークポイント（cache_control）	自動プレフィックス ベース（≥1024 トークン、128 トークン粒度）	暗黙的（自動）+ 明示的（CachedContent オブジェクト）
コスト削減	キャッシュ読み取りは入力コストの 10%（90% 節約）	キャッシュ読み取りは標準入力より約 80% 廉価	モデル依存。明示的キャッシングは要求あたりのコストを削減
最小トークン	モデルに応じて 1,024-4,096	1,024 トークン	モデルによって異なります
TTL	5 分（デフォルト）または 1 時間。読み取りは TTL をリセット	約 5-10 分自動。拡張キャッシング付き 24 時間	1 時間デフォルト。CachedContent ごとに構成可能

キャッシュ対応プロンプト設計（すべてのプロバイダーに適用、入力コストを 80-90% 削減）：

• 構造的安定 → 動的：システム プロンプト、ツール定義、例を最初に配置（安定したプレフィックス）。ユーザー入力と会話履歴を最後に配置。プレフィックスはリクエスト全体でバイト同一である必要があります。
• 再配置しない：リクエスト間でツール順序、画像順序、またはメッセージ順序を変更すると、すべてのプロバイダーでキャッシュが破損します。新しいメッセージを追加します — 以前のメッセージを変更しません。
• マルチターン：アシスタント応答 + 新しいユーザー メッセージを最後に追加。安定したプレフィックス（システム+ツール+以前のメッセージ）は自動的にキャッシュにヒット。
• 監視：応答で cache_read_input_tokens（Claude）、cached_tokens（GPT）、またはキャッシュ メタデータ（Gemini）をチェックしてヒットを確認。

独自の機能

• Claude： Prefill は 4.6 で削除されました。適応的な思考がデフォルトです — 設定不要。コンテキスト認識（残りのコンテキスト ウィンドウを追跡可能）。並列ツール呼び出しは明示的な指示で約 100% 成功。effort パラメータ（budget_tokens ではなく）思考制御に使用 — max レベルは品質が重要なタスク向けに利用可能。ツール検索は大きなツール セットの延期に利用可能。
• GPT： developer ロールは user より優先 — セキュリティに敏感な指示は開発者メッセージに移動。strict: true は 100% JSON スキーマ準拠を保証。独立した text.verbosity パラメータ（low/medium/high）出力長を推論深さから個別に制御。previous_response_id は推論全体でターンを保存（73.9% → 78.2% ベンチマーク）。5 番目の推論努力レベル xhigh は品質が重要なタスク向けに利用可能。プロンプトの矛盾は GPT-5 でより有害です — 矛盾を無視する代わりに解決することに費用をかけています。
• Gemini： ネイティブ Google 検索基礎（排他的な幻覚防止ツール — リアルタイム検証情報にモデルを接続）。マルチモーダル（画像/ビデオ/PDF トークン予算）のメディア解像度制御。Gemini 3 は単一の呼び出しでビルト イン ツール（検索、コード実行）とカスタム関数呼び出しを組み合わせることができます。関数呼び出しは結果と一緒に返す必要がある一意の ID を生成します。customtools モデル バリアントはエージェント的ワークフロー向けに最適化されており、カスタム ツールの優先順位が付けられます。少数ショット例は重要です — 「少数ショット例なしのプロンプトは有効である可能性が低くなります。」デフォルトの詳細度は簡潔です — 明示的に詳細をリクエスト。時間に敏感なタスク用に時間的基礎を追加（「今年は {YEAR} であることを思い出してください」）。完了プライミング（応答を開始し、モデルを続行させる）は形式設定の説明より信頼性があります。思考署名（thoughtSignatures）はマルチターン呼び出し全体で推論チェーンを保存 — 一貫性を維持するためにそれをキャプチャして返します。

D. バジェット モデル

バジェット モデル（Claude Haiku 4.5、GPT-5 Mini、Gemini 3 Flash/3.1 Flash Lite）は共通のパターンを共有します：

変わるもの

• より明示的な指示 — コンテキストから意図を推測する際に能力が低い。
• より多くの例 — 最小 5〜6、より単純なパターン、より多くのエッジケースをカバーします。
• よりシンプルなツール セット — より少ないツールで、より明確な境界。可能な限り統合します。
• より短いシステム プロンプト — コンテキストを積極的にトリミング。バジェット モデルはノイズからより失われています。
• より長いツール説明 — 3〜4 ではなく最小 5〜6 文。

ティア別の最良の用途

タスク タイプ	Haiku 4.5	GPT-5 Mini	Flash/Flash Lite
分類/ルーティング	優秀	良い	優秀
構造化抽出	良い	良い	良い
シンプルなツール使用	良い	良い	良い
複雑な推論	フルモデルを使用	フルモデルを使用	フルモデルを使用
マルチモーダル（画像/PDF）	適切	適切	Flash 優秀
大量バッチ	良い価値	良い価値	Flash Lite 最高価値

実践的なパターン

高速/廉価フェーズ（抽出、分類、ルーティング）にはバジェット モデルを使用し、複雑なフェーズ（分析、推奨、生成）にはフルモデルを使用。これは標準的なマルチティア エージェント パイプラインです。

警告：弱いモデル向けに設計されたツールは、より強いモデルに積極的に害を与える可能性があります。Haiku に役立つ詳細な回避策とハンドホールディングは、Opus が過度にトリガーしたり、過度に行動する可能性があります。複数のモデル ティアをサポートする場合、各ティアでツール説明をテストします — または、モデル条件付きツール説明を使用します。

E. プロバイダー間互換性

プロバイダー全体で機能するか、プロバイダー切り替えが可能性が高い場合のプロンプト記述：

どこでも安全

• セクション用 XML タグ
• マークダウンのヘッダーとリスト
• <example> タグの少数ショット例 — 明示的な制約エンフォーサーとしても機能（例が十分に明確な場合、明示的な指示を置き換えることができます）
• 有効な値の列挙配列
• 最初の文のロール/ペルソナ
• 肯定的なフレーミング（「Y しないでください」ではなく「X をしてください」）
• 具体的な例を伴う明示的な出力形式

エージェント フレームワークで、プロンプトではなく、プロバイダーごとに抽象化する必要があります

• 思考/推論設定（API パラメータ、プロンプト コンテンツではなく）
• 温度設定（特に Gemini の 1.0 要件）
• システム メッセージ ロール名（system vs developer vs system_instruction）
• キャッシング戦略（手動ブレークポイント vs 自動プレフィックス vs 自動）
• ツール スキーマ厳密性（strict: true GPT 固有）
• 推論努力レベル（プロバイダーごとに異なるスケール）

クロスプロバイダー プロンプト パターン

コア プロンプトを 1 回 XML 構造を使用して記述し、エージェント フレームワークで プロバイダー固有の調整をラップします：

1. コア プロンプト： ロール+制約+ツール+例+出力形式（XML タグ）
2. プロバイダー アダプター： 指示配置、言語強制、アンチ スコープ クリープ ガードレール
3. モデル アダプター： 思考設定、温度、キャッシング、最大トークン

F. 例

良い vs 悪いシステム プロンプト オープニング

<example> <label>良い — 明確なロール、なぜを説明</label> <content> あなたは政府入札文書を分析するシニア監査人です。企業が入札するかどうかを決定できるように、適格性要件とスコアリング基準を特定するのが目標です。

要件が曖昧な場合、推測するのではなく明示的にそれらをフラグします。要件を見落とすコストは、誤検知のコストより はるかに高くなります。 </content> <reasoning> 1 文で明確なロールを設定。目標を説明。意思決定原則をなぜ（コスト非対称性）を伴う。モデルは今、この原則を新しい状況に一般化できます。 </reasoning> </example>

<example> <label>悪い — 曖昧、理由なし</label> <content> あなたはヘルパー アシスタントです。徹底的で正確であります。間違いを犯さない。常に仕事をダブルチェック。 </content> <reasoning> 特定のロールなし。「徹底的である」と「間違いを犯さない」は無意味です — すべてのモデルはすでに正確である試みをしています。なぜとどのように優先順位をつけるかの説明なし。モデルが一般化することは何もありません。 </reasoning> </example>

良い vs 悪いツール説明

<example> <label>良い — すべての 6 つの必須要素をカバー</label> <content> フルテキスト検索を使用してデータベースでプロジェクトを検索。ユーザーが過去の仕事、特定のプロジェクト、またはドメイン内の経験について尋ねる場合に使用します。従業員またはクライアントを検索する場合は使用しないでください — 代わりに search_employees または search_clients を使用。

引数： query：str。検索用語（ヘブライ語または英語）。ヘブライ語プレフィックス マッチングの場合、少なくとも 2 文字を使用。例：「ביקורת רשויות」 limit：int、オプション。返す最大結果数。デフォルト 10。

project_id、name、client_name、year、scope、team_members を含むレコードのリストを返します。financial_data を含まない — billing の場合は get_project_details を使用。 </content> <reasoning> カバー：何をするか、いつ使用するか、いつ使用しないか（代替案付き）、パラメータの詳細と例、戻り値と明示的な除外。6 文。これを読むモデルはツールを誤用できません。 </reasoning> </example>

<example> <label>悪い — ワンライナー</label> <content> プロジェクトを検索します。 </content> <reasoning> 不足：いつ使用するか、いつ使用しないか、パラメータ、戻り値、注意事項。モデルは推測します — そして間違えます。これはツール使用精度が低い #1 の原因です。 </reasoning> </example>

G. 一般的なアンチパターン

これらの衝動を認識して抵抗します：

• 「安全のためにより詳細に追加させてください」 — 過度にエンジニアリングされたプロンプトは過度な分析（Gemini）と過度なトリガー（Claude）を引き起こします。最小限から始めて、観察された失敗のみを修正するものを追加します。
• 「重要：あなたは常に...」 — 積極的な言語は Claude 4.6 でのオーバートリガーと Gemini での過度な分析を引き起こします。穏やか、直接的な指示を使用。
• 「段階的に思考します」 — 推論モデル（GPT o シリーズ、高努力 Claude/Gemini）で有害。思考 API が有効な標準モデルで不要。標準モデルで構造化推論が必要な場合、Step-Back プロンプティング（最初に抽象化、次に推論）は連鎖思考を最大 36% 上回ります。推論モデルの場合、シンプルさが勝ります — ゼロショット最初、必要な場合のみ例を追加。
• 「幻覚しないでください」 — 否定的なフレーミングはより効果的ですが、幻覚は 1 つの問題ではありません。セクション A の「幻覚の削減」を参照してタイプ固有の軽減。短いバージョン：モデルに外部現実（ツール、ドキュメント、検索）に対して主張する前にチェックするよう指示。
• 20+ ツールを追加 — 重複するツールが多すぎることは、すべてのプロバイダー全体で #1 の失敗モード。人間として 2 つのツール間で選択できない場合、モデルもできません。
• API をツールとしてラップ — 1:1 API ツール マッピングを構築する代わりにワークフロー指向のツール。schedule_event（可用性を見つけてスケジュール）は分離した list_users + list_events + create_event に勝ります。
• サブエージェントへの過度な委譲 — Claude 4.6 は直接処理できるタスクのサブエージェントを生成します。タスクに特殊なツールやクリーンなコンテキストが不要な場合、インラインで実行します。
• プロンプト全体を書き直す — 編集時に、既存の構造とトーンを保存。問題を修正する最小限の変更を加える。編集後にプロンプト全体を再読。
• プロンプト考古学の無視 — GPT-4/Claude 3.5 で効果的な指示は、新しいモデルでは逆効果になる可能性があります。モデルをアップグレードする場合、プロンプトを監査して時代遅れの積極的な奨励を確認します — ネイティブ機能は外部の促しを冗長にします。
• すべてのプロバイダーが同じように動作すると仮定 — 彼らはしません。セクション C で指示配置、詳細度のデフォルト、ペルソナ ハンドリング、温度の違いを確認。
• すべての入力を同等に信頼 — 外部データ（ユーザー メッセージ、ツール結果、取得したドキュメント）を指示ではなくコンテキストとして扱わない信頼。デリミタと指示階層（システム > 開発者 > ユーザー）を使用してプロンプト整合性を維持。これはツール結果が敵対的なコンテンツを含む可能性があるエージェント的システムにとって特に重要です。

H. プロンプトのテスト

盲目的に反復しないでください。シンプルな評価を構築：

1. 失敗を特定 — 変更なしでエージェントを代表的なタスクで実行。特定の失敗を注意。
2. 一度に 1 つ修正 — 単一の変更を加え、再テスト、測定。複数の変更をバンドルしないでください。
3. ターゲット モデル ティアでテスト — Opus/GPT-5.4/Gemini Pro で機能するのは Haiku/Mini/Flash に対して、より詳細が必要になる可能性があります。
4. 敵対的な入力を使用 — 空の文字列、予期しない言語、エッジケース、呼ばれるべきではないツール、およびもっともらしい無意味（真のドメイン語彙が一貫性なく組み合わされてフレームワーク名が作られ、領域から概念が間違っている、測定不可能なものの正確な数）。エージェントが破された前提と自信を持ってやり取りするか、押し戻すかテスト。
5. 修正失敗 2 回後 — 反復を停止。学んだレッスンを組み込んだ、より良い初期プロンプトで新しく開始します。
6. プログラム的評価を構築 — エージェントを代表的なテスト ケースで実行、出力を自動的にスコア（LLM-as-judge または完全一致）、プロンプト変更全体でスコアを追跡。ツールの説明で小さな改善は劇的な利益をもたらします — 測定した場合のみ。

評価/判定プロンプトの記述

LLM を出力評価に使用する場合（LLM-as-judge）、プロンプト設計はシステム プロンプトから異なります：

スケール設計：

• バイナリ（合格/不合格）は最も信頼性が高い。3 ポイント スケール（0/1/2）はニュアンスで機能します。詳細なアンカーがない限り 10 ポイント スケールは避けます。
• 各スコア レベルを具体的な例で明示的に定義し、何が適格かを具体化。

構造：

• 複雑な基準を部分基準に分解（G-Eval アプローチ）。スコアを生成する前に、判定が各部分基準を評価するよう要求。
• スコアの後ではなく、理由を最初に必要とします。判定での連鎖思考は無作為を減らします。
• 構造化出力（JSON）をスコアに使用して、解析可能な結果を確保。

キャリブレーション：

• スコア レベルごとに 2-3 の少数ショット例（現実的なエッジケース付き）を提供（+25-30% 精度改善）。
• 決定論的で再現可能なスコアの場合は、低い温度（0.1-0.2）を使用。

バイアスの軽減：

• 位置バイアス：ペア比較で、出力順序をランダム化し、位置全体で平均化。
• 自己設定：異なるモデルを生成者より判定として使用（バイアスを 10-25% 削減）。
• 詳細度バイアス：明示的な長さ制御または罰則を追加。
• ヘッジング バイアス：トーンではなく、ユーザーに対する実際の効果を判定。「応答は破された前提を実際に拒否、またはそれに答える前にエラーを追加しているだけか？」

アンチパターン： 「このレスポンスの品質を 1-10 で評価」のような曖昧な基準は矛盾した結果を生成します。「レスポンスは前提の事実誤認を特定しているか？ トリガーなしで接触した場合は 0 を得点、懸念をフラグしているが依然として答える場合は 1、エラーを中心ポイントにした場合は 2。」のような特定の基準は信頼できる判定を生成します。

テンプレート

${CLAUDE_SKILL_DIR}/templates/ でテンプレートを参照：

• system-prompt-template.md — 契約スタイルのシステム プロンプト構造
• tool-description-template.md — 構造化ツール説明形式