writing-system-prompts

LLM システムプロンプトの作成

適切に構成されたシステムプロンプトは、会話全体を通じて振る舞いを導きます。また、KV キャッシュの再利用を考慮して構成すれば、プロンプトキャッシュに対応しているプロバイダー（Anthropic、OpenAI、Bedrock、Vertex など）では、キャッシュされていないプレフィックスと比べて、コストを大幅に抑えられます。

ルール

1. 役割を最初に、1 文で記述します。 システムフィールドに置く説明的な 1 文（ユーザーのターンではありません）で、口調や語彙を定めます。例：You are a helpful coding assistant specializing in Python. 先頭には通常の文章を置き、マークアップで囲まないでください。

2. 静的な内容を先に、動的な内容を最後に配置します。 キャッシュヒットには、バイト単位で同一のプレフィックスが必要です。順序は、役割 → ツール／ポリシー → 長い参考資料／少数例の例示 → キャッシュブレークポイント → 動的なコンテキスト → ユーザーのターンです。理由： ブレークポイントより前でトークンが 1 つ変わるだけで、キャッシュ読み取り料金（入力料金のおよそ 10％）ではなく、入力全体の料金が適用されます。

3. プロバイダーが対応している場合は、キャッシュブレークポイントを明示的に設定します。 ほとんどのキャッシュ機能はオプトインが必要です（例：Anthropic の cache_control、Bedrock の cachePoint）。再利用する安定したブロックの末尾にブレークポイントを置きます。キャッシュへの書き込みは通常、基本の入力料金より高く、読み取りはその一部の料金です。TTL はさまざまですが、一般的には約 5 分で、より長い階層が用意されている場合もあります。TTL 内に再利用するプレフィックスだけをキャッシュしてください。リクエストが少ないと、書き込み料金が繰り返し発生します。

   # Anthropic example — adapt to your provider's syntax
   system=[
       {"type": "text", "text": ROLE_AND_POLICIES},
       {"type": "text", "text": LONG_REFERENCE_DOC,
        "cache_control": {"type": "ephemeral"}},
   ]
   

4. 変化の多い内容をプレフィックスに置かないでください。 現在時刻、リクエスト ID、ユーザー ID、会話の要約を先頭に置くと、プロンプト全体のキャッシュが無効になります。ブレークポイントより後に配置してください。日付や ID などの確定的な情報は 2 つ目のシステムメッセージに、質問や文書などのタスク資料はユーザーのターンに置きます。どちらの方法でも、キャッシュを同じように再利用できます。

5. セクションごとに構造的な区切りを使います。 長文の入力や振る舞いに関する指示は、明確な区切りで囲みます。XML タグ（<documents><document>…</document></documents>、<default_to_action>…</default_to_action>）、Markdown の見出し、名前付き JSON フィールドなどを使ってください。理由： 区切られたセクションは、文章が連なるだけの場合よりも長いコンテキストの中で維持されやすく、いくつかのモデルファミリー（特に Claude）は XML 構造を明示的に学習しています。

6. ユーザーのターンでは、指示より前に長文データを配置します。 20k トークン以上の入力では、文書を先頭に、質問を末尾に置きます。主要なモデルで複数文書を扱うタスクを評価したところ、品質が最大 30％向上しました。

7. 具体的で、適用範囲を明確にした指示を書きます。 最新の指示追従型モデルは、プロンプトをますます文字どおりに解釈し、暗黙の一般化はしません。ルールを広く適用する場合は、その旨を明記してください。例：Apply this formatting to every section, not just the first one. 大文字だけで強調する表現（CRITICAL、MUST）は避けてください。最近の Claude モデルでは過剰反応を引き起こし、他のモデルでは効果がほとんどありません。通常の命令形を使ってください。

8. 既定の振る舞いに問題がある場合に限り、簡潔さ、口調、ツールの使用、サブエージェントの起動を調整します。 例：Provide concise, focused responses. Skip non-essential context. ／ Use a warm, collaborative tone. ／ Spawn multiple subagents in the same turn when fanning out across items. Do not spawn a subagent for work you can complete in a single response. 問題を確認してから既定の振る舞いを上書きしてください。先回りして上書きしないでください。

検証手順

作成または編集した後、各項目を確認してください。

1. 役割の確認 — システムフィールドの最上部に、役割を示す 1 文がありますか？
2. キャッシュ順序の確認 — セグメントを上から順に並べたとき、ブレークポイントより前のすべてのセグメントはリクエスト間で安定していますか？ リクエストごとに変わる値は、ブレークポイントより後（2 つ目のシステムメッセージまたはユーザーのターン）に移してください。
3. ブレークポイントの確認 — ブレークポイントは最後の静的ブロックにありますか？ キャッシュされるプレフィックスはプロバイダーの最小トークン数を超えていますか（例：Anthropic の Opus／Sonnet は 1024 トークン、Haiku は 2048 トークン、OpenAI は 1024 トークン）？ 最小数を下回ると、ブレークポイントは通知なく無視されます。
4. 構造の確認 — 長文の文書は区切りで囲まれていますか？ 振る舞いに関するブロックは、名前付きのタグまたはセクションで示されていますか？
5. 文字どおりの解釈への配慮の確認 — 指示に「出力を整形する」と書いていても、「すべてのセクションを整形する」という意味なら、適用範囲が明確になるように書き直してください。

よくある注意点

• 先頭のタイムスタンプ。 ロール行にある Current date: {{today}} により、リクエストのたびにキャッシュが無効になります。ブレークポイントを後ろに移動し、2つ目のシステムメッセージまたはユーザーターンに置いてください。
• 短すぎるプレフィックスのキャッシュ。 プロバイダーの最小要件を下回る短いシステムプロンプトでは、ブレークポイントが無視されても気付かず、書き込みの追加料金が発生します。キャッシュするブロックを大きくするか、ブレークポイントを削除してください。
• ブレークポイントより前にある会話履歴。 履歴はリクエストのたびに増えるため、その後にあるものはキャッシュできません。ブレークポイントを、増え続ける履歴の前に置いてください。
• 古い CRITICAL: YOU MUST… のコピー＆ペーストによる強い指示。 最近のモデルでは過剰なトリガーを引き起こします。通常の命令形に書き換えてください。
• ユーザーメッセージ内のロール。 システムフィールドではなく messages[0] に You are a… と記述すると、誘導の効果が弱まり、キャッシュ可能な枠を無駄にします。