最終更新: 2026/06/22 20:19
commonid: operator-guidetype: how-tostatus: deprecated
pageaudience: both

起案者向け運用ガイド (Operator Guide)

⚠️ Status: Retired (Dify Phase, 2026-05-08, ADR-0019) 現運用ガイド (LangGraph 版): operator_guide_langgraph.md を参照してください。 Web UI: https://drp.bizlp.dev/ から直接起案も可能。

対象: 起案者 (社内メンバー / 業務委託パートナー / 代表取締役) で Decision Pipeline を使って ADR を起案する人 Phase: 2a 以降（Dify 版 — 退役済） 最終更新: 2026-05-08

1. はじめに

本ガイドは、bizlp-gas-accounting プロジェクトで アーキテクチャ・業務設計上の決定 を行う際の起案ルールをまとめたものです。

Decision Pipeline は AI を使って "判断品質を機械的に確認する関門" として動きます。AI 自動生成ツールではなく、人間の判断品質を審査するインフラです。

1.1 大原則

  1. AI は審査員、起案者は人間 AI は問診・採点・指摘を行いますが、決定の責任は常に起案者と代表取締役が負います
  2. 40 点未満は差戻し 品質スコアが 40 / 50 点未満の起案は PR 化されません。AI と壁打ちして起案者が自身でドラフトを磨くフロー
  3. AI に責任を委ねない PR 概要欄には「AI のレビューを踏まえた上で、最終的にこの決定で進めたい理由」を起案者自身の言葉で 1 行記述してください
  4. Status 遷移権限の分離 起案者は Status: Proposed の PR を作成。Accepted / Superseded への遷移は 代表取締役 が判断します

2. アクセス・アカウント発行

2.1 Dify アカウント

起案者には Dify のアカウントを発行します（Google SSO 経由）。

  1. 代表取締役から招待リンクが送られます
  2. 業務利用の Google アカウントでログイン（個人 Gmail は不可）
  3. 「Decision Pipeline」ワークフローにアクセスできることを確認

2.2 GitHub アカウント

GitHub への直接コミット権限は不要です。Decision Pipeline 経由で Bot が PR を作るため、起案者は GitHub アカウントを持っていなくても起案できます。

ただしレビューコメントへの返答には GitHub アカウントが推奨されます（オプション）。

3. ADR を起案すべきケース

以下に該当する判断は ADR にしてください:

✅ ADR にすべき❌ ADR 不要
データモデル変更（タブ追加・列追加・削除）既存タブの値修正
仕訳ロジック・期ずれルール変更軽微なバグ修正
外部 API・SaaS の追加・移行既存 API のパラメータ調整
業務プロセス変更（締め日・承認フロー）通常の月次運用
不可逆なデータ移行データ整備
複数モジュール横断の設計判断単一モジュール内のリファクタ
採用 / 退職 / 業務委託の方針変更個別の契約調整

迷ったら Dify の Gate 0（Triage）に投げてみてください。AI が「ADR 不要」と判断すれば差戻しされます。

4. 起案手順

4.1 ステップ 1: ドラフトを書く

Markdown 形式で以下を盛り込んだドラフトを作成します:

  • 何を解決するか: 具体的な問題・目的
  • 採用したい方針: 1 段落で
  • 検討した代替案: 最低 2 つ、それぞれの不採用理由
  • 影響: 正/負/リスク
  • 撤退条件: どうなったら戻すか

💡 ドラフト作成段階で Claude Code / ChatGPT 等を壁打ち相手にするのは推奨です。ただし最終的な判断は自分で下してください。

4.2 ステップ 2: Dify に投入

Dify の「Decision Pipeline」ワークフローを開き、ドラフトテキストを貼り付けて実行します。

Gate 0 (Triage) の判定:

  • is_adr_worthy: false → ADR 不要として終了。理由を確認
  • is_adr_worthy: true → Mode（Light / Standard / Critical）が判定され Gate 4 へ進む

Gate 4 (Scoring) の結果:

  • pass: true（Mode 別閾値以上: Light 35 / Standard 40 / Critical 45）→ 自動的に GitHub に Webhook 送信
  • pass: false（閾値未満）→ スコア内訳と指摘を確認し、ドラフトを修正して再投入

4.3 ステップ 3: PR レビュー

合格時は BizLinkPartners/bizlp-gas-accounting に [ADR-NNN] ... というタイトルの PR が自動作成されます。

PR 本文には:

  • 起案者名（あなた）
  • Triage 結果（Mode / 理由）
  • Scoring サマリ（10 項目 × 5 点）
  • ADR ファイルへのリンク
  • 起案入力原文

が含まれます。

代表取締役がレビューし、コメントが付いた場合は:

  • GitHub 上で直接返信（GitHub アカウントがある場合）
  • または Slack / メールで返信

4.4 ステップ 4: マージ

マージ前チェックリスト:

  • PR 本文に「🔧 Pipeline 補強一覧」がある場合、各項目を確認し、設計意図に沿うものをチェックボックスでチェックする。これは Gate 1(socratic)が検出した盲点に対し、本文生成が起案者の生テキスト(Title/Context/Options)には無い補強策を織り込み、Cross-Validation が正当な根拠と認めて Accept した項目(ADR-0150)。承認の所在を ④受理層に一本化するためのもので、未チェックの項目が残っていると CI adr-reinforcement-checklist が fail し merge できない。妥当でない補強があれば PR ブランチで本文を修正するか、close して起案し直す。

代表取締役が PR をマージすると Status: Accepted に自動更新されます。

PR が Close された場合は Status: Rejected に更新されます。理由を確認し、必要なら別案を起案してください。

Implementation Status の更新: 受理後に実装 PR を出すときは、本文の Implementation Status を In Progress → Done の順で起案者が手動更新します。段階的実装 (Phase 1/2 等) や PR 番号を詳しく書きたいときは、本太字欄を 6 値の短縮形 (Not Started / In Progress / Done / Partial / Reverted / N/A) に保ち、詳細を ## 実装状況詳細 (impl_detail) 節へ分離します (ADR-0162)。INDEX.md の「Impl状況詳細」列は本節を派生ビューとして表示します。使い方の正典は docs/adr/README.md の「impl_detail 節で詳細を分離する」節。

4.5 Retroactive Validation モード (ADR-0052)

既に main に取り込まれた ADR を 事後検証 (Pipeline 自己審査) する場合は retroactive モードを使う。誤って /chat/create-pr を呼んで不要な PR が生成される事故 (2026-05-18 PR #821) の構造的防止が目的。

起案フロー (chat UI):

  1. https://drp.bizlp.dev/chat の「☁️ サーバー draft」セクションで「⬆️ アップロード」
  2. ローカル JSON 選択 → ID 入力後、確認 dialog で:
    • OK = retroactive validation 用 (PR 作成は無効化)
    • キャンセル = 通常の新規 ADR 起案 (PR 作成可)
  3. 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 (/chat-terminal) は本機能未対応 (ADR-0052 範囲外)。retroactive 用途では通常 /chat を使うこと。

詳細は ADR-0052 (docs/adr/0052-decision-pipeline-ui-retroactive-validation-mode-create-pr.md) 参照。

5. スコアリング基準（10 項目 × 5 点 = 50 点満点）

#項目配点何を見るか
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 日が設定されているか

Mode 別の合格閾値:

Mode閾値備考
Light35 / 50平均 3.5 点
Standard40 / 50デフォルト。平均 4 点
Critical45 / 50平均 4.5 点。不可逆な決定はここ

各項目は 0〜5 点で採点されます（5=模範的、4=十分、3=最低限、2=具体性に欠ける、1=ほぼ未記載、0=完全に欠落）。

5.1 よくある不合格パターン

パターンスコア低下項目改善ヒント
「他社もやっているから」#3 判断基準自社の文脈で再評価
「とりあえず始めて様子を見る」#7 ロールバック性撤退判定の指標を数値で
「他に方法がない」#2 代替案「やらない」を含めて 3 案以上
「リスクは特にない」#6 運用罠必ず何かある。最悪ケースを言語化
「〇〇を改善する」（曖昧）#1 問題定義Before/After を具体的に
「過去 ADR は知らない」#4 過去整合性既存 ADR 一覧をざっと確認
「コストは大したことない」#8 コスト工数 N 人日・月額 X 円で具体化
「うまく動けば成功」#9 完了条件KPI / 監視メトリクスで定義

6. Mode の判定基準

Gate 0 で AI が以下のように判定します:

Mode該当例求められる充足度
Light局所的・低リスク・1 人で完結コンテキスト・決定・影響のみで可。代替案・撤退条件は省略可
Standard複数モジュール・中リスク全セクション必須
Critical不可逆・データ移行・外部依存・予算/工数大全セクション + 撤退条件を厳格に

Mode が Critical と判定されたのに Rollback Plan が薄いと、Gate 4 で大きく減点されます。

7. 緊急時・パイプライン停止時の手動起票

Dify / Cloudflare Worker / GitHub Actions のいずれかが停止している場合、代表取締役の判断で 手動起票 が可能です。

7.1 手動起票の手順

  1. ローカルで docs/adr/_template.md をコピーし、docs/adr/NNN_slug.md として保存（NNN は次の連番）
  2. ブランチ manual/adr-NNN-slug を切り、コミット
  3. Push して PR を作成（タイトル: [ADR-NNN][manual] 要旨 (Mode)）
  4. PR 本文の冒頭に「手動起票理由（パイプライン停止 / 緊急判断 等）」を明記
  5. ラベル adr mode:* status:proposed manual-bypass を手動付与

7.2 Bypass の制約

  • 手動起票は 代表取締役 / 開発実装担当 のみ実施 (権限分離)
  • 手動起票は週次の振り返りで件数を確認し、パイプラインの不安定要因を特定する材料にします

8. FAQ

Q1. 同じトピックで何度も差戻されます

A. AI と壁打ちしてドラフトを磨く時間を取ってください。それでも 40 点に届かない場合、その判断は本当に必要か / 別の解き方はないか を再考してください。

Q2. 急ぎで決めたい

A. それは ADR 化すべきでないサインかもしれません。本当に急ぎなら手動起票（代表取締役判断）も可能ですが、後から「なぜそう決めたか」を問われた時に答えられる根拠は事前に整理してください。

Q3. 過去の ADR と矛盾する決定をしたい

A. Phase 2a では自動チェックがありません。Superseded by ADR-XXX を新 ADR の References セクションに明記し、PR 本文でも触れてください。Phase 2c で Gate 2（過去整合性チェック）が追加される予定です。

Q4. AI のスコアに納得できない

A. AI は審査員ですが完璧ではありません。スコアに納得できない場合、PR 本文の「最終判断理由」セクションに反論を書いてください。最終的には代表取締役が判断します。

Q5. PR が立ったあと修正したい

A. PR が Status: Proposed の間は、起案者がコミットを追加して修正可能です（GitHub アカウントが必要）。アカウントがない場合は代表取締役に修正を依頼してください。

9. 関連ドキュメント

変更履歴

日時変更内容
2026-05-07初版作成（Phase 2a 着手・実装前のドキュメント整備）