Decision Pipeline 起案者ガイド (LangGraph 版)
TL;DR(このページは何か・専門語ゼロ): 会社の大きな決めごと(仕組み・業務ルールの変更など)を提案するとき、AI が順番に下調べと採点をして「記録に残す価値があるか」「見落としや過去の決定との食い違いがないか」を確認してくれます。基準点に届いた提案だけが、決定の下書きと変更依頼として自動でまとめられ、最終承認は代表取締役だけが出します。AI はあくまで審査役で、決める責任は提案した人と代表取締役が持ちます。このページは、その提案の出し方・通し方・つまずいたときの対処を順に説明する手引きです。
Status: Active (LangGraph TS + Hono on Cloudflare Workers + LiteLLM Gateway + GitHub Actions) 対象: 起案者 (社内メンバー / 業務委託パートナー / 代表取締役) で Decision Pipeline を使って ADR を起案する人 基盤決定の根拠: ADR-0019 Dify 時代の操作手順 (履歴用): operator_guide.md (Retired) エンドポイント: https://drp.bizlp.dev/
1. はじめに
本ガイドは、bizlp-gas-accounting プロジェクトで アーキテクチャ・業務設計上の決定 を行う際の起案ルールをまとめたものです。
Decision Pipeline は AI を使って "判断品質を機械的に確認する関門" として動きます。AI 自動生成ツールではなく、人間の判断品質を審査するインフラです。
1.1 大原則
- AI は審査員、起案者は人間 AI は問診・採点・指摘を行いますが、決定の責任は常に起案者と代表取締役が負います。
- 40 点未満は差戻し 品質スコアが Mode〔モード=起案の重要度区分〕別閾値に達しない起案は PR 化されません。AI と壁打ちして起案者が自身でドラフトを磨く流れです。
- AI に責任を委ねない PR 概要欄には「AI のレビューを踏まえた上で、最終的にこの決定で進めたい理由」を起案者自身の言葉で 1 行記述してください。
- Status〔ステータス=ADR の承認段階〕遷移権限の分離
起案者は
Status: Proposedの PR を作成。Accepted/Supersededへの遷移は 代表取締役 が判断します。
2. アクセス・認証
2.1 Web UI
| 用途 | URL |
|---|---|
| 標準フォーム起案 | https://drp.bizlp.dev/ |
| Chat 形式 (Socratic 問答対話) | https://drp.bizlp.dev/chat |
| Chat (terminal 風 UI) | https://drp.bizlp.dev/chat-terminal |
2.2 認証情報
二段階認証:
- Cloudflare Access (Google SSO) — 業務利用の Google アカウントで認証
- Basic 認証 (
AUTH_USER/AUTH_PASSWORD) — 代表取締役から共有
Cloudflare Access の招待は代表取締役から送付。個人 Gmail は不可。
2.3 GitHub アカウント (任意)
GitHub への直接コミット権限は不要。Decision Pipeline 経由で Bot が PR を作成するため、起案者は GitHub アカウントを持っていなくても起案できます。
ただし PR のレビューコメントへの返答には GitHub アカウントが推奨されます (なければ Slack / メールで対応可)。
3. ADR を起案すべきケース
| ✅ ADR にすべき | ❌ ADR 不要 |
|---|---|
| データモデル変更(タブ追加・列追加・削除) | 既存タブの値修正 |
| 仕訳ロジック・期ずれルール変更 | 軽微なバグ修正 |
| 外部 API・SaaS の追加・移行 | 既存 API のパラメータ調整 |
| 業務プロセス変更(締め日・承認フロー) | 通常の月次運用 |
| 不可逆なデータ移行 | データ整備 |
| 複数モジュール横断の設計判断 | 単一モジュール内のリファクタ |
| 採用 / 退職 / 業務委託の方針変更 | 個別の契約調整 |
迷ったら Web UI に投げて Gate〔ゲート=審査の関門〕 0 (Triage〔トリアージ=ADR 要否と重要度の振り分け〕) の判定を見てください。AI が「ADR 不要」と判定すれば差戻しされます。
4. 起案手順 (LangGraph 版 / 5 ゲート)
4.1 ステップ 1: ドラフトを書く
Markdown 形式で以下の項目を ## で始まる H2 セクションとして並べたドラフトを作成します。Pipeline body_generation がこの入力を canonical ADR 構造 (§1.1/§1.2/§2 決定/§3 判断基準…) に正規変換します。
title 規約 (2026-06-05・代表取締役指示): draft の title (H1 / payload の title フィールド) に 「(Standard)」「(Critical)」等の mode サフィックスを付けない。mode は triage が判定するものであり、title に書くと判定のアンカーになり得るうえ、ADR 名としてそのまま残る。審査深度を指定したい場合は
modeOverrideパラメータを使う。
## 何を解決するか: 具体的な問題・目的 (定量根拠 1 つ以上)## 採用したい方針: まず Y-Statement で 1 文圧縮 (「X 文脈で Y 課題に直面し、A 対抗案でなく Z 選択を選ぶ。B 目的のため、C 代償を受け入れる」) → 続けて 1 段落で要旨。Z→本節 / A→検討した代替案 / B→判断基準 / C→影響・撤退条件 の種になる。1 文に収まらない・Z に「かつ」が入るなら下の粒度チェックへ## 判断基準(Standard 以上は必須 / ADR-0053): 評価軸を Q42 9 タグ (#reliable/#flexible/#maintainable/#efficient/#usable/#operable/#suitable/#secure/#safe) から 3-5 個選定 + 重要度 (Must/High/Medium) + K.O. 基準。粗くてよいが「軸が暗黙のまま採点される」状態を避ける目的。詳細: adr_decision_drivers_guide.md## 検討した代替案: 最低 2 つ、それぞれの不採用理由## 影響: 正/負/リスク## コスト試算(Standard 以上は必須 / ADR-0088): 実装工数 (人日) + 運用コストを粗くても数値 1 つ以上。完璧でなく「数値で考えた痕跡」を残す。欠落は起案前ゲートで差し戻し対象。## 撤退条件(Standard 以上は数値必須 / ADR-0091): どうなったら戻すか。数値 1 つ以上の閾値を含める (例: 失敗率 20% 超で撤退)。## Confirmation(fitness function〔フィットネス関数=決定が実装で守られているか自動で測り続ける仕掛け〕) (Standard/Critical は必須 / ADR-0036 + ADR-0091): 決定が実装で守られているかを継続的に検証する手段を 3 要素 (検証手段 / 実行頻度 / 違反時対応) で記述、観測可能 KPI〔重要業績評価指標=成否を数値で測る物差し〕 (数値 1 つ以上) を含める。例:adr-lint ルール XYZ/CI 毎/テスト失敗で merge block。Light + 純ドキュメント ADR は N/A 許容 (理由必須)。欠落すると Pipeline が(要追記)プレースホルダーを出力し adr-lintno-placeholder/no-placeholder-marker違反になる。## 過去 ADR との関係(推奨): 関連する既存 ADR があれば言及
📦 draft.json の任意フィールド (business / navGroup)
起案テキストとは別に、draft.json (payload) へ次の任意フィールドを書ける (PR #1830 / #1833)。生成 ADR の frontmatter 事業軸と nav 登録は CI が自動処理する。投入方法は従来どおり scripts/draft_push.sh (draft.json を素通しで POST するため、JSON にフィールドを足すだけ。スクリプト改修は不要)。
| フィールド | 値 | 意味 |
|---|---|---|
business | corp / mas / drp | 生成 ADR の frontmatter 事業軸 (INDEX ドメイン列の原本)。指定推奨。nav 登録先の既定グループも決まる: corp→A.09.5 / mas→A.09.3 / drp→A.09.4。未指定は corp 扱い (A.09.5) で、business 行は frontmatter に入らない (lint は nav グループ判定にフォールバック) |
navGroup | A.09.1〜A.09.7 | nav 登録グループの明示上書き。既定マップで合わないときだけ書く (例: business は corp だが docs サイト系の決定 → A.09.6)。PR 本文の <!-- nav-group: A.09.N --> マーカー経由で CI に渡る |
7 主題グループの対応: A.09.1 / A.09.3 = MAS・A.09.2 / A.09.4 = DRP・A.09.5〜A.09.7 = Corp。
📏 粒度の目安 (起案前セルフチェック / RQ-097・強制ではない)
1 ドラフト = 1 論点が原則。まず「採用したい方針」の Y-Statement で 1 文に圧縮できるか試す (1 文テスト)。次が 1 つでも当てはまれば分割を検討する (多論点ドラフトは過剰審査ループ ADR-0109 を誘発しやすい):
- 決定文に「かつ / および / また」「〜かもしれない / おそらく」が入る
- 独立して撤退・ロールバックできる決定が 2 つ以上ある (決定変数 ≥ 2)
- 判断基準 (ドライバー) / 撤退条件 / KPI が別々に分かれる
- Context が 1 ページ (〜800 語) を超える
- ステークホルダー・承認者が分かれる
逆に、ドライバー・撤退条件・supersede の運命が完全に一致するなら 1 枚に統合してよい。情報が足りず決められない論点は、ADR でなく時間を区切った下調べ (spike) を先に行い、材料が揃ってから起案する。判定マトリクスの詳細は RQ-097 synthesis。
これは目安であり、起案前ゲートで機械強制はしない (2026-06-08 決定)。まず telemetry (ゴールポスト差し戻し率・多論点起因の事後分割件数) を蓄積し、効果と必要性を見たうえで、必要なら強制ゲート化を別途検討する。
💡 ドラフト作成段階で Claude Code / ChatGPT 等を壁打ち相手にするのは推奨。ただし最終的な判断は起案者が下してください。
📋 canonical テンプレート:
docs/_meta/templates/adr-draft.template.mdにコピペ可能な完成形と JSON 起案構造を集約。AI agent も参照可能。
⚠ アンチパターン (rendered ADR 構造で書かない)
起案テキストは rendered ADR ファイル (docs/adr/NNNN-*.md) の構造を模倣しないでください。以下は body_generation の 出力フォーマットであり、入力としては不適切:
### 1.1 背景 ← ❌ rendered ADR の番号付き H3
### 1.2 現状 (As-Is) ← ❌
## 2. 決定 ← ❌ 番号付き H2
## 3. 判断基準 (Decision Drivers) ← ❌
正しくは上記 bullet 項目をそのまま H2 化:
## 何を解決するか ← ✅
## 採用したい方針 ← ✅
## 判断基準 ← ✅
## 検討した代替案 ← ✅
rendered 構造で起案テキストを書くと、(1) body_generation の正規化を浪費、(2) Cross-Validation のセクション構造比較が機能しない、(3) doc/main 間の起案フォーマットが乱れる、の 3 つのトレードオフが発生します。
完成例 (graph-check ADR draft、doc 形式)
## 何を解決するか
`docs/architecture/decision_pipeline.mmd` の自動生成 header に commit hash を埋め込むため、
graph-check workflow が毎 PR で必ず drift FAIL する。直近 2 日で merge された 約 30 PR の
ほぼ全件が admin merge で bypass、本来検知すべき真の graph 構造変更がノイズに埋もれる。
## 採用したい方針
`export-graph.mjs` の header から `%% Commit:` と `%% Generated:` の 2 行を削除する。
## 判断基準
| 軸 | 重要度 |
|---|---|
| `#reliable` | Must (真の構造変更検知が機能) |
| `#maintainable` | High (修正量 2 行) |
## コスト試算
実装 0.05 人日 (header 2 行削除) + ADR 化 0.25 人日 = 約 0.35 人日。直接金銭支出 0 円。
## 撤退条件
4 週で graph-check 起因の admin merge が 1 件以上発生したら案 C (content-only filter) へ移行。
## Confirmation
検証手段: `gh search` で graph-check 起因 admin merge 件数を月次集計
実行頻度: 月次
違反時対応: §撤退条件 #1 発動、案 C へ移行
KPI: graph-check 起因 admin merge / 月 (目標 0、許容上限 1)
数値の書き方ガイド (未確定を残さない / 根拠不明時の最低基準) — ADR-0091
## 撤退条件 と ## Confirmation は Standard 以上で数値必須。ただし「通過のために根拠なき数値を埋める」(形式的数値の水増し) と「≥99% 等の単独 KPI を満たしに行く」(グッドハートの法則) は逆効果になる。以下の規律で書く。
(a) 未確定を残さない — (要追記) / TBD / ??? / 理由なき N/A 等のプレースホルダーを本文に残さない (adr-lint no-placeholder-marker / no-placeholder 違反)。数値が出せない場合は空欄にせず「なぜ出せないか + いつ確定するか」を 1 行で書く (例: 本番ログ未取得のため暫定。Phase A merge 後 4 週で実測値に置換)。
(b) 撤退・完了は数値で — 撤退条件は閾値を最低 1 つ (例: 失敗率 20% 超 / p50 レイテンシ 5s 超で撤退)。Confirmation は観測可能 KPI を最低 1 つ (例: エラー率 / 件数 / 削減率)。「改善する」「安定させる」等の定性表現だけで終えない。
(c) 根拠不明時の数値の書き方 — 精密値を装わず推定であることを明示する。約 / オーダーで / (推定) を付け、根拠を 1 行添える。
- ❌ 悪い例:
完了条件: 整合率 99.5%(根拠なき精密値 = 水増しに見える) - ✅ 良い例:
完了条件: 整合率 ≥ 99% (現状サンプル n=12 で 100%、母数増を見込み許容下限を 99% に設定。根拠=現行実測)
(d) 許容される数値の最低基準 (3 パターンのいずれかを満たせば「数値で考えた痕跡」として可)
- オーダーマグニチュード推定 — 桁感で十分。例:
年 100 件規模 × $0.05-0.15/件 → LLM コスト $5-15/年削減。 - 文献・公開値の引用 — 外部基準を根拠に。例:
Cloudflare Workers Free 100k req/日 (公式値) を上限前提に設定。 - 類似案件の実績流用 — 過去 ADR/実装の数値を引く。例:
ADR-0088 で同機構 (起案前ゲート + §4.1 + adr-lint) が 2.0 人日だったため本件も同程度と見積もり。
💡 グッドハート回避: 完了条件を「割合 ≥99%」の単独評価に依存させない。
## Confirmationの複数 KPI、または Gate4 平均点上昇 (ADR-0091 §7/§9) を主 KPI として併用し、単一指標の最適化に陥らないようにする。
4.2 ステップ 2: Web UI で投入
Web UI を開き、ドラフトテキストを貼り付けて実行。Pipeline は以下のゲートを順次通過します:
Gate 0 (Triage)
↓ ADR 要否 + Mode 判定
Gate 1 (Blind-spot Detection) ※情報提供型 (差戻しなし / ADR-0071)
↓ Devil's Advocate + Pre-mortem + Judge 並列 DAG → 盲点レポート生成
↓ ※視点選択は原稿内容で決定化 (Part3): 無改変で再投入すると毎回同じ 3 視点・同じ盲点になる
Body Generation
↓ 本文自動生成
Gate 4 (Scoring)
↓ 50 点満点採点 (Mode 別閾値未満で差戻し)
Cross-Validation (盲点 × Must 軸 整合検証 / ライフサイクル整合バー)
↓ critical 盲点が Must 軸スコアの前提を毀損する場合に差戻し (ADR-0076)
↓ ※trailing 連続却下で盲点が毎回「移動」(goalpost) or 連続却下が round-cap (既定3) 到達 → 自動 reject せず残余リスク付きで PR 起票、merge=受理/close=却下 が終端 (Part4 / ADR-0109)
Gate 2 (Consistency)
↓ 過去 ADR 整合性 (CONFLICT 検出時は差戻し)
Gate 3 (Parallel Review) ※情報提供型 (差戻しなし)
↓ Gemini Pro / Claude Opus / o3 の 3 モデル並列レビュー
Policy Alignment ※情報提供型 (差戻しなし)
↓ 会社固有の意思決定方針との整合評価
PR 自動作成 (Status: Proposed)
4.3 各ゲートの起案者観点ハイライト
| Gate | 役割 | 差戻し条件 | 起案者の対応 |
|---|---|---|---|
| 0 Triage | ADR 要否 + Mode 判定 | is_adr_worthy: false | 理由確認 → 不要なら終了、必要なら追加情報で再投入 |
| 1 Blind-spot Detection〔ブラインドスポット検出=盲点の洗い出し〕 | 盲点検出 (DA〔Devil's Advocate=あえて反論する役〕+PM〔Pre-mortem=事前の失敗想定〕+Judge〔ジャッジ=指摘の統合役〕) | (差戻しなし、情報提供型) | PR 本文の Blind-spot Report を確認し、指摘に対応が必要か判断 |
| Body Gen | 本文自動生成 | (差戻しなし) | 生成本文を確認 |
| 4 Scoring | 50 点採点 | Mode 別閾値未満 (Light 35 / Standard 40 / Critical 45) | スコア内訳と最低スコア項目の指摘を確認 → 修正 → 再投入 |
| Cross-Validation〔クロスバリデーション=盲点と評価軸の突き合わせ検証〕 | 盲点 × Must 軸の整合検証 (ライフサイクル整合バー) | critical 盲点 × Must 軸 × undermines (非 critical / 非 Must は情報提供のみ)。実装時にしか検証できない前提は、本文にこのリスクを防止/検出する具体的緩和機構 (具体設計 / Confirmation〔確認手段=決定が守られているか継続検証する仕組み〕 / 撤退条件) があれば毀損とみなさない | 毀損指摘を確認 → 前提を補強 or 該当 Must 軸スコアを再評価 → 再投入。ただし「Goalpost〔ゴールポスト移動=指摘が毎回ずれて終わらない状態〕ループ検知」or「bounded rounds 上限到達」メッセージが出たら: 自動審査は打ち切られ、ADR は「Known Limitations / Escalated Residual Risks」節付きで PR として自動起票される (Part4 / ADR-0109)。起案者は再投入でなく、代表取締役の PR merge=受理 / close=却下 で最終判断する (= 人間レビューが LLM ループ外の検証器)。同一盲点の持続却下は通常どおり差戻し |
| 2 Consistency | 過去 ADR 整合性 | CONFLICT 検出 + Supersede 宣言なし | 矛盾 ADR を確認、後継宣言 (Supersede ADR-XXX) を追加 |
| 3 Parallel Review | 3 モデル付加価値レビュー | (差戻しなし、情報提供型) | PR 本文の 3 モデル評価セクションで参考にする |
| Policy Alignment | 会社固有方針との整合評価 | (差戻しなし、情報提供型) | PR 本文の Policy Alignment セクションで方針逸脱の有無を確認 |
4.3.1 差し戻し時の再投入ルール
Gate 4 Scoring で差し戻された場合、Pipeline が生成した ADR 本文をそのまま context に再投入しない。Pipeline 出力には自動付与されたメタデータ (Status/Mode/起案者等)、§ 番号付きサブセクション構造、評価軸テーブル、加重和計算、Confirmation セクション、References が含まれており、これらを再投入すると Pipeline が自分の出力を入力として受け取り構造が二重化する。
再投入時の context は以下の形式で整理する:
- 起案者の生テキスト (§4.1 のドラフト形式) をベースにする
- 差し戻し指摘で求められた 追加情報 (工数試算、エラーハンドリング、DoD 等) を追記する
- Pipeline が自動生成する要素は 除外 する:
- H1 タイトル + メタデータブロック (Status/Mode/起案者/Deciders)
- §1.1-1.5 等のサブセクション番号 (Pipeline が Mode に応じて構造化)
- §2 判断基準の評価軸テーブル・加重和計算 (Pipeline が生成)
- §5 Consequences の Good/Bad/Neutral サブセクション分類
- Confirmation セクションの検証手段 (Pipeline が生成)
- §7 References / §7.1 プロジェクト内参照 (Pipeline が生成)
💡 要するに「自分が書いた判断の素材 + 差し戻しで求められた補強」だけを投入し、Pipeline のフォーマッティングは Pipeline に任せる。
4.3.2 審査通過後の PR 作成 (UI run は「PR 作成」ボタンが正規)
- web UI から起動した run は、審査に通過しても PR を自動で作らない(設計)。結果画面の**「PR 作成」ボタン**を押すのが正規の手順。status の pr_url が空でも故障ではない。
- PR の自動作成は API/CI 経路 (
POST /runs+dry_run=false) だけの機能 (ADR-0064)。 - 暫定注記 (2026-06-12): 「明示の指示があったときだけ PR を作る」方式へ UI/CI 共通で統一する変更を main へ依頼済み (
tasks/prompts/main_2026-06-12_drp-pr-creation-explicit-flag.md)。実装後に本節を確定記述へ更新する。
4.3.3 受付プリゲートの「pass」の意味 (ADR-0142 本番稼働 2026-06-15)
② 受付の問題空間切り分けプリゲート (ADR-0142) は 2026-06-15 に本番稼働した (PR #2043)。プリゲート稼働後、起案者は次の点を誤解しないこと。(なお Cross-Validation の 2 段化・第 1 段〔socratic 直後の早期差し戻し・ADR-0143〕は実装着手前パイロットで K.O. となり、ADR-0154 で撤回・実装中止になった。本番 CV は従来どおり body 後の単一段で動く。)
- プリゲート pass は「検問 4 つ+前提の行き先解決」の通過のみを意味する。分析全体の正確性は保証しない。審査と人間レビューは従来どおりの深さで行う (レビュアーのチェックリストにプリゲート結果の参照項目は置かない・ADR-0142 §5.2)。
差し戻し時の見え方:
- プリゲート差し戻し = 判定理由+本文からの逐語引用が返る。対象は検問 1 (塊の混在)・検問 2 (モレ・ダブり・同種)・検問 3 (再発防止)・検問 4 (宙に浮いた対応策)・行き先のない前提のいずれか (構造正典 §D-3)。
- プリゲート差し戻しは bounded rounds (ADR-0109・既定 3) の枠内で本番 CV と通算される。
4.3.4 ADR-0142 受付プリゲート月次 precision レビュー手順
ADR-0142 のプリゲートが正当な差し戻しを返しているか月次で確認する手順。
集計 SQL
drp/queries/adr-0142-pregate-observation.sql を本番 D1 で実走する。ブロック A-F は次の通り。
- ブロック A: 月次 pregate_verdict 分布 (pass / fail / invalid)
- ブロック B: 月次 valid / invalid 集計
- ブロック C: FAIL 理由分布 (root_multiple / dangling_premise)
- ブロック D: INVALID 詳細 (機械照合失敗の証跡)
- ブロック E: pregate_stage 分布 (primary vs secondary)
- ブロック F: evidence 逐語一致率 (機械照合 KPI 100%)
実走コマンド:
cd drp && pnpm exec wrangler d1 execute decision-pipeline-telemetry --remote --json --command "<ブロック SQL>"
人手ルーブリック判定フロー
precision の分母と分子を次のように決める。
- 分母 = FAIL 件数 (ブロック A の
fail_count) - 分子 = 人手で「正当な差し戻し」と判定した件数
- 判定者 = DRP 運用者 (現任 = 代表取締役・ADR-0142 §Review After)
- 判定基準 = 差し戻し理由が本文逐語引用で実体を持つこと + 検問 1-4 のいずれかに該当すること
- 異議手順 = 起案者が判定に異議を申し立てた場合は run の telemetry を引いて再判定。判定揺れは月次で集計
ルーブリック未定義のリスクは ADR-0142 §運用 K.O. に「ルーブリック未定義で precision 集計が属人化」と high で記載済み。本節がその受け皿。
撤退条件発火時の対応
ADR-0142 §撤退条件 (Rollback Plan) に逐語で従う。
- precision < 70% (20 run 集計後) → graph 分岐 OFF。D-1 該当記録に「プリゲート由来・precision 閾値未達のため参照停止」フラグを付与
- INVALID ≥ 3 件 (20 run 集計後) → 設計見直し。NFKC 移植の前倒し検討 (ADR-0157 C2 fix の波及候補)
4.4 ステップ 3: PR レビュー
合格後、PR 作成 (UI は「PR 作成」ボタン / CI は自動・§4.3.2) で BizLinkPartners/bizlp-gas-accounting に [ADR-NNNN] ... というタイトルの PR が作成されます。
PR 本文に含まれる情報:
- 起案者名
- Triage 結果 (Mode / 理由)
- Blind-spot Report (Gate 1 の盲点検出結果、severity 付き)
- Scoring サマリ (10 項目 × 5 点)
- Consistency 結果 (関連過去 ADR + Conflict/Supersede 判定)
- Parallel Review 3 モデル評価 (Gemini Pro / Claude Opus / o3)
- Policy Alignment 評価 (会社固有方針との整合)
- ADR ファイルへのリンク
- 起案入力原文
レビュー時の確認項目 (ADR-0138):
- 冒頭「決定の早わかり」の 7 箇条 (文脈/問題/問題点と課題/前提/決定/目的/代償) が型の正典 (ピラミッド原則 §D) どおりで、定型句や空の体言止めの羅列になっていないか。末尾の定型注記 (詳細は本文参照) があるか
- 早わかりの全面書き直しが必要だった場合は件数を記録する (月次集計・ADR-0138 撤退条件 #1 = 新規 10 本中 6 本以上で必須化撤回、の判定に使う)
代表取締役がレビューし、コメントが付いた場合は:
- GitHub 上で直接返信(GitHub アカウントがある場合)
- または Slack / メールで返信
4.5 ステップ 4: マージ
代表取締役が PR をマージすると Status: Accepted に自動更新されます。
PR が Close された場合は Status: Rejected に更新されます。理由を確認し、必要なら別案を起案してください。
4.6 Retroactive Validation モード (ADR-0052)
既に main に取り込まれた ADR を事後検証 (Pipeline 自己審査) する場合は retroactive〔レトロアクティブ=既に決まった ADR を後から審査する〕モードを使う。誤って /chat/create-pr を呼んで不要な PR が生成される事故 (2026-05-18 PR #821) の構造的防止が目的。
起案の流れ (chat UI):
/chatの「☁️ サーバー draft」セクションで「⬆️ アップロード」- ローカル JSON 選択 → ID 入力後、確認 dialog で:
- OK = retroactive validation 用 (PR 作成は無効化)
- キャンセル = 通常の新規 ADR 起案 (PR 作成可)
- retroactive=true で投入した draft をロードすると:
- 上部に 🔒 Retroactive validation mode banner 表示
- 結果画面で create-pr ボタンを非表示、代わりに notice 表示
- サーバ側
POST /chat/create-prも 422 Unprocessable Entity を返す (defense-in-depth)
新規 ADR 起案として PR 化したい場合: 同じ draft を retroactive=false で再アップロード (上書き)。
緊急時 (422 が誤発火する等): wrangler secret put RETROACTIVE_MODE_ENABLED false で即時 bypass 可。復旧後に secret を削除して vars のデフォルト ("true") に戻す。
注: chat-terminal UI は本機能未対応。retroactive 用途では通常 /chat を使うこと。
詳細: ADR-0052
5. スコアリング基準(10 項目 × 5 点 = 50 点満点)
prompts/02_scoring.md の仕様準拠。
| # | 項目 | 配点 | 何を見るか |
|---|---|---|---|
| 1 | 問題定義の明確さ | 5 | 何が解決すべき課題か、現状の痛みが具体的に書かれているか |
| 2 | 代替案の網羅性 | 5 | 採用案以外に最低 2 つの代替案と却下理由が明示されているか |
| 3 | 判断基準の明示 | 5 | 評価軸(コスト/速度/保守性等)が明示されているか |
| 4 | 過去決定との整合性 | 5 | 過去 ADR との関係(準拠 / 拡張 / 矛盾 / Supersede)が言及されているか |
| 5 | 影響範囲の特定 | 5 | 変更が及ぶファイル・モジュール・データ・ステークホルダーが列挙されているか |
| 6 | 運用上の罠の検証 | 5 | 後任がハマりそうな落とし穴・エッジケース・監視ポイントが書かれているか |
| 7 | 失敗時のロールバック性 | 5 | 撤回手順・データ復旧・互換性維持の経路が示されているか |
| 8 | コスト試算 | 5 | 初期工数・運用コスト・移行コストが粗くでも数値で書かれているか |
| 9 | 検証可能な完了条件 | 5 | 「何が起きたら成功か」が観測可能な指標で定義されているか |
| 10 | 長期的影響の言及 | 5 | 半年〜1 年後の負債化リスク、Review After 日が設定されているか |
各項目を 0〜5 点で採点:
| 点 | 状態 |
|---|---|
| 5 | 模範的。後任が読んで判断を完全に再現できる |
| 4 | 十分。軽微な不足はあるが意思決定に十分な材料がある |
| 3 | 最低限。書かれているが浅い / 検証が甘い |
| 2 | 言及はあるが具体性に欠ける / 一般論で終わっている |
| 1 | ほぼ未記載 / 内容が空疎 |
| 0 | 完全に欠落 |
5.1 Mode 別の合格閾値
| Mode | 閾値 | 平均 | 該当例 |
|---|---|---|---|
| Light | 35 / 50 | 3.5 点 | 局所的・低リスク・1 人で完結 |
| Standard (default) | 40 / 50 | 4.0 点 | 複数モジュール・中リスク |
| Critical | 45 / 50 | 4.5 点 | 不可逆・データ移行・外部依存・予算/工数大 |
Mode が Critical と判定されたのに Rollback Plan が薄いと、Gate 4 で大きく減点されます。
5.2 よくある不合格パターン
| パターン | スコア低下項目 | 改善ヒント |
|---|---|---|
| 「他社もやっているから」 | #3 判断基準 | 自社の文脈で再評価 |
| 「とりあえず始めて様子を見る」 | #7 ロールバック性 | 撤退判定の指標を数値で |
| 「他に方法がない」 | #2 代替案 | 「やらない」を含めて 3 案以上 |
| 「リスクは特にない」 | #6 運用罠 | 必ず何かある。最悪ケースを言語化 |
| 「〇〇を改善する」(曖昧) | #1 問題定義 | Before/After を具体的に |
| 「過去 ADR は知らない」 | #4 過去整合性 | Gate 2 で機械的に検出されるが、起案前に grep 推奨 |
| 「コストは大したことない」 | #8 コスト | 工数 N 人日・月額 X 円で具体化 |
| 「うまく動けば成功」 | #9 完了条件 | KPI / 監視メトリクスで定義 |
6. Mode の判定基準 (Gate 0)
| Mode | 該当例 | 求められる充足度 |
|---|---|---|
| Light | 局所的・低リスク・1 人で完結 | コンテキスト・決定・影響のみで可。代替案・撤退条件は省略可 |
| Standard | 複数モジュール・中リスク | 全セクション必須 |
| Critical | 不可逆・データ移行・外部依存・予算/工数大 | 全セクション + 撤退条件を厳格に |
Triage プロンプト詳細: prompts/01_triage.md / prompts/production/gate0-triage/prompt.md
6.1 Temperature 実装制約 (ADR-0056)
各 Gate の LLM 呼出に temperature が設定されています。起案者が意識する必要はありませんが、スコアのばらつきに関する問い合わせ時の参考情報です。
| Gate | モデル | Temperature | 備考 |
|---|---|---|---|
| Gate 0 (triage) | gemini-flash | 0.2 | 判定の安定性重視。seed=42 |
| Gate 1 DA (devil's advocate) | claude-sonnet | 0.95 | 多様な反論生成のため高 T (ADR-0071) |
| Gate 1 PM (pre-mortem) | claude-sonnet | 0.80 | 失敗シナリオの多様性確保 |
| Gate 1 Judge (aggregator) | claude-sonnet | 0.20 | 分類・統合の安定性重視 |
| Body generation | claude-opus | 0.6 | — |
| Gate 4 (scoring) | claude-opus | 1.0 (固定) | reasoning_effort (output_config.effort) 使用時は T=1 必須 |
| Gate 2 (consistency) | claude-opus | 0.4 | 判定の安定性重視。seed=42 |
| Gate 3 (Gemini Pro) | gemini-pro | — | ビジネス・アーキ視点。Gemini 3.1 Pro deep think |
| Gate 3 (Claude Opus) | claude-opus | — | 論理・詳細視点 |
| Gate 3 (o3) | gpt-o3 | — | 技術・体系視点。temperature ではなく reasoning_effort で制御 |
| Policy Alignment | claude-opus | 0.4 | 会社固有方針整合。seed=42 |
制約: claude-opus は LiteLLM 経由で temperature が API に送信されない (T drop)。Gate 4 は reasoning_effort (Anthropic output_config.effort) を使用するため T=1 固定 (Anthropic API 仕様)。
Self-Consistency〔セルフコンシステンシー=同じ採点を複数回して多数決〕: Gate 4 は同一プロンプトで N 回並列採点し、多数決で合否を判定する。prompt.meta.yaml の sampling_n で制御 (フォールバック default: 1、KV〔Key-Value ストア=再デプロイなしで設定値を出し入れできる保管庫〕で N=5 に設定可能)。スコアのばらつきは scoringStdDev で観測可能。コスト影響: N=5 時は Gate 4 の LLM トークン消費が約 5 倍 (月額約 $3.5 → $6、ADR-0056 §5.2 参照)。
llm_params 外出し (Phase 2): 各ノードの temperature/seed は prompts/production/<id>/prompt.meta.yaml の llm_params ブロックで管理。KV に push 済の場合は KV 優先。変更時は scripts/prompt-kv-push.mjs で KV を更新。
詳細: ADR-0056
7. 緊急時・パイプライン停止時の手動起票
Cloudflare Worker / LiteLLM Gateway / GitHub Actions のいずれかが停止している場合、代表取締役の判断で 手動起票 が可能です。
7.1 手動起票の手順
- ローカルで
docs/adr/templates/template.mdをコピーし、docs/adr/NNNN-slug.mdとして保存 (NNNN は次の連番、4 桁固定) - ブランチ
manual/adr-NNNN-slugを切り、コミット - Push して PR を作成 (タイトル:
[ADR-NNNN][manual] 要旨 (Mode)) - PR 本文の冒頭に「手動起票理由 (パイプライン停止 / 緊急判断 等)」を明記
- ラベル
adrmode:*status:proposedmanual-bypassを手動付与
7.2 権限分離
- 手動起票は 代表取締役 / 開発実装担当 のみ実施 (権限分離)
- 手動起票件数は週次振り返りで確認し、パイプラインの不安定要因を特定する材料にします
7.3 Async mode(非同期実行 / ADR-0066)
400 行超の長尺 draft で Cloudflare 524 timeout (100 秒) が発生する場合、Web UI の 「Async mode〔アシンクモード=非同期実行=裏で処理して結果を後から取りに行く方式〕」チェックボックス を ON にしてください。
動作の仕組み:
POST /chat/start?async=true→ triage のみ同期実行 (ADR-0071 で盲点検出 DAG〔有向非巡回グラフ=枝分かれして合流する処理の流れ〕が 30s 超のため preGraph から除外)- needsAdr=true 時に Cloudflare Queues へ enqueue →
{ sessionId, status: 'queued' }即時返却 - Consumer Worker がバックグラウンドで
buildGraph().invoke()を実行し PipelineSessionDO に結果保存 - Web UI が
GET /chat/status/:sessionIdで polling (1s → 10s exponential backoff、10 分 timeout)
いつ使うか:
- 通常の起案 (Standard/Light mode): OFF のまま (sync で十分)
- Critical mode や長尺 ADR で 524 timeout が発生した場合: ON にする
エラー時の確認方法:
- Web UI に error 表示が出た場合、
GET /chat/status/:sessionIdで error 内容を確認 - DLQ〔Dead Letter Queue=処理に失敗したメッセージの退避先〕 (
pipeline-queue-dlq) に失敗メッセージが退避される (max_retries=3)
CI からの実行:
- GitHub Actions の
Decision Pipeline Triggerworkflow からworkflow_dispatchで実行可能 (ADR-0064 先行実装)
7.4 Gate 4 閾値変更手順 (ADR-0084)
Gate 4 スコアリングの合格閾値を再デプロイなしで変更可能。緊急時のガード緩和や Mode 別の運用試験に使用。
KV キー: bizlp:prompts:gate4-scoring:thresholds
デフォルト (KV 未設定時): {"Light":35,"Standard":40,"Critical":45}
# 閾値を一時的に Standard=38 に下げる
echo '{"Light":35,"Standard":38,"Critical":45}' | \
npx wrangler kv key put --binding=PROMPTS_KV \
bizlp:prompts:gate4-scoring:thresholds --pipe
# デフォルトに戻す (KV キー削除でフォールバック発動)
npx wrangler kv key delete --binding=PROMPTS_KV \
bizlp:prompts:gate4-scoring:thresholds
注意: 閾値を下げる場合は telemetry〔テレメトリ=各審査段の実行記録を集めた監視データ〕経由で品質劣化を継続監視すること。緩和の理由・期限を docs/_internal/06_ops/changelog.md に記録。
7.5 プロンプト更新手順 (ADR-0042 / ADR-0085)
全 8 ノードのプロンプトは KV 経由で更新可能。scripts/prompt-kv-push.mjs でアップロード後、active pointer を切替える。
対象 KV ID:
| ノード | KV ID |
|---|---|
| Gate 0 Triage | gate0-triage |
| Gate 1 DA | gate1-da |
| Gate 1 PM | gate1-pm |
| Gate 1 Judge | gate1-judge |
| Gate 2 Consistency | gate2-consistency |
| Gate 4 Scoring | gate4-scoring |
| Policy Alignment | policy-alignment |
| Cross Validation | cross-validation |
手順:
# 1. プロンプトを編集 (prompts/production/<node-id>/prompt.txt)
# 2. KV にアップロード (新バージョンが採番される)
node scripts/prompt-kv-push.mjs --node gate4-scoring --file prompts/production/gate4-scoring/prompt.txt
# 3. active pointer を新バージョンに切替
node scripts/prompt-kv-push.mjs --node gate4-scoring --activate <version>
# 4. ロールバック (active pointer 削除で FALLBACK_PROMPT に戻る)
npx wrangler kv key delete --binding=PROMPTS_KV bizlp:prompts:gate4-scoring:active
parallel_review は対象外 — 3 ベンダーごとに評価観点を切替える動的テンプレートのため KV 化されていない (今後の課題)。
7.6 Gate 2 ADR キャッシュ無効化手順 (ADR-0083)
Gate 2 整合性チェックは ADR 一覧を _cache:adr-summaries (TTL=1h) にキャッシュする。新規 ADR マージ直後など最新化が必要な場合は手動で無効化する。
# 認証情報を環境変数に読み込み
source scripts/keychain_env.sh
# キャッシュ削除
curl -X DELETE \
-u "$DECISION_PIPELINE_AUTH_USER:$DECISION_PIPELINE_AUTH_PASSWORD" \
https://drp.bizlp.dev/drafts/_cache:adr-summaries
次回 Gate 2 実行時に GitHub から再取得される。通常は TTL 失効で自動的に最新化されるため、緊急時のみ使用。
7.7 Telemetry スキーマ v2 (ADR-0082)
telemetry_records テーブルに以下の 5 カラムを追加:
| カラム | 型 | 用途 |
|---|---|---|
trigger_source | TEXT | web-ui / github-actions / claude-code 等の起点識別 |
mode_override | TEXT | Triage Mode 強制指定 (Light / Standard / Critical) |
dry_run | INTEGER (0/1) | PR 作成スキップフラグ |
draft_id | TEXT | KV draft ID (audit 用) |
node_metrics | TEXT (JSON) | 各ノードの elapsed_ms / tokens / cost のオブジェクト |
schema_version カラムを 'v1' | 'v2' に拡張。v1 レコードは新カラム NULL の後方互換。
マイグレーション:
npx wrangler d1 execute decision-pipeline-telemetry \
--file=drp/migrate-v2.sql
v3 (2026-05-29 / ADR-0086・0087): per-gate 所要時間 10 カラム (
triage_ms〜numbering_ms) +cross_validation_verdicts(JSON 配列) を追加しschema_versionを'v3'に拡張。カラム一覧・クエリ例・マイグレーション履歴は decision_pipeline/README.md の Telemetry スキーマ v3 を参照。本番適用済 (既存 31 件は per-gate ms をバックフィル、verdicts は過去レコード NULL)。
7.8 body-generation プロンプト slim 化 / ロールバック (v1.2.0)
body-generation プロンプトは KV (bizlp:prompts:body-generation:active) 経由で管理。2026-05-29 に v1.1.0 → v1.2.0 へ slim 化 (PR #1125)。
- 削減対象: Implementation Status / Kruchten Type の説明を
docs/adr/README.md参照に圧縮、Mode 別構造を表化、Rule 4 (Confirmation) を簡潔化。139 → 113 行、推定 tokens 3,599 → ~2,500 (-32%)。 - 絶対残した部分: Rule 7-10 (数値・表の原文転記禁則)、§5.2 負の影響「必ず 1 行」。
- 期待効果: 月次 cost $4.3-6.5 → $3.3-5.1 (期待値、本番計測待ち)。
ロールバック (前バージョンへ active を戻す):
npx wrangler kv key put "bizlp:prompts:body-generation:active" "1.1.0" \
--binding=PROMPTS_KV --preview false --remote
計測指標 (slim 効果検証): 切替 1〜2 週間後に node_metrics.body_generation の input_tokens / output_tokens / cost_usd を集計。
SELECT AVG(json_extract(node_metrics, '$.body_generation.input_tokens')) AS in_tok,
AVG(json_extract(node_metrics, '$.body_generation.cost_usd')) AS cost
FROM telemetry_records
WHERE schema_version IN ('v2','v3') AND node_metrics IS NOT NULL;
品質劣化なしを確認後、他 3 ノード (gate2-consistency / gate3-parallel-review / gate4-scoring) の slim 化要否を判断 (RQ §5.6.5 ステップ 6)。
7.9 CI auto-deploy 修復パターン (pnpm setup + lint)
PR #1116〜#1118 で auto-deploy が連続失敗した根因は 2 段階だった (PR #1114・#1119 で修正)。
- pnpm セットアップ順序:
.github/workflows/{deploy-worker.yml, ui-test.yml}でpnpm/action-setup@v4をactions/setup-node@v4(cache: pnpm) の前に置く。重複していたcorepack enableは削除。 - lint エラー:
persistence.tsのno-useless-assignmentを修正。
標準パターン:
- uses: pnpm/action-setup@v4 # ← setup-node より前
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
7.10 session stuck の自動回復 (EC-3 / per-session DO alarm watchdog)
ADR-0103 の MVP 卒業条件 EC-3 (Queue silent failure 対策) として、per-session の Durable Object alarm watchdog が実装された (PR #1354/#1355)。session が無進捗で stuck した場合に自動で status=error 化し、永久 polling を防ぐ。
- 発火条件:
queuedのまま 30 分、またはrunningで 20 分 idle (進捗書込のたびにタイマーをリセット)。- queued 閾値は当初 5 分だったが、consumer が実効直列 (max_batch_size=1) のため先行 run (~8-25 分) 占有中の正常な順番待ちを取りこぼしと誤検知した (DRP-374, session
906aafc2)。worst-case 1 run 占有をカバーする 30 分へ延長。
- queued 閾値は当初 5 分だったが、consumer が実効直列 (max_batch_size=1) のため先行 run (~8-25 分) 占有中の正常な順番待ちを取りこぼしと誤検知した (DRP-374, session
status=error時のerror.gate:queue_pickup— メッセージ取りこぼし (consumer が pickup しなかった)。回復ガードあり (DRP-374): この error の後に message が配達された場合 (= 取りこぼしでなく 30 分超の queue 待ちだった場合)、consumer は ack-skip せず実行を自動再開する。完走すれば telemetry の watchdog-timeout 行は最終結果で上書きされる (INSERT OR REPLACE)。回復なしで watchdog-timeout が残存している run のみが真の取りこぼし。consumer_timeout— consumer が無進捗で停止 (途中クラッシュ等)。こちらは gate 部分実行済みのため回復ガード対象外 (多重課金・PR 重複リスク)。
- telemetry 検索: stuck 由来の error は
rejection_reason_code='watchdog-timeout'で検索可能。 - 検証ツール (env-gated):
POST /debug/watchdog-probe?arm_ms=N&status=queued|runningで watchdog を任意発火できる。WATCHDOG_PROBE_ENABLED=trueの時のみ有効 (既定 OFF = 404)。本番では既定 OFF のままにする。
入口統一 (EC-2) と EC-3 は別スコープ。EC-2 は triage 派生フィールドを
src/triage/shared_triage.tsに集約 (drift 解消)、EC-3 は既存 async consumer の堅牢化。詳細は ADR-0103。
7.11 dormant Workflow の実機検証経路 (ADR-0120 Phase a)
ADR-0120 Phase a で本番デプロイされた PipelineRunWorkflow (Cloudflare Workflows・durable execution 本体) は dormant (入口未接続) であり、既存の queue consumer 経路には影響しない。実機検証は専用デバッグエンドポイントで行う (PR #1470)。
- エンドポイント:
POST /debug/workflow-trigger(Basic auth 必須) - dormant 維持の仕組み: 本番は
WORKFLOW_TRIGGER_ENABLED未設定 = 404。検証時のみ local wrangler dev の.dev.varsにWORKFLOW_TRIGGER_ENABLED=trueを設定する (本番環境変数には設定しない) - リクエスト body:
{draft_id}(KV draft 参照) または{author, title, context}(インライン)。dry_runは既定 true (PR 自動作成を抑止)・mode_override指定可 - 応答:
{run_id, workflow_instance_id, status, poll_url}。進捗はGET /chat/status/:run_id、終端後はGET /audit/runs/:run_idで telemetry と突合する - 実 LLM 検証: Cloud Run gateway + Keychain
bizlp-gas-LITELLM_MASTER_KEYを.dev.varsに一時上書きする。drp-ops Skill「Cross-Validation golden eval」の罠 2 つと同じ注意 —LITELLM_GATEWAY_URL=localhost:4000のままだと全件fetch failed/.dev.vars既存のLITELLM_VIRTUAL_KEYは Cloud Run では400 No connected db - 検証実績 (2026-06-05): ① mock (early-reject) ② 実 LLM Light mode 全 10 gate 完走 4.7 分 ③ schemaVersion 不一致 → 10.6 秒で failed 終端 — の 3 経路を実機確認済み
入口切替 (queue consumer → Workflow) は Phase b で実装済み (§7.12)。詳細は ADR-0120。
7.12 入口切替 flag の運用 (ADR-0120 Phase b)
ADR-0120 Phase b (PR #1476) で、審査の入口 (/chat/start?async=true・/runs) を Queue enqueue ↔ Workflows instance create で切り替える feature flag が実装された。本番は flag 既定 OFF = 入口は Queue のまま挙動不変。
- flag 名:
WORKFLOW_ENTRYPOINT_ENABLED(既定 = 未設定 = OFF) - ON / OFF (rollback) 手順:
wrangler secret put WORKFLOW_ENTRYPOINT_ENABLEDでtrue/falseを投入 — secret は vars を上書きするためデプロイ不要・即時反映 (rollback も同手順で即時) - ON 時の挙動変化:
- 入口が
PIPELINE_RUN_WORKFLOW.create()(instance id = sessionId) になり、session にengine: 'workflows'が記録される (OFF 時はengine: 'queue') - instance create 失敗は fail-loud 503 + ユーザー可視エラー (無音失敗を作らない・ADR-0120 決定 5)
/chat/cancelが即時化: ① instance terminate 併用 ② DO/session/cancel-finalize(complete/error と race しない条件付き終端・cancel telemetry は applied=true 時のみ) ③ step 内 1 秒 cancelRequested polling + AbortSignal が in-flight LLM HTTP まで伝播し課金を即停止。Queue engine のキャンセル挙動は不変- gateProgress patch に gateId+seq (init=0 / running=ordinal×2+1 / done=ordinal×2+2) が付き、DO が適用済み seq 以下を破棄 — step retry/replay による進捗の重複・巻き戻りを排除 (seq なし patch = Queue consumer は無条件適用で不変)
- 入口が
- 本番 ON の前提条件: Phase c ステージング検証 (並列 3 run・LLM 429・DO 競合・キャンセル後課金計測) の通過が必須ゲート (ADR-0120 撤退条件)。CI pass のみでの本番 ON は不可 — 2026-06-05 に PASS 判定済み (検証記録)。切替手順は §7.13
- §7.11 の
/debug/workflow-triggerは引き続き本番 404 (dormant 検証経路として維持・本 flag とは独立)
7.13 Workflows 運用 — 週次アサート・リアルタイムアラート・本番切替 (ADR-0120 Phase c)
Phase c (PR #1481 / #1484 / #1487 + ステージング検証 PASS 2026-06-05) で本番切替の前提が整った。運用面は次の 3 点。
週次 API アサート (decision-pipeline-workflows-api-assert)
- 何か: Workflows instance status API の取得フィールド (型・存在) を毎週月曜 06:30 JST に CI でアサートし、Cloudflare 側の API 仕様変更による無音破壊を検知する (ADR-0120 決定 4・盲点 5)
- 失敗時対応: アダプタ層
drp/src/workflows/instance_status.tsとscripts/assert_workflows_status_api.mjsの期待形を実 API 応答に合わせて更新する (依存箇所はアダプタ層に集約済みのため修正は 2 ファイルで完結) - 既知の罠: describe 系 API は大きな step output で エラー 10001 を返す — 依存は list/status() のみに限定済み。workers-types と REST docs の status enum は不一致が既にある (rollingBack/unknown) — アダプタ層は和集合で吸収する方針
リアルタイムアラート有効化 (running instance >20・1h cron・Google Chat ops-alert スペース)
secret 2 件を投入するまで監視は無効 (デプロイ自体は安全):
- Cloudflare ダッシュボードで Workflows read 専用 API token を発行 (deploy 用 token を流用しない — 最小権限) →
wrangler secret put WORKFLOWS_READ_API_TOKEN - ops-alert 用 Google Chat スペースの incoming webhook →
wrangler secret put OPS_ALERT_WEBHOOK({"text"}POST 互換のため Slack webhook URL でも動く・PR #1489 corrigendum で Slack から汎用化)
- 未設定の間は worker ログに
running_alert_skipped_no_token(token 未設定) /running_alert_no_webhook(webhook 未設定) が 1 時間おきに出る = 「監視無効」が観測可能 - 閾値は既定 20・env
RUNNING_ALERT_THRESHOLDで上書き可 - 計数機構は Workflows REST API count (ADR-0120 §Corrigendum — Analytics Engine 案から変更・2026-06-05 代表取締役承認)
本番切替手順 + 切替後 4 週監視
状態 (2026-06-05): 本番切替実施済み — 2026-06-05 21:45 JST に
WORKFLOW_ENTRYPOINT_ENABLED=true投入。切替直後の/runs実機で engine=workflows + telemetry + instance Completed を確認。移行 4 週の撤退条件監視中 (〜2026-07-03 目安)。リアルタイムアラートも有効化済み (Google Chat 着信確認・heartbeat 稼働)。以下は切替・rollback の手順記録。
- 切替前確認: 進行中 run が 0 件であること (
GET /audit/runs直近 +/chat/status) wrangler secret put WORKFLOW_ENTRYPOINT_ENABLEDでtrueを投入 (§7.12・デプロイ不要・即時)- rollback は同コマンドで
false(即時。Queue 経路は温存済み) - 切替後 移行 4 週の撤退条件監視 — 週次 telemetry レビューに以下 3 指標を追加 (ADR-0120 撤退条件):
- ① telemetry 喪失 1 件 で即停止 (flag OFF)
- ② LLM 二重課金 1 件 で即停止
- ③ 新規障害 3 件 で見直し
7.14 フィーチャーフラグ・ロールバック・Queue 滞留対処
フィーチャーフラグ一覧
いずれも既定有効、"false"(または数値 0)でロールバック可(wrangler.toml の [vars] or wrangler secret)。
| 変数 | 既定 | 効果 | 導入 |
|---|---|---|---|
SOCRATIC_DETERMINISTIC | ON | socratic の 3 観点選択を原稿シードの決定的 PRNG に。"false" で従来の Math.random | Part3 (PR #1303) |
CROSSVAL_LOOPBREAKER | ON | Cross-Validation 却下の goalpost / round-cap 検知 → escalate (PR 起票)。"false" で常に自動 reject | Part2/4 (PR #1311 / ADR-0109) |
CROSSVAL_ROUND_CAP | 3 | bounded rounds 上限。trailing 連続却下がこの回数に達したら盲点が移動していなくても escalate。0 で round-cap 無効 (goalpost 検知のみ) | Part4 (ADR-0109) |
パイプライン全体のロールバック
1 週間以上 ADR 起案できない事態が発生した場合: wrangler rollback で前回デプロイに切り戻し、原因を調査する。async mode (ADR-0066) に起因する場合は ?async=true を無効化し sync モードで運用を継続。詳細手順: langgraph_migration/main_workspace_checklist.md の Rollback セクション参照。
Queue 滞留時の対処
pipeline-queue にリトライメッセージが溜まると新規メッセージの処理が遅延し polling timeout (10 分) に至る。Cloudflare Dashboard → Queues → pipeline-queue → Messages → Purge で滞留メッセージを全削除後に再実行。
session が自動 stuck する場合は §7.10 (DO alarm watchdog) を参照。
7.15 受付プリゲートの人手確認ルーブリックと再 ON フロー (ADR-0142 本番稼働 2026-06-15)
ADR-0142 (② 受付プリゲート) の導入直後 20 run は、run ごとに差し戻し判定を人手確認する。本節がその判定ルーブリックと自動 OFF 後の再 ON フローの正で、ADR-0142 の Confirmation がここを参照する。(Cross-Validation 第 1 段〔ADR-0143〕も当初は本節を共用するリリース前提だったが、ADR-0154 で撤回・実装中止となったため、本節は受付プリゲート専用に整理した。)
人手確認ルーブリック (受付プリゲート)
- 判定者 (担当者): 検査の所有者 = DRP 運用者。現任 = 代表取締役。
- SLA: 差し戻し発生から 24 時間以内に「正当 / 誤検知」を判定して D-1 記録に残す。
- エスカレーション先: 代表取締役 (担当者を将来委譲した場合の上位判断者)。SLA 超過分は判定保留として月次レビューに乗せる。人手確認キューの滞留は ADR-0142 の運用 K.O. (導入後 20 run で precision 70% 未満なら graph 分岐で自動 OFF) が下限を守る。
- 判定基準 (「正当な差し戻し」の条件): 次の 2 つを両方満たすこと。
- 引用の実在: 判定が引用した逐語引用が起案本文に実在する (機械照合の結果を確認する)。
- 指摘の妥当性: 引用箇所が判定理由を実際に支持している。
- プリゲート (0142) の例: 「root の問いが 2 つ」と判定された 2 つが、1 文の決定に圧縮できず独立して撤退できる別決定か。日本語の並列節 (「〜であり、かつ〜」「〜と〜を解決する」) を独立 root と取り違えていたら誤検知。「行き先のない前提」と判定された前提が本当にスコープ的与件か。時間的与件なら誤検知。
- 異議申し立て手順: 起案者が判定に納得できない場合、D-1 記録の判定理由+逐語引用を確認のうえ担当者へ申し立てる (Slack / メール)。担当者は上記基準で再判定し、結果を D-1 記録に追記する。最終判断は代表取締役。
- 集計: 判定結果は月次で precision に集計する。KPI = プリゲート (0142) は precision 70% 以上。
自動 OFF 後の再 ON フロー (ADR-0142 撤退条件の graph OFF 後の手順)
safety circuit や precision 閾値未達で graph OFF になった後に再 ON する手順:
- 集計完了の確認: 滞留していた人手確認キューを解消し、telemetry (D1) の判定記録と人手確認結果の突合が対象 run 分そろっていることを月次集計で確認する。
- 閾値の確認: precision が KPI (0142 = 70%) 以上であることを確認する。未達なら再 ON せず撤退条件の評価へ進む。
- 承認: 再 ON の承認権限者 = 検査の所有者 (DRP 運用者。現任 = 代表取締役)。承認の記録は graph 分岐 flag の設定変更 PR のレビューで残す。
- 最大猶予期間: 自動 OFF から 30 日以内に再 ON か OFF 継続 (撤退評価へ) を判断する。30 日を超えて判断材料がそろわない場合は OFF のまま撤退条件の月次判定に乗せる (ADR-0142 の判定周期 = 月次と整合)。
撤退発動時の D-1 参照停止フラグ (ADR-0142 撤退手順 2)
precision 閾値未達でプリゲートを OFF にした場合、D-1 に書き込まれたプリゲート由来の差し戻し記録へ「プリゲート由来・precision 閾値未達のため参照停止」フラグを付与する。誤判定由来の記録が正典の人手検査基準として残り続けるのを防ぐためで、OFF 操作と同時に実施する。
8. FAQ
Q1. 同じトピックで何度も差戻されます
AI と壁打ちしてドラフトを磨く時間を取ってください。それでも閾値に届かない場合、その判断は本当に必要か / 別の解き方はないか を再考してください。
Q2. 急ぎで決めたい
ADR 化すべきでないサインかもしれません。本当に急ぎなら手動起票 (代表取締役判断) も可能ですが、後から「なぜそう決めたか」を問われた時に答えられる根拠は事前に整理してください。
Q3. 過去の ADR と矛盾する決定をしたい
Gate 2 (Consistency) が CONFLICT を検出します。Supersede ADR-XXXX を新 ADR の References セクションに明記すれば通過可能。後継宣言なしで矛盾 ADR を起案すると差戻しされます。
Q4. AI のスコアに納得できない
AI は審査員ですが完璧ではありません。スコアに納得できない場合、PR 本文の「最終判断理由」セクションに反論を記述してください。最終的には代表取締役が判断します。
Q5. PR が立ったあと修正したい
PR が Status: Proposed の間は、起案者がコミットを追加して修正可能 (GitHub アカウントが必要)。アカウントがない場合は代表取締役に修正を依頼してください。
Q6. Parallel Review の指摘は無視できる?
Gate 3 (Parallel Review) は 情報提供型 (差戻しなし)。3 モデルの指摘はあくまで参考。ただし代表取締役レビュー時に「Parallel Review でこの指摘があったが、どう対応したか」を問われる可能性があります。重要な指摘は PR 本文の「最終判断理由」セクションで触れることを推奨。
Q7. Retroactive Validation との違いは?
- 通常起案: 新規 ADR を立てて PR 化する。本ガイド §4 のフロー。
- Retroactive Validation: 既に main に取り込まれた ADR を事後審査する (PR は作らない)。本ガイド §4.6 + ADR-0052。
「Critical 案件は Pipeline 経由」と規定したのに過去に Pipeline 未経由で main マージされた ADR を事後審査する用途。
9. 関連ドキュメント
- 検査の所有(5 層モデル) — どの検査がどの層で走り、どの層が差し戻しの権限を持つかの全体像
- Decision Pipeline 全体像
- operator_guide.md (Dify Retired) — 旧 Dify 時代の操作手順 (履歴用)
- Triage プロンプト設計 / SSoT:
prompts/production/gate0-triage/prompt.md - Scoring プロンプト設計 / SSoT:
prompts/production/gate4-scoring/prompt.md - Socratic プロンプト設計 / SSoT:
prompts/production/gate1-socratic/prompt.md - Consistency プロンプト設計 / SSoT:
prompts/production/gate2-consistency/prompt.md - Parallel Review プロンプト設計 / SSoT:
prompts/production/gate3-parallel-review/prompt.md - Phase 3 並列レビュー設計メモ
- ADR-0019: LangGraph 採用 / Dify 退役
- ADR-0052: Retroactive Validation Mode
- ADR テンプレート
- ADR-0056: LLM temperature 戦略
- ADR-0066: async Queues + DO
- ADR-0071: Gate 1 盲点検出エンジン再定義
- ADR-0064: CI trigger
- ADR-0142: ② 受付の問題空間切り分けプリゲート — §4.3.3 / §7.15 の根拠
- ADR-0143: Cross-Validation critical×Must の 2 段化 — 第 1 段は ADR-0154 で撤回・実装中止 (§4.3.3 / §7.15 から 0143 分を除去済)
- ADR-0154: Cross-Validation 2 段化の第 1 段(早期差し戻し)を撤回する — §4.3.3 / §7.15 の 0143 分除去の根拠
変更履歴
| 日時 | 変更内容 |
|---|---|
| 2026-06-16 | ADR-0143 (CV 第 1 段) 撤回 (ADR-0154 merge・PR #2046) に伴い §4.3.3・§7.15 の 0143 分を除去。§4.3.3 は受付プリゲート専用、§7.15 は受付プリゲートの人手確認ルーブリック専用に整理。ADR-0142 の本番稼働分は継続 |
| 2026-06-16 | §4.3.3 / §7.15 の状態を「ADR-0142 本番稼働 (2026-06-15・PR #2043)」へ更新。ADR-0143 (CV 第 1 段) は実装待ち継続 (パイロット K.O.・方針検討中) |
| 2026-06-12 | §4.3.3 新設: 受付プリゲート・CV 第 1 段の pass の意味 (起案者周知・ADR-0143 Gate1 #4)。§7.15 新設: 人手確認ルーブリック (判定者・SLA 24h・判定基準・異議手順)・自動 OFF 後の再 ON フロー・D-1 参照停止フラグ手順 (ADR-0142/0143 受理に伴う sub 分実装・リリース前提の整備) |
| 2026-06-12 | §4.3.2 新設: UI run の PR 作成は「PR 作成」ボタンが正規 (自動作成は /runs のみ・ADR-0064 設計のコード実査確定)・明示指示方式への統一は main 依頼済みの暫定注記。§4.4 冒頭の「自動作成されます」を経路別記述に修正 |
| 2026-06-12 | §4.1 に draft.json 任意フィールド (business / navGroup) の表を追加 (PR #1830 CI autofix + PR #1833 worker 受理のドキュメント追従・main→sub 申し送り消化) |
| 2026-06-07 | §7.14 フィーチャーフラグ一覧・ロールバック・Queue 滞留対処を追加(README §12 から移植 / 経緯: ADR-0117) |
| 2026-06-05 | §7.13 本番切替手順に「切替実施済み (2026-06-05 21:45 JST・4 週監視中)」の状態注記を追記 (ADR-0120 本番切替完了に追従) |
| 2026-06-05 | §7.13 Workflows 運用 (週次アサート・アラート有効化・本番切替 + 4 週監視) を追加・§7.12 にステージング PASS と検証記録リンクを追記 (ADR-0120 Phase c 完了 / PR #1481・#1484・#1487 反映) |
| 2026-06-05 | §7.12 入口切替 flag の運用を追加・§7.11 の Phase b 言及を実装済みに更新 (ADR-0120 Phase b 完了 / PR #1476 反映) |
| 2026-06-05 | §7.11 dormant Workflow の実機検証経路を追加 (ADR-0120 Phase a 完了 / PR #1467・#1470 反映) |
| 2026-05-29 | §7.7 に Telemetry v3 注記 (per-gate ms / verdicts JSON、README 参照)。§7.8 body-generation v1.2.0 slim 化・ロールバック・計測指標を追加。§7.9 CI auto-deploy 修復パターン (pnpm setup 順序 + lint) を追加 (PR #1125・#1129・#1134・#1135) |
| 2026-05-28 | §7.4 Gate 4 閾値変更手順 / §7.5 プロンプト更新手順 / §7.6 Gate 2 キャッシュ無効化手順 / §7.7 Telemetry スキーマ v2 追加 (ADR-0081〜0085 + ADR-0071 Phase 1 実装完了 / PR #1086〜#1091) |
| 2026-05-27 | §4.2 Policy Alignment ノード追加・Gate 3 モデル名更新。§4.3 Policy Alignment 行追加。§4.4 PR 本文に Blind-spot Report / Policy Alignment 追加。§6.1 Temperature 表を全面改訂: モデル名 (body/consistency を claude-opus に)、T 値 (triage 0.2、body 0.6、consistency 0.4)、Gate 3 を 3 行分割 (gemini-pro/claude-opus/gpt-o3)、Policy Alignment 行追加、Self-Consistency default を 1 (KV override 可) に修正 |
| 2026-05-27 | §4.2/§4.3 Gate 1 を盲点検出エンジン (DA+PM+Judge) に更新 (ADR-0071 実装反映)。§6.1 Temperature 表を 3 ノード分割。§7.3 Async mode の preGraph 記述を triage のみに修正。§9 に ADR-0071 追加 |
| 2026-05-26 | §4.3.1 差し戻し時の再投入ルール追加 (Pipeline 出力の再投入禁止、起案者生テキスト形式を明文化) |
| 2026-05-26 | §6.1 Self-Consistency / llm_params 外出し追記 (ADR-0056 Phase 2-4 完了)。§6.1 Temperature 実装制約追加 (Phase 0+1)。§7.3 Async mode 追加 (ADR-0066)。関連ドキュメントに ADR-0056/0066/0064 追加 |
| 2026-05-22 | 初版作成 (LangGraph 版、operator_guide.md (Dify Retired) の後継)。中立表現 + 5 ゲート構成 + Retroactive Validation Mode + Web UI フロー反映 |