本番環境で失敗しないAIエージェント・システムプロンプトの書き方

目次

2026年7月更新。

TL;DR: 本番環境のシステムプロンプトには5つのレイヤーがある：アイデンティティ（エージェントが誰で何をしてはいけないか）、コンテキスト（環境について何を知っているか）、タスク（成功がステップごとにどう見えるか）、出力フォーマット（最も過小評価されているレイヤー）、エッジケース（入力が失敗したときの対処法）。ほとんどのプロンプトはレイヤー4と5を省略するから失敗する。出力フォーマットを最初に書くことで、本当に何が欲しいかを正確に考えることができる。

[オペレーターの視点] 私はコンサルティングブランドとPickleland（テキサス州プフルーガービルのピックルボール施設）で30以上のAIエージェントを本番稼働させている。書いたシステムプロンプトより書き直したものの方が多い。最初のバージョンはテストでは良さそうに見えて、本番では静かに劣化するのが常だ。これは、長持ちするプロンプトの書き方について学んだことだ。

誰も認めないシステムプロンプトの問題

ほとんどのエージェント・システムプロンプトは約20分で書かれ、2〜3の例でテストされ、その後二度と触られない。モデルはリリースされる。しばらくはうまくいく。そして何かが変わる——入力がより乱雑になり、モデルが更新され、新しいエッジケースが現れる——エージェントはガベージを生成し始める。静かに。スケールして。

問題は元のプロンプトが悪かったわけではない。ほとんどのプロンプトはハッピーパスを実証するために書かれている。エージェントを構築したときに想定していた入力のために設計されており、エージェントが実際に見る入力の完全な分布のためではない。

本番システムプロンプトの5つのレイヤー

私が書くすべてのシステムプロンプトを5つのレイヤーで考える。この順序で表示される必要はないが、すべて存在しなければならない。

レイヤー1：アイデンティティ

アイデンティティは、モデルに自分が誰で、どんな運用上の制約があるかを伝える。ロールプレイキャラクターではなく、このエージェントが何をして何をしないかの機能的定義だ。

強いアイデンティティレイヤーは3つの質問に答える：

• このエージェントは何に責任を持つか？
• 明示的に責任を持ないのは何か（エスカレートするか拒否すべきか）？
• どんな基準を守るか？

「しない」スコープの明示的な部分は、ほとんどのオペレーターが省略する部分だ。それがないと、モデルは管轄外で役に立とうとする——そしてそこで問題が起きる。

レイヤー2：コンテキスト

コンテキストは、ユーザーのメッセージにはないが、エージェントが自分の環境について知っていることだ。これには現在の日付と時刻（動的に注入する——モデルの内部時間感覚は信用しない）、外部システムからの関連状態、タスクの説明からは明らかでないビジネスルールが含まれる。

私がレビューするほとんどのエージェントはコンテキストが不足している。想定するな。注入せよ。

レイヤー3：タスク

タスクレイヤーはエージェントが何をステップごとに行うかを記述する。「顧客を助ける」ではなく——実際の意思決定フローだ。指示としてではなくフローチャートとして書く。フローチャートの方が堅牢で、あいまいなケースでモデルが何を望んでいるか推測する必要が減る。

レイヤー4：出力フォーマット

これが最も過小評価されているレイヤーで、サイレントな失敗に最も責任があるものだ。

出力フォーマットを正確に指定しないと、モデルは人間の読者には正しく見えるが、下流の解析を壊すほど一貫性のない出力を生成する。出力フォーマットを最初に書く。構造化出力には正確なスキーマを指定する。散文出力には構造、長さ、トーンの制約を指定する。

高リスクのエージェントには、定義されたJSONスキーマでClaudeの構造化出力を使用する。

レイヤー5：エッジケース

エッジケースレイヤーは答える：入力があいまい、不完全、間違った言語、敵対的、または明らかに間違っている場合にエージェントは何をするか？各エッジケースに対して、明示的な応答パスをモデルに与える。

時間をかけてシステムプロンプトをどうメンテナンスするか

本番システムプロンプトは生きたドキュメントだ：

1. 週次スポットチェック。 各高リスクエージェントの5〜10のランダムな出力を期待される出力と照らし合わせてレビューする。
2. モデルアップデート後のレビュー。 基盤モデルのバージョンが変わるたびに、評価フレームワークのゴールデンセット全体に対してエージェントを実行する。
3. エッジケースログ。 エージェントがうまく処理できなかった入力の継続的なログを維持する。3つ以上のエントリがパターンを共有する場合、明示的なルールを追加する。
4. プロンプトバージョニング。 重要な変更はすべてプロンプトファイルの先頭にバージョンコメントを付ける。

よくある質問

本番システムプロンプトはどのくらいの長さにすべきか？

5つのレイヤーをすべてカバーするのに十分な長さ。2分で読んでドリフトを見つけられるほど短い長さ。ほとんどのエージェントで200〜600ワードだ。

複数のエージェントに分割すべきのはいつか？

タスクに、異なるコンテキスト、異なる出力フォーマット、または異なるエラー処理を必要とする2つ以上の明確に異なるモードがある場合。パターンについてはイベントトリガーと定期実行エージェントを参照。

テストで機能したプロンプトが本番で失敗する最も一般的な理由は何か？

テスト入力が本番の分布を代表していなかった。想像上の入力ではなく、実際の本番トラフィックからテストセットを構築する。

プロンプトとコードのどちらを更新すべきかをどう判断するか？

エージェントが間違った出力フォーマットを生成している場合はプロンプトを更新。エージェントが正しい出力を生成しているが下流システムが使えない場合はコードを更新。エージェントが自信を持って間違った事実を生成している場合はまずコンテキストレイヤーを確認する。