← ADR 一覧へ残タスク一覧へ 最終更新: 2026/07/03 06:09
commonid: adr-0189type: adrstatus: accepted
pagemode: Standardkruchten: Executivescope: platformimplementation_status: Not Startedproposed_at: 2026-07-02 22:34approved_at: 2026-07-03approver_role: platformapprover_who: [email protected]driver: [email protected]consulted: Decision Pipeline AI 審査 (Gate 0-4)business: drp

ADR-0189: 規約から外れた決定記録草案の作成を防ぐ

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Executive
  • Scope: platform
  • Implementation Status: Not Started
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-07-02 22:34
  • 承認日時 (JST): 2026-07-03
  • Approver Role: platform
  • Approver Who: [email protected]
  • Driver: [email protected]
  • Consulted: Decision Pipeline AI 審査 (Gate 0-4)

1. Executive Summary

  • 文脈: 生成 AI が作成する決定記録の草案がルール通りに出力されないことが頻発している
  • 課題: 生成 AI が規約を読み落としたまま草案を作成し、事後に人間や CI が気付いた時点で作り直しが発生する
  • 対策: 書く前の読み落とし対策と書いた直後の違反検出を、2 段の工程として追加する
  • 効果: 機械強制できる規約違反を 0%、AI 依存の残る規約違反を 5% 未満に抑える
  • 代償: チェックリストと本体資料がずれないよう監視する手間が増える

2. 何を解決するか

信頼性:

  • .claude/rules/adr-draft.md (110 行) は path-scoped auto-load (ADR-0129) で自動的に読み込まれるが、参照先の template.md (138 行) と style-guide.md (数百行) は AI の判断で Read するかどうかが分かれる
  • AI が context 節約のため規約ファイルの先頭数十行だけを読むと、本質規約が本文中盤や参照リンク先に隠れて読み落とされる
  • 出力ズレの構造的原因は AI の記憶量ではなく「規約の配置」にある
  • 書き手側 AI のインデント欠落によって、早わかり節の子項目が親と同じ階層に表示される崩れが発生する
  • 早わかり節が崩れると Layer 1 (経営者早わかり層) の可読性が損なわれ、決定記録の目的 (12 ヶ月後の読者に判断根拠を伝える) が果たせなくなる
  • 現象そのものは 1 クローン運用でも原理的に起きる。クローン数は対策の配布側にのみ効く

効率性:

  • adr-draft-lint は CI (.github/workflows/adr-draft-lint.yml) で PR 単位に走るため、草案執筆から検出まで PR 作成後 30-60 分の時間差が生じる
  • 差戻し 1 回では起案者が草案を修正して KV に再投入し、審査パイプラインを再度回す必要があり、実測 30-60 分の作り直しコストがかかる
  • 書いた直後 (Write/Edit 直後) の検出に前倒せば、この作り直しコストを数秒に短縮できる

運用性:

  • ADR-0159 (5 クローン並行運用) で並行運用が確立されており、規約遵守は各クローンの AI の判断に依存している
  • クローン数は現象の発生確率を上げるのではなく、(a) クローンごとの出力品質のばらつきを観測可能にする、(b) 対策の配布経路を必要にする、の 2 点で効く
  • 規約ファイル・フック・lint スクリプトはいずれも git 管理で全クローンに配布できるため、一元管理すればクローンごとのばらつきを防げる

3. 採用したい方針

3.1 対策方針

規約ファイル冒頭 30-50 行に「起案者統一チェックリスト」10 個を集約 (書く前の読み落とし対策) + PostToolUse hook で adr-draft-lint を Write/Edit 直後に自動実行 (書いた直後の違反検出) の 2 段の工程を bizlp 標準として明文化する。

3.1.1 書く前の読み落とし対策 (集約チェックリスト)

  • 信頼性: 規約ファイル冒頭のチェックリストは AI の「先頭優先で読む」性質にフィットし、途中までしか読まなくても本質規約が確実に上位に来る
  • 保守性: /adr-draft-write skill 案は user 側の呼出周知が bottleneck になり見送り。チェックリストに「必ず template.md + style-guide.md を Read してから草案を書く」の指示を含めて代替する

3.1.2 書いた直後の違反検出 (PostToolUse hook)

  • 効率性: PostToolUse hook はどのクローンでも同一挙動で、開発体験を損なわず書いた直後に機械的に強制できる

3.2 守るべき設計制約

  • 保守性: 集約チェックリストと本体 template.md / style-guide.md の byte 一致ゲートを CI 新設し、どちらか更新時に相方を同期させる規約を担保する
  • 信頼性: フック発火時の lint 失敗は feedback として AI に返し、lint 通過するまで進めない (途中で素通りさせない)
  • 運用性: フックは .claude/settings.json に git commit される形で全クローンに配布する

3.3 仕様

  • 信頼性: 統一チェックリスト 10 項目は規約ファイルの H2「## 起案者統一チェックリスト (読み落とし耐性)」直下に項目で列挙し、各項目は 1 文で書いて詳細は本体 template.md / style-guide.md にリンクする
  • 効率性: PostToolUse hook の発火条件は tasks/prompts/draft_adr_*.md と docs/adr/[0-9][0-9][0-9][0-9]-*.md の 2 種とし、node scripts/adr-draft-lint.mjs $CLAUDE_FILE_PATH を実行する。hook スクリプト冒頭で「対象ファイルに ## 11. 実装配線 の文字列が含まれる」ことを前提チェックとして加え、中間状態 (11 節未満) では lint を skip して誤検知フィードバックを防ぐ
  • 効率性: hook スクリプト内で lint 実行前に対象ファイルの最終更新タイムスタンプとファイルサイズが 0 より大きいことを確認する guard 節を追加し、Edit tool の PostToolUse 後のファイル確定タイミング競合による空ファイル誤検知 (全ルール通過の偽陰性) を防ぐ
  • 保守性: チェックリストと本体 SSoT 3 file の byte 一致ゲートは scripts/check-adr-draft-checklist-sync.mjs で相互参照キーワードの存在を検証する (完全 byte 一致ではなく key phrase 検証でずれを捕まえる)。phrase リストはスクリプト外の設定ファイル scripts/adr-checklist-phrases.json として分離し、template.md 改訂時に phrase リストの更新を強制する運用にする

4. 判断基準

ADR-0050 で確立した arc42 Q42 9 タグ + WSM (加重和) + K.O. criterion を適用する (ADR-0053 必須)

4.1 評価軸 (3-5 個選定)

#軸 (Q42)日本語軸名重要度 (係数)案件特有の解釈
1#reliable信頼性Must (×2.0)読み落としても本質規約 8-10 個が確実に context に載る率 (目標 > 95%)
2#efficient効率性High (×1.0)差戻しループ削減量 (目標: session あたり 1-2 回 → 0-1 回)
3#maintainable保守性Must (×2.0)チェックリストと本体 SSoT のずれ検出率 (目標: key phrase 検証で phrase 一覧化された規約 100%・追加規約は phrase リスト更新運用で担保)
4#operable運用性High (×1.0)全クローンで同一挙動 (目標: クローンごとのばらつきゼロ)

K.O. criterion: Must 軸 (信頼性 / 保守性) score < 3 は不採用

4.2 評価軸 × 案スコア表

軸係数採択案 (A+C 組合せ)案 A 単独案 B (skill)案 C 単独案 D (MCP resource / system prompt 自動注入)
信頼性×2.054334
効率性×1.053453
保守性×2.035354
運用性×1.055353
加重和 (正規化)0.870.850.620.850.73
K.O. 通過 (Must ≥3)✓✓✓✓✓

保守性スコアは Gate 1 盲点検出 #2 を受けて 4 → 3 に再採点 (key phrase 検証は phrase リストに載っていない新規規約を検出できないため、byte 一致 100% には至らない)。K.O. criterion (Must 軸 ≥3) は通過を維持。

5. 検討した代替案

5.1 案 A 単独 (集約チェックリストのみ)

  • 信頼性: 読み落とし耐性は得られるが、AI がチェックリスト通りに書いても客観規約 (11 節構造・仮置きの語句禁止等) の書いた直後の機械強制がなく、事後 CI 検出のまま残る
  • 効率性: 差戻し削減効果は部分的 (チェックリストで AI が気付ける主観規約のみ効く)
  • 保守性: 追加要素なしで最小変更

5.2 案 B 単独 (/adr-draft-write skill)

  • 信頼性: skill を呼び出した時だけ context に template + style-guide 全文が載るため、呼出タイミングでは完全に効く
  • 運用性: user が skill を呼ばずに草案を書き始めると効かない。呼出の周知が全クローンの利用者に浸透する必要があり bottleneck になる
  • 効率性: skill の説明文は数千字あり、呼出のたびに context 消費が大きい

5.3 案 C 単独 (PostToolUse hook のみ)

  • 信頼性: 客観規約 (11 節構造・仮置きの語句禁止・実装配線節) は機械強制で 100% 検出できるが、主観規約 (英語密度 3 軸・Tier A・インデント) は既存 lint が未実装のため検出できない
  • 効率性: 書いた直後の検出により差戻しはほぼゼロに近づく
  • 保守性: フックは .claude/settings.json の更新のみで完結する

5.4 案 D (MCP resource / project-level system prompt 自動注入)

Gate 1 盲点検出 #4 を受けて追加。規約全文を MCP resource または project-level system prompt として毎 session 自動注入する構造的解決策。

  • 信頼性: AI の Read 判断に依存せず規約全文が毎回 context に載るため、読み落とし率は理論上 0% に近づく
  • 効率性: 全 session で規約全文 (数百行 × 3 file) が context を消費し、ADR 起案しない session でも context 圧迫が続く
  • 保守性: MCP resource 定義は 1 箇所に集約されるが、system prompt 側の設定は Anthropic 側の設定 UI に依存し git 管理から外れる
  • 運用性: 全クローンで同一挙動になるが、Anthropic 側の MCP / system prompt 仕様変更に追従する必要がある。skill 案と同じく Anthropic 依存の bottleneck が残る

5.5 現状維持 (対策なし)

  • 信頼性: 読み落とし由来の出力ズレが継続し、差戻しのコストも継続する
  • 効率性: 起案数に応じて差戻し累積が継続し、年間で無視できない工数になる
  • 保守性: 対策を追加しない分、ずれの監視は不要

6. 影響

6.1 正の影響

  • 信頼性: 読み落とし耐性がチェックリストで確保され、書いた直後のフックで客観規約が機械強制される二重の防御体制が確立する
  • 信頼性: 主観規約 (英語密度 3 軸・Tier A) はチェックリストで「AI に守らせる」形にとどまる。lint ルール化は本 ADR の scope 外とし、別 ADR で扱う (起票期限: 2026-10-02 = 本 ADR §9 Confirmation の 3 ヶ月レビュー時点・トリガー: §9 の 3 ヶ月レビューで AI 依存の残る規約違反が 5% 未満に収まりつつも主観規約違反が過半を占める場合)
  • 効率性: 差戻しは実測 1-2 回/session から 0-1 回/session への低減が見込める (書いた直後の検出で捕まえるため)
  • 効率性: フック発火のオーバーヘッドは 1 回の Write/Edit あたり数秒で許容範囲
  • 保守性: 集約チェックリストと本体 template.md / style-guide.md の key phrase 一致ゲートが新設される (scripts/check-adr-draft-checklist-sync.mjs + scripts/adr-checklist-phrases.json)
  • 保守性: 規約ファイル冒頭 30-50 行の追記で、本体規約部分との分離は維持される
  • 運用性: 規約ファイル・フック・lint スクリプトは全て git 管理で全クローンに自動配布される
  • 運用性: 別クローンが起票する草案の品質のばらつきが低減する

6.2 負の影響 / リスク

  • 信頼性: 「冒頭にチェックリストを置けば AI が template.md を自発的に Read する」という因果は未検証で、Anthropic の公開技術文書ではロストインザミドル現象 (中間部忘却) が記述されており先頭優先性質は限定的である。因果が成立しなかった場合の切替判断基準は §8 撤退条件 4 で担保する
  • 保守性: key phrase 検証は phrase リストに載っていない新規規約を検出できない false negative リスクを持つ。§9 Confirmation に月次手動 diff 確認を含めて補償する
  • 効率性: PostToolUse hook が節の途中で発火して 11 節未満の中間状態で誤検知が出るリスクは §3.3 仕様の前提チェック (## 11. 実装配線 文字列存在確認) で防ぐ
  • 信頼性: Edit tool の PostToolUse 後にファイル書き込みが完了していない競合状態のリスクは §3.3 仕様の guard 節 (最終更新タイムスタンプ + ファイルサイズ 0 超確認) で防ぐ
  • 効率性: チェックリスト 10 項目への形式的適合を目的化する Goal Displacement リスクがあり、項目チェック通過と草案品質は別能力である。§9 Confirmation に定性指標 (審査者による判断根拠再現度評価) を追加して補償する
  • 効率性: 「機械強制できる規約違反 0%」達成後に主観規約 lint 化への追加投資が先送りされる sunk cost リスクを持つ。§9 Confirmation の 3 ヶ月レビュー議題に別 ADR 起票状況確認を明示する

6.3 中立・トレードオフ

  • 保守性: phrase リストの分離 (scripts/adr-checklist-phrases.json) は template.md 改訂時に phrase リスト側の更新を強制する運用負荷を伴うが、byte 一致 100% を諦めて key phrase 部分一致に落とすトレードオフとして受容する

7. コスト試算

  • 設計・起案 = 0.1 人日 (本草案起票 + 起案審査)
  • チェックリスト起草 = 0.2 人日 (規約ファイル冒頭 30-50 行の集約・既存 template + style-guide からの抽出)
  • PostToolUse hook 配置 = 0.1 人日 (.claude/settings.json にフック設定を追加・scripts/hooks/ の既存パターンを踏襲・前提チェック + guard 節を含む)
  • key phrase 一致ゲート新設 = 0.1 人日 (scripts/check-adr-draft-checklist-sync.mjs + scripts/adr-checklist-phrases.json の作成 + CI 追加)
  • 合計 = 0.5 人日

8. 撤退条件

  1. 3 ヶ月運用 (2026-10-02) して出力ズレの発生率が 5% を超える (チェックリストが読み落とし耐性を発揮していない) 場合、チェックリストを長文化して案 B (skill) に切り替える
  2. フック発火のオーバーヘッドが 1 草案あたり 30 秒を超える (Write/Edit のたびに lint を実行して累積する) 場合、対象を H2 節を書き終えた単位に限定する (heuristic: 空行 2 個または次の H2 の直前)
  3. key phrase 一致ゲートが月 3 件を超える false positive を出す (チェックリストと本体の同期タイミングのずれ) 場合、本体側を SSoT としチェックリストを機械生成 (scripts/generate-adr-draft-checklist.mjs) に切り替える
  4. 3 ヶ月時点で規約ファイルの tool_use 呼び出しログを 3 件以上サンプリングした結果「チェックリスト参照 → template.md Read」の因果が 2 件未満でしか成立していない場合、hook 側で規約ファイル Read を強制するアプローチ (PostToolUse の前段 PreToolUse hook で規約 Read 履歴を確認) に切り替える

9. Confirmation

  • 検証手段 1 (出力ズレ発生率): 3 ヶ月後 (2026-10-02) に別クローンが起票した草案を 5 件以上サンプリングして出力ズレの発生率が 5% 未満であることを確認する / 実行頻度: 3 ヶ月後 1 回 / 違反時対応: §8 撤退条件 1 発動 (skill 切替検討)
  • 検証手段 2 (差戻し率): 3 ヶ月後に session の総ループ数と差戻しループ数を比較し、差戻し率が 10% 未満であることを確認する / 実行頻度: 3 ヶ月後 1 回 / 違反時対応: hook 発火条件 / 前提チェック仕様を見直し
  • 検証手段 3 (key phrase 一致ゲート成功率): key phrase 一致ゲートが月次 CI で成功率 100% を維持していることを確認する / 実行頻度: 月次 / 違反時対応: §8 撤退条件 3 発動 (機械生成切替検討)
  • 検証手段 4 (false negative 検出): 月次で template.md / style-guide.md の git diff と phrase リストの差分を手動で 1 件確認し、phrase リストに載っていない新規規約を発見した場合は phrase リストを追記する / 実行頻度: 月次 / 違反時対応: phrase リスト更新 + 該当草案の追加 lint
  • 検証手段 5 (判断根拠再現度・定性): 3 ヶ月後レビュー時に審査者が草案を読んで判断根拠を再現できたかを 5 段階評価し、平均 3.0 以上を維持することを確認する / 実行頻度: 3 ヶ月後 1 回 / 違反時対応: チェックリスト項目のうち定性項目 (Tier A・1 文 1 メッセージ) を lint 化する別 ADR の起票を前倒し
  • 検証手段 6 (主観規約 lint 化 ADR 起票状況): 3 ヶ月後レビュー時に主観規約 lint 化の別 ADR (起票期限 2026-10-02) が起票されているかを確認し、未起票の場合は本 ADR の driver ([email protected]) が起票を必須化するか撤退条件を発動するかを判断する / 実行頻度: 3 ヶ月後 1 回 / 違反時対応: driver 判断で起票必須化 or §8 撤退条件 1 発動

10. 参照

10.1 関連 ADR

  • ADR-0091 (起案前ゲート 3 ルール): チェックリストが同機構の延長線に位置付く
  • ADR-0097 (起案テンプレ canonical 11 節): 本 ADR はチェックリストの 11 節規約の SSoT として ADR-0097 を参照する
  • ADR-0129 (path-scoped rule のロード機構): PostToolUse hook 配置の前提
  • ADR-0159 (5 クローン並行運用): 全クローン配布の前提
  • ADR-0176 (§実装配線 lint 強制 + WIRING_LINT_ENABLED feature flag): フック配置の前例
  • ADR-0182 (rendered ADR canonical 11 節 = draft 11 節に byte 一致): チェックリストの 11 節規約の SSoT

10.2 関連 PR/Issue

  • PR #3804 (drp/chat 入れ子 markdown リストの深さスタック修正): 本 ADR 起案の契機となった描画不具合。ただし書き手側 AI のインデント欠落は本 ADR の scope 外とし、別 ADR で扱う (起票期限: 2026-01-31・トリガー: 本 ADR の対策運用後も §2 信頼性で挙げた早わかり節の崩れが月 1 件以上発生した場合)

10.3 外部資料

  • Anthropic 公開技術文書「Claude context 処理特性・ロストインザミドル現象」: §6.2 で参照する先頭優先性質と中間部忘却のトレードオフの根拠

11. 実装配線

  • lint 配線: scripts/adr-draft-lint.mjs の既存 7 ルールは本 ADR で変更しない。新設は scripts/check-adr-draft-checklist-sync.mjs (チェックリストと本体 SSoT 3 file の key phrase によるずれ検証・phrase リストは scripts/adr-checklist-phrases.json に分離) と .github/workflows/adr-draft-lint.yml へのチェックリスト同期ゲート追加
  • 起案フロー配線: .claude/settings.json の hooks.PostToolUse にエントリを追加する (matcher = Write|Edit・file pattern = tasks/prompts/draft_adr_*.md または docs/adr/[0-9][0-9][0-9][0-9]-*.md・run = node scripts/adr-draft-lint.mjs $CLAUDE_FILE_PATH)。hook スクリプト冒頭に前提チェック (対象ファイルに ## 11. 実装配線 文字列が含まれること) + guard 節 (ファイル最終更新タイムスタンプ + ファイルサイズ 0 超確認) を実装
  • docs SSoT 同期: .claude/rules/adr-draft.md の H1 直下に「## 起案者統一チェックリスト (読み落とし耐性)」を新設して 10 項目を項目で列挙する。docs/_meta/templates/adr-draft.template.md と docs/_meta/templates/adr-draft-style-guide.md に「本ファイルはチェックリストと key phrase 一致の契約関係にある」旨を明記する。docs/_internal/05_how-to/workspace_rules.md の drp 領分マトリクスに新しい lint スクリプト (check-adr-draft-checklist-sync.mjs) と phrase リスト (adr-checklist-phrases.json) を追加する (drp 所有を継続)