version: "1.0.0" name: llm-integration description: プロダクトへのLLM機能組み込みを体系的に進めるスキル。ユースケース適合性の判断からプロンプト設計・評価(eval)・コスト管理・セキュリティまでをカバーし、「動くが壊れやすい」実装を避ける。

LLM機能のプロダクト組み込み

目的

LLMをプロダクトに組み込む際の判断と実装を体系化する。「とりあえずAPIを叩く」段階から、eval・信頼性・コスト・セキュリティまでを設計の一部として扱えるチームを支援する。

使うタイミング

• 新機能にLLMを使うか判断したいとき
• プロンプトを本番に投入する前のレビュー・品質担保
• 既存LLM機能のコスト・品質・安全性を改善したいとき
• LLM機能の設計ドキュメントをレビュー・作成するとき

進め方

1. ユースケース適合性を判断する — LLMが向く処理かどうかを先に問う。普通のコードで書けるならLLMを使わない
2. LLM機能設計シートを書く — 下記テンプレートを埋める。曖昧なまま実装に入らない
3. プロンプトを設計・バージョン管理する — 役割・入力・制約・出力形式を明示し、Gitで管理してテスト対象にする([[git-workflow]])
4. evalデータセットを作る — 最低20件の代表的な入力と期待出力を用意する。これが品質の基準線になる
5. 信頼性設計を実装する — バリデーション・リトライ・タイムアウト・フォールバックをコードに組み込む
6. コストを試算・モニタリングする — 本番投入前にリクエスト数×トークン×単価を見積もり、監視とアラートを設定する([[monitoring-operations]])
7. セキュリティレビューを行う — プロンプトインジェクション・PII送信・出力の無検証実行を確認する([[security]])
8. UXに不確実性を反映する — 下書き提示・編集可能・フィードバック収集を設計に含める

設計の要点

ユースケース適合性

LLMが向く処理と向かない処理を最初に区別する。

判断基準: 「正規表現やテンプレートで実装できるか?」「失敗時のコストは?」「人間が見てもバラつく判断か?」の3問に答えてからLLMを選択する。

プロンプト設計

• 4要素を明示する: 役割(あなたは〜)・入力(ユーザーデータの形式)・制約(禁止事項・長さ・言語)・出力形式(JSONスキーマを明示)
• 構造化出力を使う: JSON Schemaを指定してパース失敗を減らす。フリーテキスト出力は検証が困難
• few-shot例を入れる: 2〜5件の入出力例で品質が大きく変わる。境界ケースを例に含める
• プロンプトはコードとして管理する: ファイルに外出しし、変更をGitでトラッキングしてevalを通す。インラインの文字列リテラルにしない

# プロンプトファイルの構成例
prompts/
  classify_feedback/
    system.txt       # システムプロンプト
    examples.json    # few-shot例
    schema.json      # 出力JSONスキーマ
    eval_dataset.jsonl  # evalデータセット

評価(eval)

「触ってみて良さそう」は評価ではない。変更のたびに数値で回帰を検知する。

• evalデータセット: 代表的な入力20件以上+正解ラベル。境界ケース・失敗しやすいケースを意図的に含める
• 合格基準を先に決める: 「精度90%以上」「拒否率5%以下」など定量的に設定する
• LLM-as-judge: 完全一致で採点できないタスクは別のLLMに採点させる。採点プロンプト自体もバージョン管理する
• 定期的な人間の抜き取り検査: LLM-as-judgeの採点精度自体を週次・月次で確認する
• CI/CDに組み込む: プロンプト変更のPRでevalが自動実行され、合格基準を下回ればマージ不可にする

信頼性

• スキーマバリデーション: LLMの出力をJSONスキーマで検証。失敗したら即リトライ(最大2〜3回)
• タイムアウト: LLMコールには必ずタイムアウトを設定する。デフォルト30秒を目安に
• フォールバック: LLM失敗時の代替動作を設計する(エラー表示・ルールベース処理・人間への引き継ぎ)
• レートリミット対応: 指数バックオフ付きリトライ。同期処理ではなくキュー経由にすることも検討
• ストリーミング: レイテンシが体感上問題になるなら最初のトークンから表示する。生成中のUIを設計する

コスト

• タスク難易度に応じて最小モデルを選ぶ: [[orchestration]] のモデル委譲と同じ思想。全タスクに最上位モデルを使わない。分類・抽出など定型タスクは軽量モデルで十分なことが多い
• プロンプトキャッシュを使う: システムプロンプトや固定のfew-shot例をキャッシュし、繰り返し課金を減らす
• トークン使用量の監視: リクエストごとの入出力トークン数をログに記録し、異常なスパイクにアラートを出す([[monitoring-operations]])
• ユーザーあたりの利用上限: 1日・1ヶ月のトークン上限をユーザーごとに設け、過剰利用を防ぐ
• 本番投入前に試算する: 月次リクエスト数 × 平均トークン数 × 単価 を必ず計算してから設計を確定する

セキュリティ

• プロンプトインジェクション対策:
• ユーザー入力をシステムプロンプトに直接結合しない
• システム指示とユーザーデータを構造的に分離する(XMLタグやJSONラッパーで囲む)
• LLMに与えるツール・権限を最小化する(必要なツールだけを公開)
• PII送信ポリシー: 氏名・メールアドレス・健康情報など個人情報を外部APIに送ってよいか、法務・プライバシーポリシーと照合する。必要なら匿名化・マスキングを挟む
• 出力の無検証実行禁止: LLMが生成したSQL・シェルコマンド・コードを直接実行しない。ホワイトリスト検証またはサンドボックスを必ず挟む
• ログのマスキング: LLMへのリクエスト・レスポンスをログに記録する際、PII・機密情報をマスクする

成果物テンプレート

# LLM機能設計シート
 
## 基本情報
feature_name: ""
author: ""
date: ""
 
## ユースケースと適合性判断
use_case: ""  # 何をLLMにやらせるか
why_llm: ""   # なぜ通常のコードではなくLLMか
failure_cost: ""  # 失敗時の影響範囲
 
## モデル選定と根拠
model: ""           # 選定モデル
reason: ""          # 選定理由(コスト・品質・レイテンシのトレードオフ)
fallback_model: ""  # フォールバック時のモデル(コスト削減版など)
 
## プロンプト管理
prompt_path: ""          # リポジトリ内のパス
version_control: git     # Git管理前提
output_schema_path: ""   # JSONスキーマのパス
 
## evalデータセットと合格基準
dataset_path: ""         # .jsonlファイルのパス
dataset_size: 0          # 件数(最低20件)
acceptance_criteria: ""  # 例: 精度 >= 90%、拒否率 <= 5%
judge_method: ""         # exact_match / llm-as-judge / human
 
## 信頼性設計
timeout_sec: 30
retry_max: 3
fallback_behavior: ""    # LLM失敗時の代替動作
 
## コスト試算
monthly_requests: 0
avg_input_tokens: 0
avg_output_tokens: 0
unit_price_per_1k_tokens: 0.0
monthly_cost_estimate: 0.0  # 上記から計算
token_limit_per_user: ""
 
## セキュリティ
user_input_isolation: ""   # ユーザー入力の分離方法
pii_policy: ""             # PII送信の可否と根拠
output_validation: ""      # 出力検証の方法(DBに保存する前・実行する前)

チェックリスト

設計フェーズ

• [ ] 普通のコードで実現できないか検討した
• [ ] LLM機能設計シートを記入した
• [ ] evalデータセット(20件以上)を用意した
• [ ] 合格基準を数値で定義した
• [ ] フォールバック動作を設計した
• [ ] コスト試算を行った

実装フェーズ

• [ ] プロンプトをファイルに外出ししGit管理している
• [ ] 出力をJSONスキーマでバリデーションしている
• [ ] タイムアウトとリトライを実装した
• [ ] ユーザー入力をシステムプロンプトと分離している
• [ ] PII送信ポリシーを確認した
• [ ] LLM出力を無検証で実行・保存していない

リリース前

• [ ] CIでevalが自動実行される
• [ ] トークン使用量の監視・アラートを設定した
• [ ] ユーザーあたりの利用上限を実装した
• [ ] UXに不確実性が反映されている(下書き提示など)
• [ ] フィードバック収集の仕組みを実装した([[analytics-kpi]])

アンチパターン

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

関連スキル

• [[orchestration]] — マルチエージェントとモデル委譲の共通原則
• [[security]] — プロンプトインジェクション・PII・出力検証の詳細
• [[monitoring-operations]] — トークン使用量監視・アラート設計
• [[analytics-kpi]] — フィードバック収集・改善指標の設計
• [[git-workflow]] — プロンプトのバージョン管理
• [[api-design]] — LLMをAPIとして公開する場合の設計
• [[testing]] — evalをCIに組み込む
• [[performance-optimization]] — レイテンシ改善・ストリーミング最適化
• [[architecture-design]] — LLM機能をシステム全体に組み込むアーキテクチャ設計