customaize-agent:prompt-engineering

プロンプトエンジニアリングのパターン

LLM のパフォーマンス、信頼性、制御性を最大化するための高度なプロンプトエンジニアリング手法です。

主な機能

1. Few-Shot 学習

ルールを説明する代わりに、例を示してモデルに学習させます。望ましい動作を示す入出力ペアを2〜5組含めます。一貫したフォーマット、特定の推論パターン、またはエッジケースへの対応が必要な場合に使用します。例を増やすと精度が向上しますが、トークンを消費するため、タスクの複雑さに応じて調整してください。

例：

Extract key information from support tickets:

Input: "My login doesn't work and I keep getting error 403"
Output: {"issue": "authentication", "error_code": "403", "priority": "high"}

Input: "Feature request: add dark mode to settings"
Output: {"issue": "feature_request", "error_code": null, "priority": "low"}

Now process: "Can't upload files larger than 10MB, getting timeout"

2. Chain-of-Thought プロンプティング

最終的な回答の前に、段階的な推論を求めます。「一歩ずつ考えてみましょう」（ゼロショット）を追加するか、推論の例を含めます（Few-Shot）。多段階の論理や数学的推論が必要な複雑な問題、またはモデルの思考プロセスを検証したい場合に使用します。分析タスクの精度が30〜50％向上します。

例：

Analyze this bug report and determine root cause.

Think step by step:
1. What is the expected behavior?
2. What is the actual behavior?
3. What changed recently that could cause this?
4. What components are involved?
5. What is the most likely root cause?

Bug: "Users can't save drafts after the cache update deployed yesterday"

3. プロンプトの最適化

テストと改善を通じて、プロンプトを体系的に改良します。シンプルなものから始め、パフォーマンス（精度、一貫性、トークン使用量）を測定してから反復します。エッジケースを含む多様な入力でテストします。バリエーションを比較するには A/B テストを使用します。一貫性とコストが重要となる本番環境のプロンプトでは欠かせません。

例：

Version 1 (Simple): "Summarize this article"
→ Result: Inconsistent length, misses key points

Version 2 (Add constraints): "Summarize in 3 bullet points"
→ Result: Better structure, but still misses nuance

Version 3 (Add reasoning): "Identify the 3 main findings, then summarize each"
→ Result: Consistent, accurate, captures key information

4. テンプレートシステム

変数、条件付きセクション、モジュール式コンポーネントを備えた再利用可能なプロンプト構造を構築します。複数ターンの会話、役割に基づくやり取り、または異なる入力に同じパターンを適用できる場合に使用します。重複を減らし、類似タスク間の一貫性を確保します。

例：

# Reusable code review template
template = """
Review this {language} code for {focus_area}.

Code:
{code_block}

Provide feedback on:
{checklist}
"""

# Usage
prompt = template.format(
    language="Python",
    focus_area="security vulnerabilities",
    code_block=user_code,
    checklist="1. SQL injection\n2. XSS risks\n3. Authentication"
)

5. システムプロンプトの設計

会話全体を通じて維持される全体的な動作と制約を設定します。モデルの役割、専門知識のレベル、出力形式、安全ガイドラインを定義します。ターンごとに変えるべきではない安定した指示にはシステムプロンプトを使用し、ユーザーメッセージのトークンを可変コンテンツに充てられるようにします。

例：

System: You are a senior backend engineer specializing in API design.

Rules:
- Always consider scalability and performance
- Suggest RESTful patterns by default
- Flag security concerns immediately
- Provide code examples in Python
- Use early return pattern

Format responses as:
1. Analysis
2. Recommendation
3. Code example
4. Trade-offs

主なパターン

段階的な情報開示

シンプルなプロンプトから始め、必要な場合にのみ複雑さを加えます。

1. レベル 1：直接的な指示

   • 「この記事を要約してください」

2. レベル 2：制約を追加

   • 「この記事を、主な調査結果に焦点を当てて、箇条書き3点で要約してください」

3. レベル 3：推論を追加

   • 「この記事を読み、主な調査結果を特定してから、箇条書き3点で要約してください」

4. レベル 4：例を追加

   • 入出力ペアを含む要約例を2〜3件追加します

指示の優先順位

[System Context] → [Task Instruction] → [Examples] → [Input Data] → [Output Format]

エラーからの回復

失敗に適切に対処できるプロンプトを作成します。

• フォールバック指示を含めます
• 確信度スコアを求めます
• 不確かな場合は別の解釈を尋ねます
• 情報が不足している場合の示し方を指定します

ベストプラクティス

1. 具体的にする：曖昧なプロンプトでは結果に一貫性がなくなります
2. 説明するより、例を示す：例は説明よりも効果的です
3. 十分にテストする：多様で代表的な入力を使って評価します
4. 素早く反復する：小さな変更が大きな影響をもたらすことがあります
5. パフォーマンスを監視する：本番環境でメトリクスを追跡します
6. バージョン管理する：適切なバージョン管理を行い、プロンプトをコードとして扱います
7. 意図を文書化する：プロンプトがそのような構成になっている理由を説明します

よくある落とし穴

• 過剰な設計：シンプルなプロンプトを試す前に、複雑なプロンプトから始めること
• 例の混入：対象タスクに合わない例を使用すること
• コンテキストの超過：例を入れすぎてトークン上限を超えること
• 曖昧な指示：複数の解釈ができる余地を残すこと
• エッジケースの無視：特殊な入力や境界値の入力でテストしないこと

統合パターン

RAG システムとの統合

# Combine retrieved context with prompt engineering
prompt = f"""Given the following context:
{retrieved_context}

{few_shot_examples}

Question: {user_question}

Provide a detailed answer based solely on the context above. If the context doesn't contain enough information, explicitly state what's missing."""

検証との統合

# Add self-verification step
prompt = f"""{main_task_prompt}

After generating your response, verify it meets these criteria:
1. Answers the question directly
2. Uses only information from provided context
3. Cites specific sources
4. Acknowledges any uncertainty

If verification fails, revise your response."""

パフォーマンスの最適化

トークン効率

• 冗長な単語やフレーズを削除します
• 初出時に定義した略語を一貫して使用します
• 類似した指示をまとめます
• 安定したコンテンツはシステムプロンプトに移します

レイテンシの削減

• 品質を犠牲にせずにプロンプトの長さを最小化する
• 長文の出力にはストリーミングを使用する
• よく使われるプロンプトのプレフィックスをキャッシュする
• 可能な場合は類似したリクエストをバッチ処理する

---

エージェントプロンプトのベストプラクティス

Anthropic の公式エージェントプロンプトのベストプラクティスに基づいています。

中核となる原則

コンテキストウィンドウ

「コンテキストウィンドウ」とは、言語モデルが新しいテキストを生成する際に参照および遡って確認できるテキストの総量と、生成する新しいテキストを合わせたものを指します。これは言語モデルが学習した大規模なデータコーパスとは異なり、モデルにとっての「ワーキングメモリ」を表します。コンテキストウィンドウが大きいほど、モデルはより複雑で長いプロンプトを理解して応答できますが、コンテキストウィンドウが小さいと、長いプロンプトの処理や長い会話での一貫性の維持が制限される場合があります。

• 段階的なトークンの蓄積: 会話がターンを経て進むにつれて、各ユーザーメッセージとアシスタントの応答がコンテキストウィンドウ内に蓄積されます。以前のターンは完全に保持されます。
• 線形の増加パターン: コンテキストの使用量は各ターンごとに線形に増加し、以前のターンは完全に保持されます。
• 200K トークンの容量: 利用可能なコンテキストウィンドウの総量（200,000 トークン）は、会話履歴の保存と Claude からの新しい出力の生成における最大容量を表します。
• 入力と出力の流れ: 各ターンは次で構成されます:
  • 入力フェーズ: 以前のすべての会話履歴と現在のユーザーメッセージを含みます
  • 出力フェーズ: 将来の入力の一部となるテキスト応答を生成します

簡潔さが鍵

コンテキストウィンドウは公共の資源です。あなたのプロンプト、コマンド、スキルは、Claude が知る必要のある他のすべてとコンテキストウィンドウを共有します。それには次が含まれます:

• システムプロンプト
• 会話履歴
• その他のコマンド、スキル、フック、メタデータ
• あなたの実際のリクエスト

デフォルトの前提: Claude はすでにとても賢い

Claude がすでに持っていないコンテキストだけを追加してください。情報の各断片について次を問いかけてください:

• 「Claude は本当にこの説明を必要としているか？」
• 「Claude がこれを知っていると仮定できるか？」
• 「この段落はそのトークンコストに見合うか？」

良い例: 簡潔（約 50 トークン）:

## Extract PDF text

Use pdfplumber for text extraction:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

悪い例: 冗長すぎる（約 150 トークン）:

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

簡潔なバージョンは、Claude が PDF とは何か、ライブラリがどのように動作するかを知っていると仮定しています。

適切な自由度を設定する

タスクの脆弱性と変動性に合わせて、具体性のレベルを調整してください。

高い自由度（テキストベースの指示）:

次に使用します:

• 複数のアプローチが有効な場合
• 判断がコンテキストに依存する場合
• ヒューリスティックがアプローチを導く場合

例:

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

中程度の自由度（疑似コードまたはパラメータ付きスクリプト）:

次に使用します:

• 推奨されるパターンが存在する場合
• ある程度の変動が許容される場合
• 設定が動作に影響する場合

例:

## Generate report

Use this template and customize as needed:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
```

低い自由度（特定のスクリプト、パラメータが少ないか存在しない）:

次に使用します:

• 操作が脆弱でエラーが発生しやすい場合
• 一貫性が重要な場合
• 特定の順序に従う必要がある場合

例:

## Database migration

Run exactly this script:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.

たとえ: Claude を道を探索するロボットだと考えてください:

• 両側が崖になっている狭い橋: 安全に前に進む方法は 1 つだけです。具体的なガードレールと正確な指示を提供してください（低い自由度）。例: 正確な順序で実行する必要があるデータベースマイグレーション。
• 危険のない広い野原: 多くの道が成功につながります。一般的な方向性を与え、最適なルートを見つけることを Claude に任せてください（高い自由度）。例: コンテキストが最適なアプローチを決定するコードレビュー。

エージェントコミュニケーションのための説得の原則

プロンプトの作成に役立ちます。これには以下が含まれますが、それに限定されません: Claude Code のコマンド、フック、スキル、またはサブエージェントやその他の LLM インタラクションのためのプロンプト。

概要

LLM は人間と同じ説得の原則に反応します。この心理を理解すると、より効果的なスキルを設計できます。操作するためではなく、プレッシャーがかかる状況でも重要な実践が確実に守られるようにするためです。

研究の根拠： Meincke et al. (2025) は、N=28,000 件の AI との会話を対象に、7 つの説得の原則を検証しました。説得のテクニックにより、指示への従順率は 2 倍以上に上昇しました（33% → 72%、p < .001）。

7 つの原則

1. 権威

概要： 専門知識、資格、公式な情報源に従うことです。

プロンプトでの効果：

• 命令形の表現：「必ず実行してください」、「決して〜しないでください」、「常に〜してください」
• 交渉の余地がないことを示す表現：「例外はありません」
• 意思決定による疲労や、正当化を排除します

使用する場面：

• 規律を徹底するスキル（TDD、検証要件）
• 安全性が特に重要な実践
• 確立されたベストプラクティス

例：

✅ Write code before test? Delete it. Start over. No exceptions.
❌ Consider writing tests first when feasible.

2. コミットメント

概要： 以前の行動、発言、公の宣言との一貫性です。

プロンプトでの効果：

• 宣言を求めます：「スキルの使用を宣言してください」
• 明確な選択を促します：「A、B、C のいずれかを選択してください」
• 追跡機能を使用します：チェックリストには TodoWrite を使用します

使用する場面：

• スキルが実際に守られていることを確実にする
• 複数ステップのプロセス
• 説明責任の仕組み

例：

✅ When you find a skill, you MUST announce: "I'm using [Skill Name]"
❌ Consider letting your partner know which skill you're using.

3. 希少性

概要： 時間制限や入手可能性の制限によって生じる緊急性です。

プロンプトでの効果：

• 期限を設けた要件：「先に進む前に」
• 順序に依存する要件：「X の直後に」
• 先延ばしを防ぎます

使用する場面：

• ただちに検証する必要がある場合
• 時間制約のあるワークフロー
• 「後でやろう」を防ぐ場合

例：

✅ After completing a task, IMMEDIATELY request code review before proceeding.
❌ You can review code when convenient.

4. 社会的証明

概要： 他者の行動や、一般的と見なされていることに従うことです。

プロンプトでの効果：

• 普遍的なパターン：「毎回」、「常に」
• 失敗のパターン：「Y なしの X は失敗」
• 規範を確立します

使用する場面：

• 普遍的な実践を文書化する
• よくある失敗について警告する
• 標準を徹底する

例：

✅ Checklists without TodoWrite tracking = steps get skipped. Every time.
❌ Some people find TodoWrite helpful for checklists.

5. 一体感

概要： 共通のアイデンティティ、「私たち」という意識、内集団への帰属意識です。

プロンプトでの効果：

• 協力的な表現：「私たちのコードベース」、「私たちは同僚です」
• 共通の目標：「私たちはどちらも品質を大切にしています」

使用する場面：

• 協力的なワークフロー
• チーム文化の確立
• 階層に依存しない実践

例：

✅ We're colleagues working together. I need your honest technical judgment.
❌ You should probably tell me if I'm wrong.

6. 互恵性

概要： 受け取った恩恵を返す義務です。

効果：

• 控えめに使用してください。操作的に感じられることがあります
• プロンプトで必要になることはほとんどありません

避ける場面：

• ほぼすべての場合（ほかの原則のほうが効果的です）

7. 好意

概要： 好感を持つ相手と協力することを好む傾向です。

効果：

• 指示への従順を促すためには使用しないでください
• 率直なフィードバックを重視する文化と相反します
• へつらいを生みます

避ける場面：

• 規律を徹底する場合は常に避けてください

プロンプトの種類ごとの原則の組み合わせ

プロンプトの種類	使用する原則	避ける原則
規律を徹底するもの	権威 + コミットメント + 社会的証明	好意、互恵性
ガイダンス／手法	適度な権威 + 一体感	過度な権威
協力的なもの	一体感 + コミットメント	権威、好意
参照用	明確さのみ	すべての説得の原則

なぜ効果があるのか：心理的な仕組み

明確なルールは正当化を減らします：

• 「必ず実行してください」は意思決定による疲労を取り除きます
• 絶対的な表現は、「これは例外に当たるのか」という疑問をなくします
• 正当化を明示的に否定する表現は、特定の抜け穴をふさぎます

実行意図は自動的な行動を生み出します：

• 明確なきっかけ + 必須の行動 = 自動的な実行
• 「X のときは Y を実行する」は、「通常は Y を実行する」より効果的です
• 指示に従う際の認知負荷を減らします

LLM は人間を超える性質を持ちます：

• これらのパターンを含む人間のテキストでトレーニングされています
• トレーニングデータでは、権威を示す表現の後に指示への従順が続きます
• コミットメントの連続（発言 → 行動）が頻繁にモデル化されています
• 社会的証明のパターン（誰もが X を行う）が規範を確立します

倫理的な使用

正当な使用：

• 重要な慣行が守られていることを確認する
• 効果的なドキュメントを作成する
• 予測可能な失敗を防ぐ

不当な使用：

• 個人的な利益のために操作する
• 偽りの緊急性を作り出す
• 罪悪感に訴えて従わせる

判断基準： ユーザーがこの手法を十分に理解していたとしても、その本当の利益にかなうでしょうか？

クイックリファレンス

プロンプトを設計するときは、次の点を確認します。

1. どの種類ですか？（規律づけ、ガイダンス、参考情報のいずれか）
2. どのような行動を変えようとしていますか？
3. どの原則が当てはまりますか？（通常、規律づけには権威とコミットメントを用います）
4. 組み合わせすぎていませんか？（7つすべてを使わないでください）
5. 倫理的ですか？（ユーザーの本当の利益にかなっていますか？）