ClaudeでAPIエンドポイントを構築：70以上のエンドポイントプロジェクトから得た実践的プロンプトエンジニアリングの教訓

アクション実行エージェントのための実践的プロンプトエンジニアリング

70以上のエンドポイント、サーバーサイド実行、Chrome拡張機能認証を備えたLinkedIn自動化APIを構築した開発者は、Claudeを使用してコードの約80％を記述しました。このプロジェクトから、API呼び出し、データ抽出、意思決定ツリーなどのアクションを実行するエージェントと、チャットのみを行うエージェントに対するプロンプト構造に関する具体的な教訓が明らかになりました。

プロンプトへの契約的アプローチ

開発者は、「LinkedInで関連性のあるリードを見つけ、パーソナライズされた接続リクエストを送信する」といった自然言語の指示では問題が生じることを発見しました：Claudeはフィールドを幻覚させ、検証をスキップし、不要なAPI呼び出しを連鎖させることがありました。効果的だったのは、すべてのエージェントプロンプトを明示的な制約を持つ関数シグネチャのように扱うことでした：

• 入力： エージェントが受け取る正確な内容（スキーマ、タイプ、エッジケース）
• 境界： エージェントがしてはならないこと（代替推測なし、フィールドのスキップなし、データの捏造なし）
• 出力契約： エラー状態を含む、返されるデータの正確な形状
• 意思決定ルール： XならばY、Zならば停止 — 曖昧さなし

得られた具体的な教訓

「創造的であれ」はアクションエージェントにとって問題： アクション実行プロンプトに解釈の余地を残すたびに、Claudeは予期しない結果を生み出しました。実際のアクションを実行するエージェントにとっては、創造性ゼロが望ましく、創造性はコンテンツ生成タスクのために温存すべきです。

エラー処理は必須： プロンプトトークンの約40％が「問題が発生したときの対処方法」に割り当てられました。これがないと、Claudeは無限に再試行するか、エラーを黙って飲み込み、すべてが正常であるかのように部分的なデータを返していました。

連鎖思考のトレードオフ： すべてのエージェントにアクションの前に推論ステップを出力させることは、約15％多くのトークンを消費しますが、デバッグ時間を節約します。何かが壊れたとき、開発者はエージェントがその決定を下した正確な理由を読むことができます。

ペルソナプロンプトよりもパターンマッチング： 「あなたはシニアエンジニアです」といったプロンプトを使用する代わりに、開発者は良好な出力の実際の例を貼り付け、「このパターンに正確に一致させてください」と指示します。Claudeはロールプレイよりもパターンマッチングで優れたパフォーマンスを発揮します。

モデル選択戦略： 単純な抽出とフォーマットタスクはSonnet（またはHaiku）にルーティングされ、複雑な意思決定のみがOpusを使用します。このアプローチにより、APIコストは苦痛から管理可能なレベルに削減されました。ほとんどのエージェントタスクはOpusを必要としないためです。