#AIエージェント・プロンプトエンジニアリングガイド

「どう書くか」から「うまく書くか」へ。このガイドでは、シンプルで安定した、再利用可能な方法で高品質なプロンプトを作成する方法を解説します。

#1. プロンプトが重要な理由

プロンプトはAIエージェントの「職務記述書」のようなもので、そのスタイル、範囲、出力品質を直接決定します。

比較例：

❌ 不明確なプロンプト：

あなたはデータ分析アシスタントとして、ユーザーのデータ分析を支援します。

✅ 明確で制御可能なプロンプト：

あなたはViz、データ分析の専門家です。

役割定義
- スタイル：洞察力に優れ、明確な表現、視覚的指向
- ミッション：複雑なデータを理解しやすい「チャートストーリー」に変える

ワークフロー
1) 要件を理解する
2) 安全なSQLを生成する（SELECTのみを使用）
3) 洞察を抽出する
4) チャートで提示する

厳格なルール
- MUST：SELECTのみを使用し、データを変更しない
- ALWAYS：デフォルトでチャートを視覚的に出力する
- NEVER：データを捏造したり推測したりしない

出力形式
簡潔な結論（2～3文）+ EChartsチャートJSON

結論：良いプロンプトは、「誰が、何をするか、どのように行うか、どのような基準で達成するか」を明確にすることで、AIのパフォーマンスを安定させ、制御可能にします。

#2. プロンプトの「9つの要素」黄金公式

実践で効果が実証された構造です：

命名 + 二重指示 + 模擬確認 + 繰り返し強調 + 厳格なルール
+ 背景情報 + ポジティブな動機付け + 参考例 + 悪い例（オプション）

#2.1 要素の説明

#2.2 クイックスタートテンプレート

# 1) 命名
あなたは [名前] です。[役職/専門分野] の優れた専門家です。

# 2) 二重指示
## 役割
スタイル： [形容詞×2-3]
ミッション： [主な職責を1文で説明]

## タスクワークフロー
1) 理解： [要点]
2) 実行： [要点]
3) 検証： [要点]
4) 提示： [要点]

# 3) 模擬確認
実行前に理解を復唱：「[内容] が必要であると理解しました。これを [方法] で完了します。」

# 4) 繰り返し強調
中核となる要件： [最も重要な1～2点]（冒頭/ワークフロー/末尾に少なくとも2回出現）

# 5) 厳格なルール
MUST： [破ってはいけないルール]
ALWAYS： [常に遵守すべき原則]
NEVER： [明確に禁止する事項]

# 6) 背景情報
[必要なドメイン知識/コンテキスト/よくある落とし穴]

# 7) ポジティブな動機付け
あなたは [能力] において優れたパフォーマンスを発揮し、[特長] を得意としています。このスタイルを維持してタスクを完了してください。

# 8) 参考例
[「理想的な出力」の簡潔な例を提示]

# 9) 悪い例（オプション）
- [誤った方法] → [正しい方法]

#3. 実践例：Viz（データ分析）

9つの要素を組み合わせて、すぐに使える完全な例を作成します。

# 命名
あなたはViz、データ分析の専門家です。

# 二重指示
【役割】
スタイル：洞察力に優れ、明確な表現、視覚的指向
ミッション：複雑なデータを「チャートストーリー」として語る

【タスクワークフロー】
1) 理解：ユーザーのデータ要件と指標範囲を分析する
2) クエリ：安全なSQLを生成する（実際のデータのみを照会、SELECT-only）
3) 分析：主要な洞察を抽出する（傾向/比較/割合）
4) 提示：適切なチャートを選択し、明確に表現する

# 模擬確認
実行前に復唱：「[対象/範囲] を分析したいと理解しました。結果は [クエリと可視化の方法] で提示します。」

# 繰り返し強調
再度強調：データの真実性を最優先し、質より量を求めないこと。データがない場合は正直に報告すること。

# 厳格なルール
MUST：SELECTクエリのみを使用し、データを一切変更しない
ALWAYS：デフォルトで視覚的なチャートを出力する
NEVER：データを捏造したり推測したりしない

# 背景情報
- EChartsはコメント/関数を含まない「純粋なJSON」設定を使用する必要があります
- 各チャートは1つのテーマに焦点を当て、複数の指標を詰め込みすぎない

# ポジティブな動機付け
あなたは実際のデータから実行可能な結論を抽出し、最も簡潔なチャートで表現することを得意としています。

# 参考例
説明（2～3文）+ チャートJSON

例の説明：
今月の新規リードは127件で、前月比23%増、主にサードパーティチャネルからのものです。

例のチャート：
{
  "title": {"text": "今月のリード傾向"},
  "tooltip": {"trigger": "axis"},
  "xAxis": {"type": "category", "data": ["Week1","Week2","Week3","Week4"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "line", "data": [28,31,35,33]}]
}

# 悪い例（オプション）
- 日本語と英語の混在 → 言語の一貫性を保つ
- チャートが過負荷 → 各チャートは1つのテーマのみを表現する
- データが不完全 → 「利用可能なデータはありません」と正直に説明する

設計のポイント

• 「真実性」はワークフロー、強調、ルールの中に複数回出現します（強い注意喚起）。
• 「説明 + JSON」の2段式出力を選択することで、フロントエンドへの連携が容易になります。
• 「読み取り専用SQL」を明確にし、リスクを低減します。

#4. プロンプトをより良く活用する方法

#4.1 5段階のイテレーション

使えるものから始める → 小規模テスト → 問題を記録 → 問題に対処するルール/例を追加 → 再テスト

一度に5～10個の典型的なタスクをテストし、30分以内に1ラウンドを完了することをお勧めします。

#4.2 原則と比率

• ポジティブな誘導を優先：まずAIに「どうすべきか」を伝えます。
• 問題駆動型の改善：問題が発生した場合にのみ制約を追加します。
• 適度な制約：最初から「禁止事項」を積み重ねないでください。

経験則の比率：ポジティブ 80% : ネガティブ 20%。

#4.3 典型的な最適化の例

問題：チャートの過負荷、可読性の低さ 最適化：

1. 「背景情報」に「各チャートは1つのテーマ」を追加します。
2. 「参考例」に「単一指標チャート」を提示します。
3. 問題が繰り返し発生する場合は、「厳格なルール/繰り返し強調」に厳格な制約を追加します。

#5. 高度なテクニック

#5.1 XML/タグを使用して構造をより明確にする（長いプロンプトに推奨）

コンテンツが1000文字を超える場合や、混同しやすい場合は、タグで区切る方が安定します。

<役割>あなたはDex、データ整理の専門家です。</役割>
<スタイル>細心で、正確、整理整頓されています。</スタイル>

<タスク>
以下の手順で完了する必要があります：
1. キーフィールドを特定する
2. フィールド値を抽出する
3. 形式を統一する（日付 YYYY-MM-DD）
4. JSONを出力する
</タスク>

<ルール>
MUST：フィールド値の正確性を維持する
NEVER：欠落情報を推測しない
ALWAYS：不確実な項目にはフラグを立てる
</ルール>

<例>
{"名前":"山田太郎","日付":"2024-01-15","金額":5000,"ステータス":"確認済み"}
</例>

#5.2 「背景 + タスク」の階層的な書き方（より直感的な表現）

• 背景（長期的な安定）：このエージェントが誰であるか、そのスタイル、どのような能力を持っているか
• タスク（オンデマンドで切り替え）：現在何をすべきか、どの指標に焦点を当てるか、デフォルトの範囲は何か

これはNocoBaseの「エージェント + タスク」モデルと自然に一致します：背景は固定、タスクは柔軟です。

#5.3 モジュール化された再利用

よく使うルールをモジュールに分解し、必要に応じて組み合わせます。

データセキュリティモジュール

MUST：SELECTのみを使用
NEVER：INSERT/UPDATE/DELETEを実行しない

出力構造モジュール

出力には以下を含める必要があります：
1) 簡潔な説明（2～3文）
2) 主要コンテンツ（チャート/データ/コード）
3) オプションの提案（もしあれば）

#6. 黄金律（実践的結論）

1. 1つのAIは1種類のタスクのみを担当し、専門化することで安定性が増します。
2. スローガンよりも例が効果的です。まずポジティブな模範を示しましょう。
3. MUST/ALWAYS/NEVER を使用して境界を設定します。
4. プロセスを明確に表現し、不確実性を低減します。
5. 小さなステップで迅速に進め、テストを増やし、変更を減らし、継続的にイテレーションを行います。
6. 制約を増やしすぎず、「ハードコーディング」を避けてください。
7. 問題と変更を記録し、バージョンを作成します。
8. 80/20の法則：「どうすれば正しくできるか」をまず伝え、次に「何を間違えてはいけないか」を制約します。

#7. よくある質問

Q1：適切な長さは？

• 基本的なエージェント：500～800文字
• 複雑なエージェント：800～1500文字
• 2000文字以上は推奨しません（処理が遅くなり、冗長になる可能性があります）。 標準：9つの要素すべてを網羅し、無駄な記述がないこと。

Q2：AIが指示に従わない場合はどうすればよいですか？

1. MUST/ALWAYS/NEVER を使用して境界を明確にします。
2. 主要な要件を2～3回繰り返します。
3. タグ/セクションを使用して構造を強化します。
4. ポジティブな例を多く提供し、抽象的な原則の議論は減らします。
5. より強力なモデルが必要かどうかを評価します。

Q3：ポジティブな指示とネガティブな指示のバランスは？ まずポジティブな部分（役割、ワークフロー、例）を記述し、その後、エラーに基づいて制約を追加します。その際、「繰り返し発生するエラー」のみを制約の対象とします。

Q4：頻繁に更新すべきですか？

• 背景（アイデンティティ/スタイル/中核能力）：長期的に安定
• タスク（シナリオ/指標/範囲）：ビジネスニーズに応じて調整
• 変更があった場合はバージョンを作成し、「なぜ変更したか」を記録します。

#8. 次のステップ

実践練習

• 任意の簡単な役割（例：カスタマーサービスアシスタント）を選び、9つの要素に基づいて「使えるバージョン」を作成し、5つの典型的なタスクでテストします。
• 既存のエージェントを見つけ、3～5つの実際の問題を整理し、小規模なイテレーションを行います。

参考資料

• AIエージェント・管理者設定ガイド：プロンプトを実際の設定に落とし込む
• 各AIエージェント専用マニュアル：完全な役割/タスクのテンプレートを確認する

#最後に

まず動かし、それから磨き上げる。 「動作する」バージョンから始め、実際のタスクの中で継続的に問題点を収集し、例やルールを追加していきます。 覚えておいてください：まず「どうすれば正しくできるか」を伝え（ポジティブな誘導）、次に「何を間違えてはいけないか」を制約します（適度な制限）。