---
title: "プロンプトスタイルガイド"
description: "ThunderPhone音声エージェントのプロンプトを作成・編集する方法。ガイドラインと、プロンプトレビューが参照する検出結果のIDについて説明します。"
---

{/*
  生成ファイル: 手動で編集しないでください。
  ソース: api/agents/prompt_style_guide.md
  再生成: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  CI はこのページを再生成し、差分がある場合は失敗します
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh)。
*/}

<Note>
  これは[プロンプトレビュー](/api-reference/agents#review-a-prompt)がプロンプトを確認する際に使用するガイドであり、
  検出結果では以下の ID が参照されます。[MCP サーバー](/ja/guides/thunderphone-mcp-server)に接続されたコーディング
  エージェントも、リソース `thunderphone://guides/prompt-style` として同じ内容を読み取ります。テンプレートと例については、
  [プロンプト作成ガイド](/ja/guides/prompting)を参照してください。
</Note>

このガイドは、ビルダーの担当者、Copilot、または API 経由で作業するコーディングエージェントなど、音声エージェントのプロンプトを作成または編集するすべての人を対象としています。プロンプトレビュー ツールはこれを評価基準として使用し、ガイドライン ID（P1、W2 など）を参照します。

発信者がエージェントの話を聞けるのは、会話速度で一度だけであり、前に戻って確認することはできません。エージェントはターンごとにプロンプトを読み、その表現を忠実に再現します。この 2 つの事実が、以下のすべての指針の基盤です。

## 構成

**P1. 新しい受付担当者に説明するように書く。** 冒頭で、エージェントが誰で、どの組織のために対応するかを簡潔に示します。その後は、通話の進行順に従います。開始方法、確認すべき内容、確定すべき内容、終了方法の順です。各ルールは、適用される通話の箇所に記載します。読者が各段落について、「この事業を運営する人がこれを入力しただろうか」と問えるようにします。確認すべき内容には、発信者が誰で連絡方法が何かだけでなく、組織が依頼に対応するために必要な情報を含めます。

**P2. 見出しは簡潔にし、その下に本文を書く。** 「担当者について」「通話」「事実」「引き継ぎ」などの見出しは役立ちます。番号付きのルール集、camelCase やコードのような見出し、長いダッシュ箇条書きのルール一覧、冒頭のツールリファレンス、「以下のセクション 4 を参照」のような相互参照といった、機械的な構造は避けてください。エージェントが参照するデータ（営業時間、価格、住所）にはリストを使用して構いません。

**P3. 話し方は一度だけ、簡潔に示す。** 通話全体を通じたエージェントの話し方（短い一人称のターン、温かみのある平易な言葉。「S2」を参照）は、冒頭付近の短い段落にまとめます。特定のステップに関する内容はすべて、そのステップ内に記載します。

**P4. 事実と振る舞いを分ける。** 営業時間、価格、場所、ポリシー、その他の事実は、通話フロー全体に散在させず、プロンプトの事実セクションまたはナレッジベースに記載します。長いカタログや FAQ はナレッジベースに置きます。エージェントが伝えてよいのは、提供された事実のみです。

## 内容

**C1. 台本ではなく、原則と事実を示す。** エージェントが達成しようとしていることと、知る必要があることを説明します。「発信者が X と言ったら、Y と言う」といった分岐、想定される質問への台本化された回答、定型句は含めません。設定した開始時のあいさつが、唯一の台本化された要素です。

**C2. 修正では一般原則を示す。** プロンプトの変更が確認された失敗への対応である場合、その変更では一般原則または不足している事実を追加し、その一件だけに対する応急処置にはしません。失敗した通話の固有情報（名前、番号、正確な発話）はプロンプトに含めません。

**C3. 追加より削除を優先する。** 失敗の原因が、具体的すぎる、広すぎる、または配置が不適切な既存ルールにある場合は、その横に対抗ルールを追加するのではなく、そのルールを変更または削除します。

**C4. 一部はプロンプトではなく設定で決める。** 次はエージェント設定であり、これらに関するプロンプトのテキストは無視されるか、設定と競合します。ツール実行中に発話する内容（ツール開始時の文言、つなぎのフレーズ）、無音時の確認と無音後の最終アクション、復唱のペース、言語切り替えのスタイル、録音に関する通知、エージェントと発信者のどちらが先に話すかです。プロンプトでは結果を示し（「保存する前にメールアドレスを確認する」）、設定で指定します。開始時のあいさつ自体はプロンプトに記述します。

**C5. 例はエージェントが実際に言う文にする。** エージェントは例の表現をほぼそのまま模倣するため、すべての例を完全で自然な話し言葉の文にし、1つだけよりも少数の多様な例を使います。必須の文としてではなく、例として導入します（「たとえば、次のように言えます…」）。「まだ正確ですか？」のように切り詰めたタグは、実際に話すと簡潔すぎる印象になります。

**C6. 自社顧客の通話から例を使わない。** 例では状況の種類を一般的な表現で説明するか、架空の事業者を使います。

**C7. プロンプトは発信者のためのものであり、構築に関するものではありません。** 発信者は公開後にプロンプトの内容をそのまま聞くため、構築、テスト、コンプライアンスの状況に関する注記（「このバージョンはテスト用です」「予約名の「TEST」」「契約に署名されるまで」）は含めません。また、プランを受け入れても何が成立しないか、まだ未確認の内容の要約など、事業者が求めていない免責事項、責任に関する注意書き、終話時の要約も含めません。エージェントは発信者が尋ねた内容に答えて終了し、注意書きが必要な場合は事業者が追加します。不足している情報やシステム上の制限は、それが提供されていないことやリクエストの記録方法に関する注記ではなく、エージェントの動作として記述します（「料金については、オフィスからの折り返し連絡を提案します」）。また、不要な名前や見出しなど、下書きの残りは一切残しません。

## 表現

**W1. 実行内容を、簡潔に、一度だけ伝える。** 望ましい動作を通常の言葉で指示します。「発信者が修正できるよう、注文番号を一桁ずつ読み上げてください。」該当する箇所で一度だけ伝えます。

**W2. 強調しない。** IMPORTANT、NOTE、CRITICAL のラベル、強調のための大文字表記、感嘆符、「悪い例:」と「良い例:」の組み合わせ、してはいけないことのブロックは使用しません。強調のために使う「決して」「常に」「必ず」などの語も同様です。強調はモデルの注意を1つのルールに引き寄せ、通話の他の部分への対応を悪化させます。エージェントが指示を無視する場合は、指示をより明確に、より具体的に、またはより適切な位置に配置します。強調を強くしてはいけません。

**W3. 動作を引き起こす構造を修正する。** エージェントが行うことを禁止するルールを追加する前に、そこへ導く表現や構造を見つけます。たとえば、モデルが文字どおりに埋めるテンプレート、2つの意味を持つ用語、高速なモデルが緩く解釈する if-else 分岐です。それを変更します。

**W4. 一般論より具体的な指示を優先する。** 「空いている最も早い2つの時間を提示してから、どちらが都合よいか尋ねる」は、「予定調整を支援する」より優れています。曖昧な指示は曖昧な動作につながります。

**W5. 質問する前に検索する。** 発信者が読み取り専用の検索ツールで確認できる対象（商品、注文、既存の予約）を示した場合、エージェントは発信者が伝えた言葉で確認し、結果に応じて必要な場合にのみ追加の質問をします。「発信者が指定した商品の在庫を確認し、見つかった内容を伝えてください」は、「ブランド、サイズ、バリエーションを確認してから在庫を確認してください」より優れています。先に確認するよう指示されたエージェントは質問を続け、確認が実行されないためです。これは検索にのみ適用されます。予約、変更、キャンセル、保存を行うツールを使用する前には、エージェントは引き続き発信者に詳細を確認します。

## 発話

**S1. 1ターンにつき質問は1つにし、質問でターンを終える。** 質問の後に発話すると、発信者の回答にかぶります。説明が必要な場合は、質問の前に置きます。

**S2. 短いターンでは、完全な話し言葉の文を使います。** 発信者から詳しい説明を求められない限り、短い文を1～2文にします。
口頭で示す選択肢は少数に限ります。短いとは、文を途中で切ることではなく、語数を少なくすることです。エージェントは優れた
受付担当者が電話で話すように、一人称の完全な文で話します。たとえば、「今すぐ予約をお取りします」や
「月曜日の10時で承りました」のようにします。メモ風の断片（「予約をお取りします。」「完了です。」「承知しました。」）は、
口にするとぶっきらぼうに聞こえます。また、メール調の表現（「ご留意ください…」「恐れ入りますが…」「お役に立てれば幸いです」）は、
話し言葉ではなく読み上げのように聞こえます。プロンプトの話し方に関する段落では、たとえば次のように明確に指示します。「各ターンは
1～2文にし、電話で受付担当者が話すように一人称で話してください。」

**S3. 耳で聞くことを前提に書く。** エージェントが発話する内容では、マークダウン、記号、音声が不自然に読む表記（スラッシュ、アンパサンド、「@」、「.com」、桁区切り、区切りのない電話番号）を避けます。メールアドレスやアカウント番号など、エージェントがツールに渡す事実や値は正確な表記のままにします。それも声に出す必要がある場合は、書き換えるのではなく、その横に読み方を追加します。珍しい名前や頭字語の読み方を明記し、新しい用語は残す前にエージェントの音声で聞きます。

**S4. 間違えると大きなコストになる情報を確認します。** 数字、メールアドレス、住所、コードは、発信者から伝えられた
直後かつ次の質問の前の応答で、伝えられた形式のまま一度復唱します。1回の復唱では1つの値だけを扱います。デフォルトでは名前は
伝えられたとおりに受け取り、復唱しません。エージェントがつづりを尋ねるのは、名前が珍しい場合または不明瞭な場合だけで、尋ねるのは
一度だけです。記録との照合やその名前での予約など、事業者が正確な名前を必要とする場合は、プロンプトでその旨を指定し、エージェントが
名前のつづりを復唱します。復唱は値を修正する機会であり、関門ではありません。発信者が次の詳細を答えたり、修正せずに会話を続けたりした場合、
その値は受け入れられたものとみなされ、再度尋ねられることはありません。事業者が折り返し電話またはSMSを送る電話番号は例外です。その復唱で
ターンを終え、発信者の回答を待ちます。数字を1桁ずつ読むよう求めるプロンプトでは、その方法で読む値（電話番号、コード）のみを指定します。
番地、価格、時刻、日付は、人が通常話す方法で読み上げます。プロンプトで確認する内容を指定し、プラットフォームが復唱のタイミングを調整します。

## 反復

**I1. 変更を残す前にテストする。** 編集したドラフトでエージェントの開発セットを再実行し、現在の
バージョンと比較します。変更によって修正された例と、壊れた例を確認します。発信者が聞くときと同じように
応答を読みます。発信者が気付くことはすべて、細部ではなく問題です。

**I2. ホールドアウトセットは一度だけ確認する。** 調整は開発セットのみで行います。変更の準備ができたらテストセットを実行し、
結果はそのまま報告します。テスト結果を見た後に行った変更には、新しいテスト例が必要です。

**I3. パッチが積み重なったらリファクタリングする。** 多数の小さな修正を重ねたプロンプトは、P1からずれていきます。ルールが
繰り返され、競合し、または対象となるステップから離れた場所に置かれます。その場合は、要求しているすべての動作を維持したまま、
この形に書き直します。各動作について、維持、統合、言い換え、削除のいずれかを記載し、何も黙って削除しません。前後で開発
セットを再実行します。リファクタリングで変えるべきなのは文言であり、動作ではありません。

**I4. プロンプトの前に設定を確認する。** 一部の失敗はプロンプトが原因ではありません。スペルで読み上げた文字の聞き取り間違いは認識の限界によるものです（Plus hearingを試してください）。応答が遅い場合は、知能または認識のティア、あるいはエンドポイント判定の設定が原因の可能性があります。テキストを書き換える前に、設定が原因ではないことを確認してください。
