← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0072type: adrstatus: proposed
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Not Startedproposed_at: 2026-05-26 22:39approved_at: -deciders: [email protected] (単独)business: drp
型付き辺: 出 1 / 入 0
前提とする: ADR-0056全体は INDEX →

ADR-0072: Pipeline LLM パラメータ Drift 検出 CI

  • Status: Proposed
  • Mode: Standard
  • Kruchten Type: Existence/Property
  • Scope: platform
  • Implementation Status: Not Started
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-26 22:39
  • 承認日時 (JST): -
  • Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景 (Background)

ADR-0056 (Phase 2, PR #1008) は Decision Pipeline の全 8 Gate/node に対し工程別 temperature / sampling 戦略を確立し、設定の SoT を prompts/production/<gate>/prompt.meta.yaml の llm_params フィールドに一本化した。同 ADR §6.5 では本 CI スクリプトの新設が計画として記載されている。

1.2 現状 (Current State / As-Is)

prompt.meta.yaml の llm_params 値と ADR-0056 §4.1 テーブルの推奨範囲の整合性、および各 node 実装 (src/nodes/*.ts) の fallback 値との乖離を検出する仕組みは存在しない。変更検知は PR レビュー時の目視に依存している。

1.3 課題 (Problem)

設定の drift が進むと ADR-0056 の工程別ハイブリッド設計の前提が崩れ、判定系 Gate (0/2/3) の再現性 (seed 固定) や探索系 Gate (1/4) の多様性 (N=5) といった監査証跡の信頼性に影響する。レビュアー (代表取締役) の認知負荷も増大し、見落としリスクが残る。

1.4 制約・要件 (Constraints & Requirements)

  • ADR-0056 §4.1 推奨範囲を逸脱しないこと
  • 判定系 Gate (0/2/3) で seed non-null、探索系 Gate (1/4) で seed null を強制
  • sampling_n は Gate 4 で N=5、その他で N=1
  • CI 実行時間 < 5 秒、GitHub Actions の追加コストは無視可能範囲
  • 新規 Gate 追加時に CI fail で開発フローをブロックしないこと (WARN 許容)

1.5 目標 (Goals / To-Be)

scripts/pipeline-temperature-audit.mjs を実装し、GitHub Actions で PR ごとに prompt.meta.yaml の llm_params を自動検証する。SoT は prompts/production/llm_params_policy.json (機械可読 JSON) に外出しする。Non-Goals: Runtime バリデーション (Pipeline 実行時検証は対象外)。

2. 決定

scripts/pipeline-temperature-audit.mjs を新設し、CI (GitHub Actions) で PR ごとに以下を自動検証する: (1) 全 prompt.meta.yaml の llm_params.temperature が推奨範囲内、(2) seed が判定系で non-null・探索系で null、(3) sampling_n が Gate 4 で N=5・その他 N=1、(4) (将来) src/nodes/*.ts の loadLlmParams() fallback 値と YAML の不一致検出。検証基準は prompts/production/llm_params_policy.json (案 I) に外出しする。新規 Gate は policy.json 未定義なら CI WARN (fail ではない)。

3. 判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから選定)

#軸重要度 (係数)案件特有の解釈
1#reliable[Must] (×2.0)ADR-0056 設計前提の drift を確実に検出できるか
2#maintainable[High] (×1.0)ADR-0056 改訂時の同期更新コスト・スクリプト保守容易性
3#operable[High] (×1.0)CI 偽陽性回避、bypass 手段、新規 Gate 追加時の摩擦
4#efficient[Medium] (×0.5)CI 実行時間・開発者待ち時間への影響

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

3.2 評価軸 × 案スコア表

軸係数採択案 (案 I: policy.json 外出し)案 II: ADR §4.1 動的抽出案 A: 手動レビュー案 B: Runtime 検証
#reliable×2.05423
#maintainable×1.04353
#operable×1.04322
#efficient×0.55434
加重和 (正規化)0.9110.7330.5440.600
K.O. 通過 (Must ≥3)✓✓❌✓

加重和は K.O. 通過候補のタイブレーク用 (Suhr 1999 CBA criterion 準拠)。

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

  • 案 I: prompts/production/llm_params_policy.json に外出し (採用) — 機械可読性が高く、YAML パースの依存先を最小化。初期作成 0.3 人日、ADR-0056 改訂時の同期更新 0.1 人日/回。
  • 案 II: ADR-0056 §4.1 テーブルから動的抽出 — SSoT 一本化の利点があるが、Markdown テーブルのパーサ実装が 0.5 人日追加で必要、テーブル記法変更時に脆弱 — 不採用。
  • 案 A: 手動レビューのみ — PR レビュー時に人間が prompt.meta.yaml の変更を目視確認。不採用理由: 見落としリスク、レビュアー (代表取締役) の認知負荷増大。#reliable で K.O.
  • 案 B: Runtime バリデーション — 各 node の起動時に llm_params を検証し、範囲外なら例外。不採用理由: Pipeline 実行時に初めて検知されるため遅い、本番 ADR 起案がブロックされるリスク。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • prompt.meta.yaml 変更時に自動で ADR-0056 準拠を検証、drift 防止
  • PR マージ前に設定逸脱を検出 (shift-left)
  • レビュアー (代表取締役) の llm_params 目視確認負荷を解消
  • Jr 開発者 (2026-10 入社予定) にとって自動ガードレールとして機能

5.2 負の影響 (Bad)

  • CI ジョブ追加 (実行時間 < 5 秒、GitHub Actions の追加コスト無視可能)
  • ADR-0056 §4.1 テーブル改訂時に llm_params_policy.json も同期更新が必要 (0.1 人日/回)
  • 初期実装コスト 1.0 人日が発生

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

  • 運用上の落とし穴:
    • YAML パース失敗: prompt.meta.yaml の構文エラー時は CI fail + エラーメッセージで YAML 修正を促す
    • 新規 Gate 追加: llm_params_policy.json に未定義の Gate ID は WARN (意図的に fail にしない)
    • CI 偽陽性: ADR-0056 §4.1 の推奨範囲変更を先に llm_params_policy.json に反映すれば回避可能
  • 人的ステークホルダー:
    • 代表取締役 (レビュアー): llm_params の目視確認が不要に
    • Jr 開発者 (2026-10 入社予定): prompt.meta.yaml 変更時の自動ガードレール
  • コスト試算:
項目工数
pipeline-temperature-audit.mjs 実装0.5 人日
llm_params_policy.json 初期作成0.3 人日
GitHub Actions workflow 追加0.2 人日
初期実装合計1.0 人日
ADR-0056 改訂時の policy.json 同期0.1 人日/回
年間運用コスト (改訂 2 回想定)0.2 人日/年

6. 撤退条件 (Rollback Plan)

  • ADR-0056 が Superseded された場合: 本スクリプトの廃止 + .github/workflows/ の該当 job 削除
  • 6 ヶ月間 drift 検出ゼロなら CI 頻度を PR ごと → weekly に緩和検討
  • CI 偽陽性 bypass: [skip-llm-audit] コミットメッセージフラグで該当 PR のみスキップ。月 3 回超の bypass 発生なら policy.json のルール見直し
  • スクリプト廃止時の手順:
    1. workflow yml から job 削除
    2. scripts/pipeline-temperature-audit.mjs 削除
    3. llm_params_policy.json 削除
    4. ADR-0056 §6.5 に廃止を追記
  • Review After: 2026-11-26 (6 ヶ月後)

6.5 Confirmation (準拠確認 / Fitness Function)

  • 検証手段: scripts/pipeline-temperature-audit.mjs 自身が本 ADR の fitness function を兼ねる。GitHub Actions workflow (.github/workflows/llm-params-audit.yml) で PR ごとに実行し、prompts/production/<gate>/prompt.meta.yaml の全 llm_params フィールドを prompts/production/llm_params_policy.json と突合する。加えて scripts/adr-lint.mjs で本 ADR と ADR-0056 のクロスリンクを検証する。
  • 実行頻度: PR ごと (GitHub Actions trigger: pull_request)、および main へのマージ時。新規 Gate 追加時は WARN 出力で開発者に policy.json 追記を促す。
  • 違反時の対応: CI fail で PR マージをブロック。エラーメッセージに違反した Gate ID・違反項目 (temperature / seed / sampling_n)・期待値・実測値を出力。緊急 bypass は [skip-llm-audit] コミットフラグ (月 3 回超で policy.json 見直し)。YAML パース失敗時は構文エラー箇所を提示。

7. 参照 (References)

  • 関連 ADR: ADR-0056 (工程別 temperature / sampling 戦略, Phase 2)
  • 関連 PR/Issue: PR #1008 (ADR-0056 Phase 2 実装)
  • 外部資料: （要追記）