ADR-0056: Decision Pipeline の LLM temperature / sampling 戦略を工程別ハイブリッド設計で確立

• Status: Accepted
• Mode: Standard
• Scope: platform
• Kruchten Type: Property/Executive
• Implementation Status: Done (Phase 0-4: PR #1005, #1008, #1009, #1010)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-21 04:06
• 承認日時 (JST): 2026-05-26 (Pipeline Score 40/50 合格済、amendment で実態反映後 Accepted)
• Deciders: [email protected] (単独)

決定の早わかり（Y-statement）

本節は ADR-0140 の方針で遡及追加された本文の要約で、新しい意味は加えていない (意思決定内容は不変)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

• 文脈: Decision Pipeline の CI 化検討で「Pipeline 全体 T=0 で再現性確保」案が浮上した。各 Gate / node の LLM temperature・sampling は暗黙運用 / provider 既定値依存である。
• 問題: T=0 一律は Gate 1 Socratic の発散探索を機能不全にする構造的リスクがある。T>0 一律は判定系の再現性が低く、同じ draft で結果が変わる監査リスクがある。provider 既定は Gate 3 並列レビューの比較整合性を崩す。
• 問題点と課題（直せる原因 → 発生を止めるためにやること）:
  • temperature が暗黙運用で provider 既定値依存 → 全 node で明示設定を必須化し、provider 既定値の使用を禁止する。
  • 判定系と発散系で最適パラメータが相反する → 工程別に分ける (判定系=低温度・低 N / 発散系=高温度・複数 sampling / 採点系=中温度 + Self-Consistency N=5)。
  • LLM call のパラメータ追跡が未整備 → 全 call で {node_id, temperature, seed} 等をログ保存する (90 日)。
• 前提（解決を課題に立てない与件）:
  • LiteLLM Gateway 経由で OpenAI / Anthropic 等の複数 provider を扱う (seed 対応有無に依存)。
  • prompt 文面そのものの最適化 (ADR-0042 スコープ) とモデル選定 (別 ADR) は Non-Goals。
• 決定（対応策）: 全 Gate T=0 一律 (案 X1)・全 Gate T=0.7 一律 (案 X2)・provider 既定 (案 X3) でなく、工程別ハイブリッド temperature / sampling 戦略を採用する。設定は prompts/production/<gate>/prompt.meta.yaml に明示する。
• 目的: 判定系の再現性と探索系の創造性を両立し、全 LLM call の監査証跡を完備する。
• 代償: LLM コストが増える (Gate 1 / Gate 4 の sampling で現状比 +70% / ≈ $6/月)。8 node × 4 パラメータの設定複雑性が増す。
• 詳細は本文の影響・撤退条件セクションを参照のこと

1. コンテキスト

1.1 背景 (Background)

2026-05-21 セッション (docs/_internal/05_how-to/git_workflow.md の rebase 章追加 PR #880 から派生) で Decision Pipeline の CI 化検討を議論する中で、「CI から実行すれば Web UI と同じか?」「同じになるように T=0 にすればよいか?」というユーザ質問が起点となり、Pipeline 全体での LLM temperature / sampling 戦略が暗黙運用のままであることが顕在化した。

1.2 現状 (Current State / As-Is)

Decision Pipeline (LangGraph TS on Cloudflare Workers + LiteLLM Gateway / ADR-0019) の各 Gate / node で使う LLM の temperature・sampling 戦略は 暗黙運用 / provider 既定値依存 であり、明示的な設定方針が存在しない。CI 化検討時に「Pipeline 全体 T=0 で再現性確保」案が浮上している。

1.3 課題 (Problem)

「Pipeline 全体 T=0 一律」は Gate 1 Socratic 問診の発散探索を機能不全にする構造的リスクがある。具体的な失敗シナリオ:

• T=0 一律: Gate 1 Socratic で「他にどんな代替案がある?」が argmax で 1 答しか返らず、起案者の思考そのままが ADR になり AI 審査の意味が薄れる。Gate 4 Scoring の sampling variance が消失して採点信頼区間が出せず、起案者バイアス検出が困難
• T>0 一律: 判定系 (Gate 0 Triage / Gate 4 合否) の再現性が低く、同じ draft を 2 回流すと結果が変わる監査リスク
• provider 既定: モデル / vendor ごとに異なり、Gate 3 並列レビューの比較整合性が崩れる

1.4 制約・要件 (Constraints & Requirements)

• LiteLLM Gateway 経由で OpenAI / Anthropic 等の複数 provider を扱う (seed 対応有無に依存)
• LLM コストは予算制約あり (詳細値は要追記)
• Cloudflare Workers 環境で実行 (ログ保存先は Cloudflare Logs / KV)
• 監査証跡として全 LLM call のパラメータ追跡が必須
• ADR-0042 (LLM Prompt Lifecycle Management) の prompts/production/<gate>/prompt.meta.yaml 構造と整合させる

1.5 目標 (Goals / To-Be)

• Gate 工程ごとに最適な temperature / sampling を明示設定し、判定系の再現性と探索系の創造性を両立する
• 全 LLM call の温度・サンプリングパラメータを設定ファイルで一元管理し、監査証跡を完備する
• Non-Goals: prompt 文面そのものの最適化 (ADR-0042 スコープ)、モデル選定 (別 ADR)

2. 決定

Decision Pipeline の各 Gate / node に対し、工程別ハイブリッド temperature / sampling 戦略 を採用する。判定系 (Gate 0 / Gate 4 確定 / Slug) は低温度・低 N で再現性を確保し、発散系 (Gate 1 Socratic) は高温度・複数 sampling で探索性を担保、採点系 (Gate 4 Scoring) は中温度 + Self-Consistency N=5 で信頼区間を取得する。設定は prompts/production/<gate>/prompt.meta.yaml に明示し、provider 既定値の使用を禁止する。

3. 判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから 3-5 個選定)

K.O. criterion: Must 軸 (#reliable / #suitable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

K.O. 通過は採択案と案 X2 のみ。案 X2 は加重和も低いため不採用。採択案を選択。

4. 検討した代替案 (Alternatives Considered)

• 採用案: 工程別ハイブリッド設計 — Gate 0 (T=0.0-0.3, N=1) / Gate 1 (T=0.7-1.0, N=3-5) / Gate 2 (T=0.3-0.5, N=1-2) / Gate 3 (T=0.5, N=1, vendor 別並列) / Gate 4 (T=0.5-0.7, N=5 Self-Consistency) / Body Generation N7 (T=0.5-0.8, N=1) / Slug 生成 N8 (T=0.0-0.3, N=1)。各 Gate の本来価値を最大化。
• 案 X1: 全 Gate T=0 一律 (再現性最優先) — 不採用理由: Gate 1 Socratic の発散探索が死蔵、Gate 4 sampling variance 消失で起案者バイアス固定化、Body Generation が全 ADR 似た文体に収束 (K.O. #suitable 未充足)。
• 案 X2: 全 Gate T=0.7 一律 (創造性最優先) — 不採用理由: Gate 0 / Gate 4 判定が不安定、同じ draft で結果が変わる監査リスク、回帰テスト不可。
• 案 X3: provider 既定 temperature 任せ — 不採用理由: モデル / vendor / API バージョンごとに変化、Gate 3 並列レビューの比較整合性が崩れる。完全な hidden state (K.O. #suitable / #reliable 未充足)。

4.1 Gate / node 別 temperature 設定 (採用案詳細)

†1 LiteLLM T drop: litellm/config.prod.yaml で claude-opus の supported_openai_params に temperature を含めておらず、drop_params: true により API リクエスト時に除外される。Anthropic API デフォルト (T=1.0) が適用される。将来 supported_openai_params に temperature を追加すれば推奨値が有効化される。

†2 thinking 必須: createLlmWithEffort() で Claude Opus thinking mode を使用。Anthropic API は thinking 有効時に T=1.0 を必須としており、他の値を指定するとエラー。起案時の推奨 T=0.5〜0.7 は適用不可。Self-Consistency N=5 の多数決で採点の robust 性を代替確保する。

4.2 監査証跡要件

• 全 LLM call で {node_id, model_id, temperature, top_p, seed, sample_index, latency_ms, prompt_hash, response_hash} をログ保存
• Gate 4 で複数 sampling した場合は 個別 sample + 集計結果 を両方記録
• ログは Cloudflare Logs / KV のいずれかに 90 日保存

4.3 再現性を担保する仕組み

• seed 固定 (provider 対応している前提、OpenAI/Anthropic は対応) を全 node で必須化
• provider 既定 temperature の使用を禁止 (明示設定必須)
• golden.jsonl 整備 (ADR-0042 で計画済、2026-07-14 目標) で回帰テスト

5. 影響 (Consequences)

5.1 正の影響 (Good)

• Gate 1 探索 / Gate 4 採点の 本質的価値 (発散思考 + 信頼区間) を機械化
• 監査証跡が完備 (全 LLM call のパラメータ + sample index + hash)
• Pipeline 全体の振る舞いを 設定ファイルで一元管理 (例: prompts/production/<gate>/prompt.meta.yaml)

5.2 負の影響 (Bad)

• LLM コスト N 倍 (Gate 1 / Gate 4 で N=3-5 sampling)
• 設定の複雑性増加 (8 node × 4 パラメータ × provider 別差異の管理)
• Gate 4 Self-Consistency の N=5 がコスト的に持続困難な場合、N=3 への degrade option が必要

コスト試算 ($/月、絶対値)

前提: Claude Sonnet 4.6 ($3/M input + $15/M output)、平均 prompt 5K + completion 2K = 7K token/call、Gate 1 calls/ADR = 3、Gate 4 calls/ADR = 2 (Self-Consistency 前)。実測値の差異が ±50% 超なら撤退条件 §6 の N 削減トリガー発火。

注: 月 ADR 件数は代表取締役 1 名運用の現状値 (2026-04 〜 2026-05 実績 月 4-6 件)。Jr 入社 (2026-10) で月 15 件想定なら採用案コストは 約 $18/月 (現状比 +5 倍)。Jr 入社時に再評価。

5.4 影響を受ける LangGraph node ファイル (8 件)

本 ADR の採用に伴い temperature / sampling.n 設定を明示する LangGraph TS node (docs/_internal/03_decisions/decision_pipeline/langgraph_migration/migration_overview.md 参照、main session 実装担当):

設定は各 node から呼ばれる prompts/production/<gate>/prompt.meta.yaml に集約する (ADR-0042 整合)。LangGraph 移行未完了時点 (2026-05-21) では本ファイルは未実装のため、main session が ADR-0019 main_workspace_checklist の手順 2 (LangGraph node 実装) で新規作成する際に本 ADR の表を SSoT として参照する。

5.3 中立・トレードオフ (Neutral / Trade-offs)

• 再現性 (T=0) vs 創造性 (T>0) の二律背反は本 ADR の核心。工程別に分けることで「両方欲しい」を実現するが、設定運用コストとのトレードオフ
• Self-Consistency (N=5) の信頼区間 vs LLM コスト 5 倍。Gate 4 でのみ採用、Gate 1 では N=3 で許容

6. 撤退条件 (Rollback Plan)

6.1 再評価トリガー

• 3 ヶ月後 (2026-08-21): Gate 別 sampling コストの実測値を評価。LLM コスト総額が予算の 30% 超 (実コスト > $20/月 想定) なら N 削減
• 6 ヶ月後 (2026-11-21): LLM provider 側の seed / temperature 挙動変更があれば再評価
• 1 年後 (2027-05-21): 新モデル (Claude Opus 5 / GPT-5 等) の登場で「T=0 でも十分に creative」になっていれば本 ADR を Superseded
• 判定指標: Gate 4 Scoring の信頼区間幅 (σ) が 5 点 (50 点満点中) 超えていれば、Gate 4 のみ N=10 に拡張検討

6.2 撤退手順 (Rollback Procedure)

完全撤退 / 段階的縮退いずれも以下の手順で実施。所要時間 ~30 分:

1. PR テンプレで設定 revert:
   • 影響 node の prompts/production/<gate>/prompt.meta.yaml の temperature / sampling.n を 本 ADR 採用前の baseline (T=0 一律 / N=1) に戻す PR を起案
   • PR タイトル: revert(pipeline): ADR-0056 settings to baseline (T=0 / N=1)
   • PR body 必須項目: (a) revert 理由 (撤退トリガー §6.1 のどれが発火したか)、(b) 影響範囲 (どの node を戻すか、全部 vs Gate 4 のみ等の段階指定)、(c) golden.jsonl の baseline テスト再走結果
2. 進行中ログの扱い:
   • 撤退 PR merge 時点で 実行中の Pipeline run (Gate 1〜4 進行中の session) は 完了まで継続 (中断しない)
   • 進行中 run の audit log には audit.adr_0056_state: in_flight_during_rollback フラグを付与し、撤退境界を識別可能化
   • 次回 trigger 以降の新 run から baseline 設定で動作
3. 境界マーカー記録:
   • 監査ログに audit.rollback_marker: {adr: "0056", from_version: "<git_sha>", to_version: "baseline", at: "<ISO timestamp>"} を 1 行追加
   • Cloudflare Logs / KV 両方に書き込み (90 日保存)
4. golden.jsonl の baseline 復帰:
   • tests/golden/<gate>.jsonl の expected output を T=0 仕様時のものに切り替え (ADR-0042 連動)
   • 回帰テスト再走で全件 pass を確認
5. 段階的縮退 (部分撤退) パターン:
   • Gate 4 N=5 → N=3: 上記 1 で sampling.n: 3 に変更、他 Gate は変更なし
   • Gate 1 N=3 → N=1: 上記 1 で sampling.n: 1 に変更、Gate 4 は維持
   • 完全撤退: 全 node baseline (T=0 / N=1) に戻す

6.5 Confirmation (準拠確認 / Fitness Function)

• 検証手段 1 (機械検証): 全 LLM call ログから {node_id, temperature, sample_index} を抽出し、本 ADR §4.1 の Gate 別表と整合するか CI で検証 (scripts/pipeline-temperature-audit.mjs 新設)
• 検証手段 2 (機械検証): golden.jsonl (ADR-0042) で T=0 工程の再現性を回帰テスト。Gate 0 Triage の判定が seed 固定で 100% 一致するか
• 検証手段 3 (手動): 月次で Gate 4 Scoring の信頼区間幅 σ をレビュー。5 点超えなら N 拡張検討
• 実行頻度: 検証手段 1/2 は PR ごと、検証手段 3 は月次
• 違反時の対応: temperature 設定逸脱は PR マージブロック (CI fail)、信頼区間幅は監視 → 閾値超えで Pipeline 設定改訂 PR を起案

7. 参照 (References)

• 関連 ADR:
  • ADR-0019 (Decision Pipeline LangGraph 移行): 本 ADR の前提となる Pipeline 構成
  • ADR-0042 (LLM Prompt Lifecycle Management): 本 ADR は ADR-0042 の運用パラメータを具体化。prompts/production/<gate>/prompt.meta.yaml への temperature/sampling フィールド追加要
  • ADR-0050 (Synthesis 標準テンプレート Q42 MCDA): Gate 4 Scoring が本 ADR の Self-Consistency の主要適用先
• 関連 PR/Issue:
  • PR #880 (DOC-OPS-05、本 ADR の議論の発端)
  • PR #882 (handover §Step 5 派生 4 ADR 起案 KV 投入プロンプト、本 ADR と同じ起案フロー)
• 外部資料: 2026-05-21 セッション議論ログ (docs/_internal/05_how-to/git_workflow.md 関連)

8. 参照: Pipeline 審査履歴 (2026-05-21 実行時)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を審査した結果のログ。Gate 0-4 + 3 vendor (Gemini / Claude / o3) の Gate 3 並列レビュー赤ペンを参照として保存。デフォルトでは折りたたまれており、▶ をクリックで展開する。