型付き辺: 出 3 / 入 0
ADR-0093: Gemini Deep Research を Plan-then-Chain パターンで実行 (flaky startup 回避)
- Status: Accepted
- Mode: Standard
- Kruchten Type: Executive/Property
- Scope: platform
- Implementation Status: Done (PR #1179 — Plan-then-Chain 実装、2026-05-30 マージ済)
- 起案者: [email protected]
- 起案日時 (JST): 2026-05-30 04:03
- 承認日時 (JST): 2026-05-30 04:21 (Pipeline 通常 flow Standard 44/50 通過 + Cross-Validation Must 軸毀損なし、PR #1189 マージ)
- Deciders: [email protected] (単独)
1. コンテキスト
1.1 背景
2026-05-29 の RQ-085 (認証統合) 調査で、Gemini Deep Research Interactions API への直接 fire が 3 連続失敗 (5 設問 original / 3 設問 slim ×2、いずれも status: in_progress のまま 45 分客タイムアウト)。当初は「queue 圧迫 / silent drop」を疑ったが、queue を cancel/DELETE で空にしてから 1 件だけ再投入しても同症状で、queue 圧迫起因では説明できなかった。
2026-05-30 に系統的調査 (tmp/gemini-investigation-2026-05-30.md) を実施し、以下の決定的データを取得:
- 同一モデル (deep-research-preview-04-2026) + 同一入力で T2 = 11 分+ stuck / T3b-max = 5 分で成功 / T7b ('hi') = 3 分で成功 → モデル broken ではなく 同条件でも startup が確率的に失敗する flaky 動作
- T2 / RQ-085 過去 3 件 = 直接 fire 失敗率 ~71% (n=7 で 2 成功)
- T4 (collaborative_planning=true) = 45 秒で plan 完了 / T10 (previous_interaction_id 連結 from T4) = 5 分で research 完了 = Plan-then-Chain は 100% 成功 (n=2)
- 本番投入 (RQ-085 5 設問 original prompt) で Plan 36.7s + Research 528.5s = 計 9.4 分で完走、47KB の academic research output 取得 (citations 付き)
統計的留意 (v6 追記): 上記成功実績は n=3 (T4+T10 + 本番) であり、二項分布 95% 信頼区間は [0%, 70.8%] に達するため、本 ADR 採択時点では「直接 fire (29%) と統計的に区別できる」ことを実証していない。本仮説の検証は 4 週間 n≥15 で Wilson 上限 < 20% の達成をもって完了とする (§3.2 スコア確定条件 / §6 #1)。
1.2 現状 (As-Is)
scripts/run_deep_research.mjs の runGemini() (改修前) は background: true で interaction を 1-shot 起動し /interactions/{id} を GET でポーリングする実装。クライアントタイムアウトは 45 分固定。中間進捗を取得する手段がない (steps は user_input のみ、output_text は空のまま完了まで何も出ない API 仕様)。healthy と stuck の区別がポーリング中に不可能。
1.3 課題
- 直接 fire の startup flaky で 1 起案あたり最大 45 分の無駄待機が発生 (実測 71% 失敗、年間規模では業務影響大)。
- 公式の "maximum research time of 60 minutes" は agent 研究時間 (worker pickup 後) を指し、queue 投入から worker pickup までの SLA は未公開。
- 失敗 interaction が server 側で生き続け queue 圧迫リスク。リトライ時に古い interaction を待つ運用ミスリスク。
- 当初仮説 (queue 分離 / rate limit) は実証で否定された (cancel/DELETE で空にしても同症状、
generateContent通常 API は瞬時応答)。真因は 04-2026 系の deep-research preview agent startup 経路に潜む intermittent failure と推定 (Google 側の queue scheduling 起因か agent worker placement の非決定性かは特定不能)。
1.4 制約・要件
- 個人開発 (solo dev)。実装人日は最小化。
- AI Studio API key (個人) を使用。GCP Console のクオータダッシュボードは見えない。
- 追加 LLM コストは 1 起案あたり ~$0.20 以内 (Plan phase 1 回分)。
- 既存の Claude/OpenAI 経路には影響を与えない (Gemini 経路のみ改修)。
- メタプロンプトパイプライン (
scripts/B*、調査で Node.js 実行と確定) からの呼出 I/F は変更しない。 - 高精度版 (
deep-research-preview-04-2026, DeepSearchQA 93.3%) の品質を維持する。legacy 12-2025 版 (66.1%) への切替は精度劣化が大きく不採用。 - 実行環境固定: 本 ADR の実装は Node.js (非 Workers) 環境でのみ動作を保証。Cloudflare Workers への移植は Phase B 40 分タイムアウトが Workers の 30 秒 wall-time 制限と非互換のため設計上不可能。将来インフラを Workers へ移行する場合は本 ADR を即時廃止対象とする (盲点 #2 対応)。
1.5 目標 (To-Be)
Gemini 経路で collaborative_planning: true で Plan を取得後、previous_interaction_id 連結で research を起動する 2-phase pattern を採用する。これにより直接 fire の flaky startup 経路を回避しつつ、04-2026 の高精度を維持する。ただし本採択は条件付きである (§2 / §6 参照): 4 週検証で信頼区間条件を満たさない場合は §6 撤退条件 #2 を即時発動し案 B フォールバックへ移行する。
Non-Goals: Claude/OpenAI 経路の改修、Deep Research の質的改善、複数 provider の並列実行制御、Gemini API クライアント抽象化の汎用化、Plan-mode を heartbeat として独立利用 (Plan は単に chain 起動のための前段として使う)。
2. 決定
Gemini 経路の runGemini() を 2-phase Plan-then-Chain pattern に改修する (PR #1179 で実装完了済) — ただし本採択は条件付きである: 本番投入後 4 週間で Wilson 信頼区間上限 < 20% を達成し、かつ同期間の直接 fire コントロール群との成功率差が統計的に有意であることを確認した時点で #reliable を 3 → 5 に昇格し正式採択を確定する。達成できない場合または直接 fire が独立に回復した場合は §6 撤退条件 #2 / #4 を即時発動する。
- Phase A (Plan):
agent_config.collaborative_planning: trueで interaction を起動。Plan 出力は通常 30〜60 秒で返る (実測 36.7 秒)。タイムアウト上限 5 分 (環境変数GEMINI_PLAN_TIMEOUT_MINで可変)。タイムアウト時は cancel → DELETE フォールバックで queue を綺麗にして throw。 - Phase B (Chain): Phase A 完了後、
previous_interaction_id: <plan_id>+collaborative_planning: false+ input"Plan looks good. Proceed with the research as outlined."で新 interaction を起動。実 research output が取得される。タイムアウト上限 40 分 (環境変数GEMINI_RESEARCH_TIMEOUT_MINで可変)。タイムアウト時は同様の cleanup。 - token/cost は plan + research の合算で記録。raw response は
{ plan, research }の両方を保存。
設計の正当化は「Plan-mode が 04-2026 の broken な startup 経路を踏まない別経路で動く → Plan が完了した interaction を previous_interaction_id で連結すると research も別経路で起動する」という 観測ベースの仮説 (実測 T4 plan + T10 chain = 100% / 直接 fire = 29%)。Google 公式に Plan queue 分離は明記されておらず、「Plan 直後の warm-up 効果」「観測期間中の Google 側修正」「確率的成功の連続」などの代替説明も成立しうる。本仮説の崩壊は Phase A 単独 timeout 率 ≥ 20% という独立可観測指標 (§6 #3) で検知し、検知時は即時撤退する。
3. 判断基準 (Decision Drivers)
3.1 評価軸
| # | 軸 | 重要度 (係数) | 案件特有の解釈 |
|---|---|---|---|
| 1 | #reliable | [Must] (×2.0) | 直接 fire 71% 失敗から実用可能な水準への改善率。スコア 5 の付与には Wilson 信頼区間上限 < 20% を要する (§6 #1 で確定) |
| 2 | #efficient | [High] (×1.0) | 1 起案あたり追加コスト (Plan token ~$0.10-0.30) と削減効果 (失敗時 45 分→5 分) のバランス |
| 3 | #maintainable | [High] (×1.0) | 既存 Claude/OpenAI 経路への非侵襲性、API 仕様変更時の影響範囲 |
| 4 | #operable | [Medium] (×0.5) | solo dev で cleanup や zombie interaction の運用負荷 |
| 5 | #flexible | [Medium] (×0.5) | 環境変数で plan / research タイムアウトを調整可能、フラグ追加なしで撤退可能 |
K.O. criterion: Must 軸 (#reliable) の score < 3 は不採用。
3.2 評価軸 × 案スコア表
| 軸 | 係数 | 採択案 (Plan-then-Chain) | 案 A (現状維持: 直接 fire) | 案 B (pro-12-2025 legacy 切替) | 案 C (Gemini 経路廃止) |
|---|---|---|---|---|---|
| #reliable | ×2.0 | 3 (暫定: 実測 100%, n=2+本番 1。二項分布 95% CI = [0%, 70.8%] で直接 fire と統計的に区別できず、score=5 の根拠不足。4 週後 n≥15 で Wilson 上限 < 20% 達成時に 5 へ昇格) | 1 (実測 29%, n=7) | 5 (実測 100%, n=1 のみ未検証) | 5 (n/a) |
| #efficient | ×1.0 | 4 (+ Plan コスト ~$0.20) | 1 (45 分 × 71% 損失) | 5 (改修ゼロ) | 5 (Gemini 不要) |
| #maintainable | ×1.0 | 3 (2-phase 設計、helper 抽出済) | 5 (改修なし) | 5 (1 行) | 2 (3 model synthesis 削減) |
| #operable | ×0.5 | 3 (cleanup hook で zombie 抑制) | 2 (zombie 蓄積) | 4 | 5 |
| #flexible | ×0.5 | 4 (環境変数で調整可) | 5 (何もない) | 3 (固定切替) | 5 |
| 加重和 (正規化) | 0.770 (暫定。4 週後昇格達成で 0.870 へ) | 0.420 | 0.910 | 0.840 | |
| K.O. 通過 (Must ≥3) | ✓ | ❌ | ✓ | ✓ |
注 1 (採択判定の正当化): 加重和は 案 B (0.910) > 採択案 (0.770) だが、案 B は §1.4 制約「高精度版維持」の K.O. 基準 (DeepSearchQA 93.3% 維持) に違反 (66.1% へ 27pt 劣化、Humanity's Last Exam も 54.6% → 46.4%)。Standard mode の制約由来 K.O. を適用し案 B を失格、加重和 K.O. 通過案のうち最高位の採択案を選定。案 C は単純化便益あるが 3 モデル synthesis 削減の質的影響を許容しない (RQ-085 で Gemini 結果の独自視点が他 2 モデルにない知見を含むことを実証済)。
注 2 (Cross-Validation v6 反映): 本表は v5 の Gate 4 差し戻し (critical 盲点 #1 統計的脆弱性 / #6 Plan キュー統合リスク) を受け、#reliable 暫定スコアを 5 → 3 へ引き下げ、加重和を 0.870 → 0.770 へ再計算した。スコア 5 への昇格は §6 #1 (4 週検証) の達成および直接 fire コントロール群との有意差確認を条件とし、達成失敗時は §6 #2 を即時発動する。盲点 #6 (Plan キュー統合) は Phase A 単独 timeout 率を独立計測 (§6 #3) して仮説崩壊を検知する仕組みに変換した。
4. 検討した代替案 (Alternatives Considered)
採択案 (Plan-then-Chain): 04-2026 高精度版を維持しつつ、Plan-mode 経由で flaky startup を回避。観測値 100% (n=3 含本番 RQ-085 5 設問版)、ただし統計的には暫定値 (n=3 の 95% CI=[0%, 70.8%])。追加 Plan コスト ~$0.20/起案。PR #1179 で実装済、4 週検証で確定。
案 A (現状維持: 直接 fire): 改修ゼロだが 71% 失敗率を放置。
#reliable=1で K.O. 不通過。本 ADR 起案前の状態がこれ。留意 (盲点 #3 対応): 2026-05-30 以降のベースライン成功率は再計測していない。本 ADR マージ前に直接 fire を n≥3 試行し、現時点ベースラインを §1.1 に追記する事前タスクを設定する。再計測で高確率成功 (≥70%) が確認された場合は本 ADR を撤回し案 A 維持へ回帰する。案 B (pro-preview-12-2025 切替): 1 行修正で 100% 成功率を得られる軽量解。却下理由: DeepSearchQA 27 ポイント / Humanity's Last Exam 8 ポイント精度劣化 (公式数値)。3 モデル synthesis の Gemini 担当として品質劣化は許容範囲外。留意 (盲点 #1 対応): 12-2025 の直接 fire 成功率は n=1 のみで未検証。撤退条件 #2 の安全網としての有効性がブラインドのため、本 ADR 採択と並行して 12-2025 直接 fire を n≥5 バックグラウンド試行し、startup 成功率を独立計測して ADR §参照に追記する。12-2025 も同一 flaky 経路を共有していた場合、撤退条件 #2 の移行先を案 D に変更する。
案 C (Gemini 経路廃止): 改修ゼロ + 月次コスト削減。却下理由: RQ-085 で Gemini が Claude/OpenAI と異なる独自視点 (Cloudflare Tunnel と Workers AI Gateway の統合観点) を提供したことを実証済。3 モデル synthesis の Cross-Validation 効果を犠牲にする選択は別案件の精度低下を招く。
案 D (max-preview-04-2026 切替): 04-2026 系の重量級バージョン、検証で動作確認済 (T3b ~5 分)。却下理由: 04-2026 系の同根問題を抱える可能性、コストが preview の 2-3 倍 ($3-7 vs $1-3)。留意 (盲点 #5 対応): max の直接 fire 成功率は n=1 のみで「同根問題」は仮定。並行して max 直接 fire を n≥3 試行し、3/3 成功が確認された場合は Plan-then-Chain 複雑性を導入せず案 D' (max 直接 fire) として再評価する。追加コストは月次起案件数 × 差額で定量化し §3.2 案 D 欄に追記する。
案 E (collaborative_planning なしで
agent_config.thinking_summaries: 'auto'のみ): 中間 reasoning を露出する別オプション。却下理由: 観測性は向上するが startup flaky 自体は解決しない。Plan-then-Chain と排他ではないので将来併用候補。案 F (Plan 自動承認拒否時のインタラクティブ承認フォールバック): Google が collaborative_planning に human-in-the-loop を追加または固定文字列を拒否した場合の備え。
GEMINI_PLAN_REVIEW=trueでインタラクティブ承認モードへ切替、それでも継続困難なら案 B フォールバック。撤退条件 #5 に組込。
5. 影響 (Consequences)
5.1 正の影響 (Good)
- 失敗時の無駄待機 45 分 → 5 分 (Plan timeout) に短縮。観測値 71% 失敗が ~0% へ改善 (暫定、4 週検証で確定)。
- 04-2026 の高精度 (DeepSearchQA 93.3%) を維持。
- cancel → DELETE の cleanup hook で zombie interaction の queue 圧迫を抑制 (今日の事故処理で実証)。
- Plan-then-Chain は本来の collaborative_planning 用途 (起案者が Plan を確認してから research を承認する) の半自動版として、将来の対話的モードに拡張可能。
- 本ファイル群の改修により Plan-mode + previous_interaction_id 連結という新たな API 機能パターンを社内 (solo dev) で確立、他の Deep Research 用途にも適用可能。
5.2 負の影響 (Bad)
- 暫定採択であることの認知負荷: 4 週検証完了まで「実証済」と呼称できない。
.gemini_execution_log.jsonlへの append-only ロギング、Phase A 単独 timeout 率の.gemini_plan_stats.json独立計測、直接 fire コントロール群成功率の.gemini_direct_fire_stats.json月次自動計測 (盲点 #7/#12 対応)、スクリプト起動時の自動成功率集計を 本番運用の前提条件として 本 PR フォローアップで最優先実装する (盲点 #1/#6/#12 への構造的対応)。 - 1 起案あたり Plan phase の token / search cost が追加 (~$0.10-0.30、本番実測で search cost $1.12 のみ、Plan token は usage 報告が 0 で計算不能 = 別バグ)。GCP Console クォータダッシュボード不可視 (§1.4) の環境では累積コスト超過を月次 API 明細の手動確認でカバー (盲点 #9 対応)。電帳法対応 (盲点 #10): Plan token usage = 0 問題を Google AI Studio サポートに報告し、暫定措置として入出力テキスト長から推定 token 数を計算し『推定値』フラグ付きで記録、月次 API 明細との照合スクリプトで乖離率 20% 超アラート。
- 2-phase 設計で 60 行程度のコード追加 (helper 抽出含む 109 insertions)。保守時の認知負荷増。
previous_interaction_idAPI 仕様変更時の影響範囲が大きい (採択案の中核機構)。Phase A→B 間遅延 30 秒超で警告、Phase B 起動直後の最初のポーリングレスポンス (5〜10 秒以内) でoutput_textまたはstepsに Plan context のキーワードが存在しない場合を『連結失敗』として検知し即時 abort (盲点 #6 対応、必須実装)。Phase A→B 遅延が 2 分超の試行は「有効な Plan-then-Chain 試行」の統計から除外する条件を §6 計測条件に追加 (盲点 #4 対応)。- Plan-mode が将来「別経路」を提供しなくなる (Google 側で同一経路に統合) と本 ADR の前提が崩壊するリスク。Phase A 単独 timeout 率を独立計測 し週次レビューで仮説崩壊を検知 (§6 #3、盲点 #6 対応)。
- 失敗 interaction の cleanup が cancel 500 エラーや DELETE 失敗時にローカルファイル
.gemini_zombie_interactions.jsonへの記録ロジックは未実装。電帳法 §7 電子取引データ保存要件 (2026 時点で宥恕措置終了済) では API 経由業務データの処理ステータス追跡可能性が問われるため、Phase A/B 全 interaction の ID・開始/終了時刻・status・推定コストの append-only ログ化、cleanup 失敗時の zombie 記録、起動時の残存 zombie DELETE 試行、zombie 3 件警告 / 5 件超で新規 research 起動ブロックの 2 段階通知を 本 PR マージ前の P0 ゲート として実装、CI/CD でブロック (盲点 #2/#8 対応、本番運用の絶対前提条件)。週次の zombie DELETE クリーンアップ cron も追加。 "Plan looks good. Proceed..."固定文字列での自動承認は collaborative_planning の API 設計意図 (人間レビュー) に反する機械的バイパス。Gemini API 利用規約 §4 (Prohibited Uses) の "automated interactions that simulate human review" 類似条項に該当する可能性があり、preview API の利用条件変更時に制限されうる。現時点で Google AI Studio ToS と Deep Research API 利用ポリシーを精査し自動承認に関する条項の有無を §参照に記録、preview API の changelog 週次確認に「利用規約の変更」を明示的に追加、GA 版リリース時の Plan 自動承認継続可否チェックリストを事前作成 (盲点 #3/#11 対応)。拒否時の動作は案 F に委ねる。deep-research-preview-04-2026は preview であり GA 移行時にモデル名変更・API 仕様変更・非推奨化の可能性。モデル名を環境変数GEMINI_MODELで外部化し、Google AI Studio release notes と Gemini API changelog の週次確認を運用手順化、GA 版での Plan-then-Chain smoke test スクリプトを事前準備 (盲点 #10 対応、§6 #6)。- 入力プロンプト複雑化や Plan の調査方向誤りが自動 Research に伝播し誤った成果物を生むリスク。
GEMINI_PLAN_REVIEW=trueでインタラクティブ承認待ちに切替可能な分岐、入力プロンプト主要エンティティと Plan の照合キーワード検証ロジックを実装 (盲点 #11 対応)。
5.3 中立・トレードオフ (Neutral / Trade-offs)
- 改修前 (45 分 1-shot) は 71% 失敗 + 45 分無駄、改修後 (Plan-then-Chain) は ~$0.20 追加 + 9 分平均完走。コスト/時間トレードオフは明確に改修後が有利 (ただし暫定値、4 週検証で確定)。
- 本 ADR は「Google API の non-deterministic 起動経路を hack して回避する」性質を持ち、Google 側の改修で陳腐化する可能性がある (例: 04-2026 preview の startup を改善するパッチが入れば直接 fire に戻せる)。直接 fire の成功率を月 1 回 n≥3 自動 A/B 観測 (盲点 #7/#12 対応)、80% 超回復で 2-phase 廃止を能動的に提案するアラート (§6 #4)。Devil's Advocate チェックを 4 週レビュー時に必須化し「この結果は Plan-then-Chain の効果以外で説明可能か」を明示的に問う。
- Plan 自動承認 (
Plan looks good. Proceed...) は実質的に Plan-mode の便益 (起案者レビュー) を犠牲にしている。スコープ縮小・前提変更が必要なケースには対応不能。当面は run_deep_research.mjs の用途 (定型クエリ 5 設問) で問題ないが、対話的用途にはGEMINI_PLAN_REVIEW経由の案 F で対応。 - Phase B timeout 40 分は API 公称最大 60 分からの逆算で実測 p95 に基づかない。Phase B ポーリング中に 15 分・25 分・35 分の各時点で warn ログ、タイムアウト発生時に「timeout 起因の失敗」と「flaky startup 起因の失敗」を区別するフラグを付与し Wilson 信頼区間計算から timeout 起因を除外可能とする (盲点 #5/#9 対応)。n=5 到達後に「前回 n 件の p95 × 1.5 倍」への動的調整ロジックを実装。
コスト試算 (4 週検証期間の月次概算)
- 起案頻度: 月 ~10 件想定 (RQ ベース、ピーク時 ~20 件)
- Plan phase 追加コスト: $0.10-0.30 × 10 = $1-3/月
- A/B 観測月 1 回 (直接 fire コントロール群 n≥3 自動試行): $1-3 × 3 = $3-9/月
- 検証期間 4 週合計: $4-12 + 統計集計スクリプトのランタイム微少 (Workers 課金圏外)
- 撤退判断データ収集の絶対前提 (
.gemini_execution_log.jsonl等) は無料 (ローカルファイル append-only) - 撤退判断後の案 B (12-2025) 切替時はコスト不変 (search cost のみ)、案 D' (max 直接 fire) 切替時は 1 起案あたり ~$3-7 で月 ~$30-70 増
6. 撤退条件 (Rollback Plan)
撤退条件を多項目並列監視する複雑性 (盲点 #13) を回避するため、最優先 K.O. 条件 (#1/#3) と 改善トリガー (#2/#4/#5/#6) の 2 階層に分類する。最優先条件のいずれかが発動した時点で他条件の判定を待たず撤退着手する。
最優先 K.O. 条件
- #1 統計的確定失敗: 本番投入後 4 週間で Plan-then-Chain 成功率 n≥15 を蓄積した際、Wilson 信頼区間上限が 20% を超える場合、または同期間の直接 fire コントロール群 (月 1 回 n≥3 自動試行) と成功率差が統計的有意でない場合 → 案 B フォールバック (12-2025 切替) または案 D' (max 直接 fire) を発動 (盲点 #1/#12 対応の事前検証結果による分岐)。
- #3 Phase A 単独 timeout 率 ≥ 20% が 2 週連続: Plan-mode 自体が flaky 経路と統合されたことを示す独立指標。仮説 (Plan-mode は別経路) が崩壊したと判断、案 B または案 D' へ即時撤退。
改善トリガー (発動時は条件 #1/#3 の判定加速)
- #2 撤退先の事前検証完了: 案 B (12-2025) と案 D (max) の直接 fire 成功率を本 ADR 採択と並行して n≥5 / n≥3 で計測し、撤退発動時の移行先を事前に確定する (盲点 #1/#5 対応)。
- #4 直接 fire の回復: 月次 A/B 観測で直接 fire 成功率が 80% 超に回復した場合、2-phase 廃止を能動的に提案 (Google 側修正による陳腐化の検知、盲点 #13 対応)。
- #5 Plan 自動承認の利用規約違反化: Google が collaborative_planning に human-in-the-loop を必須化、または
"Plan looks good. Proceed..."自動承認を ToS で明示禁止した場合 → 案 F (GEMINI_PLAN_REVIEW=trueインタラクティブ承認) へ切替、継続困難なら案 B。 - #6 モデル GA 移行・非推奨化:
deep-research-preview-04-2026の GA リリースまたは非推奨告知時、新モデル名で Plan-then-Chain smoke test を事前実施し非互換時は案 B または案 D へ。
撤退発動の絶対前提
撤退判断に必要なデータ収集 (append-only ログ .gemini_execution_log.jsonl / Phase A 独立計測 .gemini_plan_stats.json / 直接 fire コントロール群 .gemini_direct_fire_stats.json / zombie 記録 .gemini_zombie_interactions.json) は PR #1179 マージ前の CI ゲート で機械的に強制する。未実装でのデプロイは技術的にブロック (盲点 #13 対応)。
実装ロールバック手順
撤退発動時の実装変更手順:
- コードレベル: PR #1179 (Plan-then-Chain 実装) を
gh pr revertで逆コミット PR を起案 → main マージでrunGemini()を改修前の 1-shot 実装に戻す。 - 設定レベル (一時退避): 環境変数
GEMINI_MODELをpro-preview-12-2025に切替 (案 B) またはmax-preview-04-2026に切替 (案 D')。コードを残したまま Plan phase をスキップする feature flag は本実装に組込まれていないため、コード revert または環境変数切替の二択。 - データ保存: 撤退前の
.gemini_execution_log.jsonl/.gemini_plan_stats.jsonは撤退判断の根拠資料として archive 化 (docs/_internal/06_ops/changelog.mdに絶対パス記録)。
Confirmation
- 検証手段:
.gemini_execution_log.jsonlの append-only ログから Phase A/B 成功率・Wilson 信頼区間・Phase A→B 遅延・timeout 起因失敗フラグを集計するスクリプト (scripts/audit_gemini_stats.mjs、本 PR フォローアップで実装)。- 月次の直接 fire コントロール群自動試行 (n≥3) と Plan-then-Chain 成功率の差分検定。
- adr-lint による本 ADR の §6 撤退条件と実装の整合性チェック (撤退条件で言及した環境変数
GEMINI_PLAN_TIMEOUT_MIN/GEMINI_RESEARCH_TIMEOUT_MIN/GEMINI_PLAN_REVIEW/GEMINI_MODELがコード内に存在するかの grep ベース検証)。
- 実行頻度: append-only ログ集計はスクリプト起動時に自動表示 (毎回)、月次 A/B 観測は cron で月初実行、4 週レビューは起案 4 週後の固定日。
- 違反時対応: Phase A timeout 率 ≥ 20% が 2 週連続検知 → §6 #3 自動アラート → 撤退着手。4 週時点で Wilson 上限 ≥ 20% または直接 fire との有意差なし → §6 #1 発動、§3.2 注 2 の手順で案 B または案 D' へ移行。zombie 5 件超 → 新規 research 起動を機械的ブロックし起案者に手動 cleanup を要求。
11. 参照: Pipeline 審査履歴 (2026-05-30 実行時, 通常 flow)
本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を通常 flow (retroactive=false) で審査した結果のログ。v5 (KV:
gemini-deep-research-queue-plan-mode-heartbeat-) は Cross-Validation 差し戻し (Score 42/50、#reliable=5を毀損する critical 盲点 2 件) → v6 で#reliable暫定 5→3 (4 週検証で昇格条件付き) + 加重和 0.870→0.770 + §6 撤退条件 #1 を「スコア確定条件」に再フレーム + §6 #3 に Phase A 単独 timeout 率独立計測を新設 + §2/1.5 で条件付き採択を本文格上げ → Score 44/50 + Cross-Validation Must 軸毀損なしで通過。デフォルトでは折りたたまれており、▶をクリックで展開する。
📋 Pipeline 審査履歴 全 Gate 結果 (合格 Score 44 / 50, v5 42 → v6 44 +2 pt) — クリックで展開
Gate 0-4 結果 (v6 実行)
- Gate 0 Triage: needsAdr=true / triageMode=Standard
- Gate 1 Socratic: 盲点 13 件検出 (全件
actionability=monitor、§5.2/5.3/§6 撤退条件に反映済) - Gate 2 Consistency: INFO (既存 ADR と直接矛盾なし、ADR-0042/0056/0081 と方向整合)
- Gate 3 Parallel Review: Gemini が「サンプル数不足による統計的脆弱性を認識し、明確な定量基準に基づく条件付き採択と撤退条件を定義している点はアーキテクチャ決定として非常に堅牢」と評価
- Cross-Validation (盲点 × Must): PASS (Must 軸
#reliableの毀損ゼロ。High/Medium 軸の毀損は §5.2/5.3 で個別対応) - Gate 4 Scoring: 44 / 50 (scoringMean 44.2, stdDev 1, Standard 閾値 40 + 4pt 余裕)
| # | 採点項目 | 点数 | コメント |
|---|---|---|---|
| 1 | 問題定義 | 5 | 71% 失敗率 (n=7)、T2-T10 系統的調査、本番実測 9.4 分、n=3 の 95% CI=[0%, 70.8%] まで自ら開示 |
| 2 | 代替案 | 5 | 案 A-F 計 6 案、各却下理由明示。案 B/D の未検証ブラインドを自ら認識し並行検証を設計に組込 |
| 3 | 判断基準 | 5 | 5 軸 × 重要度係数、加重和正規化、K.O. 基準、注 1 で案 B の制約由来失格、注 2 で v5→v6 の #reliable 引下げ経緯を明示 |
| 4 | 過去 ADR 整合性 | 1 | 「関連 ADR: -」のまま (本 PR で §参照 関連 ADR ブロック充足) |
| 5 | 影響範囲 | 5 | 改修ファイル / 環境変数 4 種 / ログファイル 4 種 / Workers 非互換 / 呼出 I/F 不変まで網羅 |
| 6 | 運用上の罠 | 5 | 盲点 #1-#13 を明示的に検証、Phase A→B 遅延・連結失敗検知・zombie 2 段階通知を明記 |
| 7 | ロールバック性 | 5 | 2 階層撤退条件 (最優先 K.O. #1/#3 + 改善トリガー #2/#4/#5/#6)、CI ゲート強制 |
| 8 | コスト試算 | 3 | Plan ~$0.20/起案 + 削減効果は記述ありだが、4 週検証期間の月次総額が概算で示されていない (本 PR で §5.4 に月次概算追記) |
| 9 | 完了条件 | 4 | Confirmation 3 要素 (検証手段 / 実行頻度 / 違反時対応) |
| 10 | 長期影響 | 5 | 段階導入 + 4 週レビュー + 8 週 A/B 観測 + follow-up |
合計: 44 / 50 (Standard 閾値 40 → PASS, Cross-Validation Must 軸毀損なし)
Status 遷移
- v5 起案 (2026-05-30 03:36Z KV 投入) → Pipeline 通常 flow 42/50 差し戻し (
#reliable=5を毀損する critical 盲点 2 件) - v6 改訂 (2026-05-30 04:00Z 再投入、#reliable 暫定 5→3 + 加重和 0.870→0.770 + §6 撤退条件 #1 再フレーム + §6 #3 新設) → Pipeline 再投入 → 44/50 通過 → auto-PR #1189 生成 (Proposed)
- 本 PR で Status: Proposed → Accepted に更新、推奨改善コメント (関連 ADR 参照欄 / 実装ロールバック手順 / 4 週検証期間月次総コスト概算) を同時反映
参照 (References)
- 関連 ADR:
- ADR-0042 (Prompt Lifecycle) — モデル名
GEMINI_MODEL環境変数化は Type 1 prompt の model_pin 思想と整合。並立。 - ADR-0056 (LLM temp/sampling stage-hybrid strategy) — 本 ADR は Pipeline 外 (
scripts/run_deep_research.mjs) を対象だが、将来 Pipeline 経由で Deep Research を呼ぶ場合は §4.1 推奨範囲との整合確認が必要 (ADR-0056 を再参照する Phase B PR 起案時の整合チェックリスト項目として組込)。補完。 - ADR-0081 (Decision Pipeline LLM 耐障害性 retry/Promise.allSettled/JSON parse) — Phase A/B タイムアウト + cleanup + 統計計測の設計思想は ADR-0081 の retry パターンと方向性が一致。並立。
- Supersede / Conflict なし。
- ADR-0042 (Prompt Lifecycle) — モデル名
- 関連 PR/Issue: PR #1179 (実装)、RQ-085 (起点案件)
- 外部資料:
tmp/gemini-investigation-2026-05-30.md(T1-T10 系統的調査ログ)- Google AI Studio Terms of Service / Deep Research API 利用ポリシー §4 Prohibited Uses (自動承認条項の精査は §6 #5 撤退条件の判定資料として別途記録、URL は規約改訂頻度のため fix せず週次確認時の現行版を参照)
- Gemini API Deep Research 公式ドキュメント (
https://ai.google.dev/gemini-api/docs/deep-research、§ "maximum research time of 60 minutes" 記述箇所) - 電帳法 §7 電子取引データ保存要件 (2026 時点宥恕措置終了済)
- DeepSearchQA / Humanity's Last Exam ベンチマーク公式数値 (04-2026: 93.3% / 12-2025: 66.1%)