Claude AI実行エージェントのための実用的なプロンプト構造

実行エージェントのためのプロンプトエンジニアリング

API呼び出し、データ抽出、マルチステップ意思決定ツリー、エラー回復など、実際のアクションを実行するClaude AIエージェントを数ヶ月間構築してきた開発者が、持続的な幻覚問題を解決したプロンプト構造を共有。初期の試みでは、エージェントがフィールドを幻覚し、不要なAPI呼び出しを連鎖させ、エラーを黙って飲み込み、すべてが正常であるかのように部分的なデータを返す結果になりました。

主要なプロンプト構造の原則

• プロンプトは指示ではなく契約のように書く:「関連するリードを見つけてパーソナライズされたメッセージを送信する」などの自然言語プロンプトは即興を招きます。効果的な方法：入力（正確なスキーマ、タイプ、エッジケース）、出力（エラー状態を含む正確な形状）、決定ルール（XならY、Zなら停止）を定義します。
• プロンプトトークンの40％をエラーハンドリングに割り当てる: 明示的なエラーパスがないと、Claudeは無限に再試行するか、黙って無意味な結果を返します。すべての可能な失敗モードには独自の指示が必要です：APIが429を返したときの対処、必須フィールドが欠けているときの対処、データが曖昧に見えるときの対処。
• 「待機」と「停止」を分ける: Cludeは「まだ行動するのに十分な情報がない」と「情報が悪いので中止」を区別できません。両方のケースを明確に指示する必要があります。あるエージェントは曖昧なデータで一時停止するはずでしたが、代わりに100％クリーンでないものはすべてスキップしていました。両方の状態に対する明示的な指示を追加することで、精度が一夜にして向上しました。
• 役割演技よりもパターンマッチング: 「あなたはシニアエンジニアです」という設定は実行品質にほとんど影響しません。実際の良い出力例を貼り付け、「このパターンに正確に一致させてください」と言う方が10倍効果的です。Claudeは抽象的なペルソナを解釈するよりも、具体的な例を再現する方が得意です。
• 習慣ではなく複雑さでルーティングする: コンテキストとエッジケースが重要なマルチステップ意思決定にはOpusを独占的に使用。それ以外はすべてSonnetまたはHaikuに。ほとんどのエージェントタスクはOpusを必要とせず、コスト差は急速に蓄積します。適切なルーティングにより、APIコストは過酷なものから管理可能なものに変わりました。
• すべてのアクションの前に連鎖思考を強制する: これは約15％多くのトークンがかかりますが、深夜2時に何かが壊れたとき、エージェントがその行動を決定した正確な理由を読むことができます。これがないと、暗闇でのデバッグになります。

開発者は、このプロンプト構造は、実際のアクションを実行するエージェント（単なるテキスト生成ではない）を構築する際に、モデル選択よりもはるかに重要であると指摘しています。