senior-prompt-engineer

シニアプロンプトエンジニア

評価駆動型のプロンプトエンジニアリング、RAG 品質測定、エージェントワークフローの検証を行います。ここにあるものはすべて、設計上、モデルに依存しません。手法は、どの世代のモデルで確認されたかではなく、何をするものかを基準に説明しています。また、ツールにモデル ID や料金がハードコードされることはありません。金額を算出する場合は、利用するプロバイダーの最新料金を指定してください。

運用ルール

1. ベースラインなしにプロンプトを変更しないでください。 まず指標を取得し（--analyze --output baseline.json）、その後、すべての反復をベースラインと比較してください。
2. 最適化の前に評価セットを用意してください。 期待される出力を含む、代表的なケースを最低 10〜20 件用意してください。ユーザーが評価セットを持っていない場合は、プロンプトに手を加える前に、一緒に評価セットを作成してください。感覚に頼った最適化が、最もよくある失敗の原因です。
3. プロンプトの小細工より、プラットフォームの機能を優先してください。 プロバイダーがネイティブの構造化出力／JSON スキーマの強制、ツール使用 API、プロンプトキャッシュを提供している場合は、「JSON のみを返す」といった呪文ではなく、それらを使ってください。プロンプトレベルでの形式の強制は、デフォルトではなく、代替手段です。
4. 現行世代のモデルには、足場となる指示が少なくて済みます。 思考過程の定型文、役割の指定、少数ショット例を反射的に追加しないでください。最先端モデルでは、冗長な足場によって性能が低下することがよくあります。評価セットで効果が確認できた場合にのみ、各要素を追加してください。
5. コストの数値は、必ずユーザーが指定してください。 プロバイダーの最新の 1 Mtok あたりの料金を確認し、--price-per-mtok で渡してください（記憶しているものも含め、キャッシュされた料金表は決して信用しないでください）。

ツール（正確な CLI、すべて標準ライブラリ）

1. プロンプトオプティマイザー — scripts/prompt_optimizer.py

静的解析：トークン数の推定、明瞭さ／構造のスコア（0〜100）、曖昧さと冗長さの検出、少数ショット例の抽出。

# Full analysis (human-readable report)
python3 scripts/prompt_optimizer.py prompt.txt --analyze

# Save machine-readable baseline for later comparison
python3 scripts/prompt_optimizer.py prompt.txt --analyze --json --output baseline.json

# Token estimate; cost only if you supply your provider's current rate
python3 scripts/prompt_optimizer.py prompt.txt --tokens --model claude --price-per-mtok 3.00

# Whitespace/redundancy-trimmed version
python3 scripts/prompt_optimizer.py prompt.txt --optimize --output optimized.txt

# Extract Input/Output few-shot pairs to JSON
python3 scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json

# Compare a revision against the saved baseline
python3 scripts/prompt_optimizer.py optimized.txt --analyze --compare baseline.json

--model には任意の文字列を指定できます。推定されるのはトークナイザーの種類のみです（名前に「claude」が含まれる場合は 1 トークンあたり 3.5 文字、それ以外は 4.0 文字）。

2. RAG 評価ツール — scripts/rag_evaluator.py

2 つの JSON ファイルから、検索とグラウンディングの品質を測定します（形式は --help に表示されます）。

python3 scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json
python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --k 10 --json
python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --output report.json --verbose
python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --compare baseline_report.json

コンテキスト関連性、precision@k、網羅率、回答の忠実度、根拠への準拠度を報告します。関連性が 0.80 未満の場合は、プロンプトの問題ではなく検索の問題（チャンク分割／埋め込み／フィルタリング）として扱ってください。生成プロンプトを書き直す前に、検索を改善してください。

3. エージェントオーケストレーター — scripts/agent_orchestrator.py

エージェント設定（YAML／JSON）を検証します：ツールの接続、必須設定の不足、ループのリスク、トークン数の推定。

python3 scripts/agent_orchestrator.py agent.yaml --validate
python3 scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid
python3 scripts/agent_orchestrator.py agent.yaml --estimate-cost --runs 100 \
    --input-price-per-mtok 3.00 --output-price-per-mtok 15.00

2 つの料金フラグを指定しない場合、--estimate-cost はトークン数の推定のみを報告します。設定内の model: フィールドは参考情報であり、任意のモデル名を指定できます。

ワークフロー

プロンプトの最適化（評価によるゲート）

1. ベースライン： python3 scripts/prompt_optimizer.py current_prompt.txt --analyze --json --output baseline.json
2. レポートから問題を診断します：曖昧な動詞（「分析する」「処理する」など）、冗長なブロック、出力仕様の欠如、トークンの浪費。
3. 一度に1つの変更を適用し、効果の大きい順に進めます：

   症状	修正
   形式が不正、または解析できない出力	API が対応している場合はネイティブの構造化出力／JSON Schema を使用し、それ以外の場合はプロンプト内でスキーマを明示します
   実行ごとに回答が一貫しない	指示を明確にし、対照的な例を2～3件追加します（うち1件は、何をしてはいけないかを示す紛らわしい例にします）
   エッジケースを見落とす	エッジケースを明示的に列挙し、「判断に迷った場合はXを行う」というルールを追加します
   繰り返し呼び出しでトークンが肥大化する	安定したプレフィックス（システムルール、例）を先頭に移動してプロンプトキャッシュを利用できるようにし、冗長な箇所を削除します
   難しいケースで推論を誤る	コンシューマーが無視するスクラッチフィールドに段階的な推論を記述するよう求めるか、プロバイダーの拡張思考モードを使用します

4. 再分析して比較します： python3 scripts/prompt_optimizer.py revised.txt --analyze --compare baseline.json
5. 評価ゲート（リリース前に必ず合格すること）： 改訂したプロンプトを評価セットで実行し、ケースごとの合否を eval_results.json に書き込んだうえで、次をアサートします：

   python3 scripts/prompt_optimizer.py revised.txt --analyze --json --output revised.json \
     && python3 -c "
   import json, sys
   r = json.load(open('revised.json')); b = json.load(open('baseline.json'))
   ok = r['clarity_score'] >= b['clarity_score'] and r['token_count'] <= b['token_count'] * 1.10
   sys.exit(0 if ok else 1)"
   echo "gate exit=$?"   # 0 = ship; 1 = regression, iterate again
   

   この構造上のゲートとタスクレベルの評価を組み合わせます。改訂によって、以前合格していた評価ケースを1つも失ってはなりません（リグレッションなしのルール）。

Few-Shot の例の設計

1. まずタスクの仕様（入力形式、出力形式、エッジケースの扱い）を定義します。
2. 例をゼロ件から始めて測定します。現在のモデルでは例が不要なこともよくあります。評価で明らかになった失敗の傾向に対してのみ例を追加します。
3. 追加する場合は、最大3～5件とし、簡単な例 → エッジケース → 否定例（抽出してはいけないもの）の順に並べ、実際の出力仕様と同じ形式にします。
4. 一貫性を検証します：python3 scripts/prompt_optimizer.py prompt_with_examples.txt --extract-examples --output examples.json を実行し、抽出されたすべてのペアがスキーマに照らして解析できることを確認します。
5. 評価セットを再実行します。例に似ているという理由だけで合格するケースがある場合は、そのバリエーションを評価セットに追加し、評価時には使用しないようにします。

構造化出力の設計

1. まず JSON Schema を作成します（型、列挙値、必須項目、maxLength）。
2. API によるネイティブな強制を優先します：構造化出力／レスポンススキーマ／ツール呼び出しのパラメーターであれば形式を保証できますが、プロンプトのテキストでは保証できません。
3. フォールバック（スキーマに対応していない API の場合）：スキーマをフィールドごとのルールとして記述し、有効な例を1つ添えて、「JSON オブジェクトのみを出力する」と指示します。
4. ゲート：10件の評価出力をスキーマバリデーターに通します（最低限、python3 -c "import json,sys; [json.loads(l) for l in sys.stdin]" を使用）。10件すべてを解析できなければ、ステップ2に戻ります。

RAG の調整ループ

1. questions.json（id、質問、参照回答）を作成し、現在の検索結果を contexts.json に保存します。
2. python3 scripts/rag_evaluator.py --contexts contexts.json --questions questions.json --output rag_baseline.json
3. 最も低い指標から修正します：関連性 → チャンク分割／埋め込み／メタデータフィルター、忠実性 → グラウンディングの指示＋「コンテキストのみを根拠に回答する」＋引用の必須化、網羅性 → 検索 k／クエリ拡張。
4. ゲート：python3 scripts/rag_evaluator.py --contexts new_contexts.json --questions questions.json --compare rag_baseline.json を実行し、すべての指標がベースライン以上であることを確認します。1つでも低下した場合は変更をブロックします。

エージェント設定のレビュー

1. python3 scripts/agent_orchestrator.py agent.yaml --validate を実行します。VALIDATION PASSED で終了する必要があります。すべてのエラーと警告（ツール設定の欠落、反復回数の上限なし、ループのリスク）を修正します。
2. コンテキストの適切な管理を確認します：各ツールの説明は1～2文以内、ツール数はタスクに必要な最小限、安定したシステムプロンプトは先頭に配置（キャッシュしやすくする）、反復回数の上限と早期終了の条件が設定されていること。
3. 予算：現在の料金を指定して --estimate-cost --runs N を実行します。1回あたりのコストが予算を超える場合は、モデルをダウングレードする前にツールまたはコンテキストを削減します。

参照資料

ファイル	内容	ユーザーから次の質問があった場合に読み込みます
references/prompt_engineering_patterns.md	入出力例を含む10種類のプロンプトパターン	「どのパターンがよいですか？」、少数ショット設計、分解、メタプロンプティング
references/llm_evaluation_frameworks.md	評価指標、スコアリング手法、A/Bテスト	「どのように評価しますか？」、「品質を測定する」、「プロンプトを比較する」
references/agentic_system_design.md	エージェントアーキテクチャ（ReAct、Plan-Execute、ツール使用）	「エージェントを構築する」、「ツール呼び出し」、「マルチエージェント」

関連スキル

• engineering-team/skills/senior-ml-engineer — モデルのデプロイとサービング（このスキルはプロンプト／評価レイヤーまでを対象とします）
• engineering/rag-architect — RAG システムアーキテクチャ（このスキルは RAG の品質を測定し、もう一方はパイプラインを設計します）
• engineering/agent-designer — エージェントシステム全体の設計（このスキルは設定を検証し、もう一方はアーキテクチャを設計します）