ADR-0099: ADR 正規構造に「実装スコープ」を第一級セクションとして追加し、コスト試算の構造定義(ADR-0024 / body-generation rule-9)を ADR-0088 と同期する

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

コンテキスト

§1.1 背景

ADR 正規構造(ADR-0024 が定義する見出し集合 / body-generation prompt のテンプレート)には「実装スコープ・段階化・ロールアウト方針」を書く第一級セクションの定位置が存在しない。起案者も body-generation も「どこに書くか」の構造的ガイドが無く、実装スコープは影響セクションや撤退条件に散在し、Gate 1 盲点(スコープクリープ)と Gate 4 §5 低評価を繰り返し招いている。

一方でコスト試算は既に ADR-0088 が第一級化を完了している(起案前ゲート + operator_guide §4.1 テンプレ必須 + adr-lint cost-estimation-section = ## コスト試算 見出し + 数値 1 つ以上)。したがって本 ADR が解くべきコスト試算側の課題は「追加」ではなく、**ADR-0088 が決めた事実が構造定義 doc(ADR-0024)と body-generation の rule-9 マッピング表に反映されていない「定義同期の欠落」**である。

§1.2 現状 (As-Is)

定量根拠(D1 telemetry blind_spot_findings, 31 pipeline run / 269 findings, 2026-05-29 抽出):

動機づけの実例: 2026-06-01 に ADR-0098 で、生成本文がコスト試算表を §影響内の太字バレットに格下げし adr-lint cost-estimation-section が落ちた(commit e011029 で手動 ## コスト試算 に昇格して解消)。これは正規構造の欠落ではなく、正規構造定義(ADR-0024)・デプロイ済み prompt・lint の三者がずれていることの典型症状である。実装スコープに至っては三者いずれにも定位置が無く、ずれ以前に存在しない。

§1.3 課題

読み取れる因果: 定位置のあるテーマ(撤退 11%・検証 37%)に比べ、定位置の無い実装スコープ(22%)が高頻度で盲点に突かれている。コスト(30%)は ADR-0088 で構造的対応が決定済みであり、残る盲点は body-generation prompt の未デプロイ(DOC-OPS-14)による定義同期遅延が主因と解釈する。実装スコープは散在ゆえスコープクリープ盲点と Gate 4 §5 低評価が再発している。

§1.4 制約・要件

• 起案者負担を最小化する(「粗くてよい」前提、30〜60 秒/起案)。
• ADR-0088 の lint・起案前ゲート・テンプレを再利用し二重定義しない。
• 適用範囲は新規起案のみ(既存 ADR の遡及改訂は不要)。
• 認知負荷を抑えるため追加セクションは実装スコープ 1 節に限定、監視は Confirmation に集約。

§1.5 目標 (To-Be)

実装スコープを第一級セクション化し、コスト試算は ADR-0024 / rule-9 への定義同期に限定。Confirmation を「監視/計測指標 1 つ以上明示」要求で強化。Non-Goals: コスト試算の lint/ゲート/テンプレ新設、監視独立セクション新設、既存 ADR 遡及改訂、DOC-OPS-14 解決、データ/依存/性能テーマのセクション昇格。

決定

ADR 正規構造に ## 実装スコープ(やること / Non-Goals / 段階化・ロールアウト方針)を第一級セクションとして追加し、コスト試算は ADR-0024 正規構造定義と body-generation rule-9 マッピング(【実装スコープ】→ ## 実装スコープ / 【コスト試算】→ ## コスト試算)への定義同期のみを行う(lint/ゲート/テンプレは ADR-0088 を再利用、二重定義しない)。Confirmation 仕様には「運用・監視/計測指標 1 つ以上明示」要求を追加し、34% の監視盲点を集約吸収する。未記入時は body-generation が 未評価 固定トークンを出力し、section_empty_rate telemetry field で空節を機械検知する。adr-lint implementation-scope-section は warn で導入し、保有率実績に応じて段階的に error 昇格を検討する。

判断基準 (Decision Drivers)

ドキュメント/規約系アーキタイプ(adr_decision_drivers_guide §4)。重み: Must ×2.0 / High ×1.0 / Medium ×0.5。

3.1 評価軸

K.O. criterion: Must 軸(#maintainable / #operable)いずれかで score < 3 の案は不採用。

3.2 評価軸 × 案スコア表

加重和 = Σ(score × 係数) / (5 × Σ係数)、Σ係数 = 5.5、分母 = 27.5。

検討した代替案 (Alternatives Considered)

• 案A(何もしない / 起案ガイド文だけ強化): 構造定義に定位置を与えず operator_guide の散文だけ厚くする。#maintainable=2(単一定義にならず暗黙のまま)・#operable=1(機械検知不能)で Must 二軸 K.O.。実装スコープ 22% 盲点と ADR-0098 型の三者ずれが放置される。不採用。
• 案B(入力補助テンプレートのみ、構造定義 ADR-0024 は変更しない): 起案テンプレに節を足すが正規構造定義・rule-9 は更新しない。#operable=2(テンプレと定義/lint が乖離し ADR-0098 型再発)で K.O.。次点だが定義同期が無く効果が半減する。不採用。
• 案C(実装スコープを独立節化せず §影響配下に置き続ける): 現状の場当たりを継続。#maintainable=2 / #operable=2 で K.O.。スコープクリープ盲点の定位置が生まれず、書き場所が不定のまま。不採用。
• 採択案: 実装スコープを第一級化し、コスト試算は ADR-0088 同期に限定、監視は Confirmation 集約。Must 二軸を通過し認知負荷も追加 1 節に抑える。

実装スコープ

(本節自体が新設セクションの運用例を兼ねる。実装スコープ＝やること/Non-Goals/段階化、Confirmation＝KPI による検証、撤退条件＝失敗時の閾値、と責務を分ける)

やること:

• (a) ADR-0024 改訂(sub): 正規構造定義に「実装スコープ」を第一級セクションとして追加し、コスト試算の定位置を明記する(ADR-0088 を出典として参照し二重定義しない)。Confirmation の監視/計測明示要求も追記。
• (b) body-generation prompt 改訂(main・prompts は sub 読み取り専用): rule-9 マッピングに 【実装スコープ】→ ## 実装スコープ / 【コスト試算】→ ## コスト試算 を追記。テンプレ本文に ## 実装スコープ H2 を追加(## コスト試算 / ## Confirmation は既存)。未記入時の 未評価 トークン出力ルールを明記。
• (c) operator_guide §4.1 改訂(sub): 起案項目に ## 実装スコープ(やること / Non-Goals + 段階化、粗くてよい)を追加。
• (d) adr-lint に存在チェック追加(main): implementation-scope-section(仮称)= 新規 ADR に ## 実装スコープ 見出しの存在を severity: warn で検査。error にはしない(起案体験の阻害回避。コスト試算が error なのと差別化)。段階昇格条件は Confirmation で別途定義。
• (e) telemetry に section_empty_rate field を新設(main): 節は在るが本文が 未評価 のみ・空の率を計測する新規 field を audit スキーマに追加する。撤退判定の観測ループを成立させる。
• (f) gate4-scoring との整合確認(main): 実装スコープ節が gate4 §5 impact_scope 採点を正しく裏付けるかをプロンプト読み合わせで確認(採点ルーブリック自体は変更しない)。

Non-Goals:

• コスト試算の lint・起案前ゲート・テンプレの新設(ADR-0088 が担当、二重定義しない)。
• 監視/計測の独立セクション新設(Confirmation 集約で吸収)。
• 既存 ADR の遡及改訂(新規前進適用のみ)。
• body-generation prompt の KV デプロイ問題(DOC-OPS-14)の解決(直交、本 ADR は定義側でデプロイは main の別タスク)。
• データ/依存/性能テーマのセクション昇格。
• 本 ADR のコスト試算は内部検討用の概算であり、会計上の費用計上根拠・発注書・見積書を構成しない(電帳法・税務上の証憑要件は対象外)。

段階化・ロールアウト: (e) telemetry section_empty_rate を先行(観測ループ確保)→ (a) ADR-0024 + (c) operator_guide → (b) body-generation rule-9 + テンプレ → (d) adr-lint warn。各段で空節率を観測する。warn → error 昇格は導入 8 週後に保有率・空節率の実績で判断する別決定とする(本 ADR では未確定)。

役割境界: 構造定義(ADR-0024)・operator_guide・規約は sub、body-generation prompt・adr-lint・gate4-scoring・telemetry スキーマは main(prompts/scripts は sub 読み取り専用)。cross-workspace 作業。三者(ADR-0024・body-generation・adr-lint)の定義バージョンは将来 manifest 化を検討するが本 ADR の範囲外(別 ADR)。

注記: gate4 採点 §5 impact_scope(影響範囲＝ファイル/モジュール/データ/ステークホルダー)と起案者が書く ## 実装スコープ(やること/Non-Goals/段階化)は別概念であり、実装スコープ節は §5 採点を裏付けるが同一ではない。また adr-lint の scope-meta(Kruchten Scope メタ: corporate/platform/product/ops)とも無関係である。

コスト試算

本 ADR 自身のコスト(新設する実装スコープ節の運用例を兼ねる)。

• 追加 LLM コスト: body-generation は単一パスを維持。実装スコープ 1 節分のトークン微増(出力 +約 200 tok/起案)のみで月数十円未満、実質無視可能。Opus 追加コールはゼロ。むしろ書き場所が明確になり差し戻し再投入が減りトータルは削減方向。
• GAS 実行時間: 増分なし(Pipeline は Cloudflare Workers 上、GAS 外 / ADR-0019)。lint は正規表現 1 回(数 ms)。
• 起案者負担: 実装スコープ 30〜60 秒/起案(粗い記述前提)。コスト試算は ADR-0088 の既存負担で増分ゼロ。

影響 (Consequences)

§5.1 正の影響 (Good)

• 実装スコープに定位置ができ、低評価・差し戻し・盲点(22%)の再発が構造的に減る。
• スコープクリープを起案段階で抑止する。
• 正規構造定義・body-generation・lint の三者整合が取れ、ADR-0098 型のずれを検知可能にする。
• Confirmation 強化で監視/計測(34%)も底上げする。

§5.2 負の影響 (Bad)

• 起案セクションが 1 つ増える(「粗くてよい」と未記入時 未評価 明示で緩和)。
• ADR-0024 改訂で新旧 ADR の見た目に差(遡及改訂しないため新規のみ。横断分析は新形式を対象と明示)。
• 本 ADR 自体の実装スコープが (a)-(f) 6 タスクに渡り、単純な構造定義追加と比較して広い。Gate 2 で複合判定を受けるリスクあり(後述 Risk)。

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

• Gate2 で ADR-0088 と重複/衝突判定される(最大リスク)→ 本文・タイトル・代替案・参照のすべてで「コスト試算は ADR-0088 が第一級化済、本 ADR は構造定義同期のみ・lint/ゲート/テンプレ再利用・二重定義しない」を一貫明記して回避する。
• warn 止まりの強制力不足: adr-lint を warn 導入とする一方で Confirmation KPI は保有率 ≥ 90% を要求する。1 人開発では warn が「無視するノイズ」と認知されるリスクあり。Confirmation で「warn 発火数 / 対応数 / 無視数」を 4 週ごと可視化し、warn 無視率 50% 超を撤退トリガに加える。保有率実績に応じて warn → error 段階昇格を別決定で扱う。
• 三者整合の連鎖更新漏れ: ADR-0024・body-generation rule-9・adr-lint・ADR-0097 マッピング表・DOC-OPS-14 KV デプロイ・gate4-scoring の 6 つの独立更新が cross-workspace で発生し、CI ゲートが未整備。manifest 化は本 ADR 範囲外(別 ADR)とし、当面は DOC-OPS-14 KV デプロイ完了を Confirmation KPI に含めることで暫定対応する。
• スコープクリープの自己矛盾: 本 ADR の実装スコープが 6 タスク + Confirmation 強化を含み、(e) telemetry / Confirmation 強化は厳密には「定位置の欠落」と直交する。一括採用の根拠は「観測ループなしでは撤退判定が機能しない / 監視盲点 34% が最大未対応テーマでありセクション過多を避けるため Confirmation 集約が最小手」であり、これを撤回した縮退案(構造定義のみ)は §3.2 案B として既に K.O. 済み。Gate 2 で複合判定された場合は telemetry を分離 ADR に切り出す縮退余地を残す。
• 形骸化(空節量産): 節を設けても 未評価 だらけになりうる → body-generation が 未評価 を明示し section_empty_rate で監視、空節率が高止まりなら撤退する。将来 body-generation が起案入力から実装スコープ草案を推論出力する拡張も検討余地(別 ADR)。
• 定位置付与の因果仮説の検証: 定位置のある撤退(11%)も依然盲点に突かれていることから、定位置の有無と盲点頻度の因果は未確証(相関の可能性)。Confirmation で「節の存在」だけでなく「内容充実度」と「節あり充実 vs 節あり未評価のみ」の層別比較を行い、仮説棄却時は撤退する。
• 起案放棄率の上昇: セクション増が ADR 起案そのものの放棄を招くリスク。Confirmation に新規 ADR 起案件数の前後比較を含め、20% 以上減少で撤退トリガ。
• 責任者のバスファクター 1: 撤退判断責任者を起案者個人名で記述する点。本 ADR では運用上「ADR オーナー」ロールとして読み替え可能とし、開発者数 3 名超で再評価する撤退トリガを加える。
• 実装スコープ と 撤退条件 / Confirmation の境界: 三者の責務を実装スコープ冒頭で 1 行定義し重複記述を避ける。
• 監視を Confirmation 集約にした判断: 将来 34% の監視盲点が集約で吸収しきれないと判明したら、監視セクション新設を別 ADR で起案する(本 ADR では昇格させない)。

撤退条件 (Rollback Plan)

撤退判断の責任者 = ADR オーナー(現時点では起案者 代表取締役)、判定 = 4 週ごとの定期レビュー(calendar 登録・未実施は自動 warning)。観測ループ (e) section_empty_rate が未実装の場合は観測不能のため本 ADR を撤回する(ADR-0088 と同じ原則)。

sunk-cost バイアス対策(起案者 1 名): 撤退判定を pipeline 内部指標(§5 スコア・空節率)だけに依存させず、pipeline 外の独立指標「実装スコープ起因の差し戻し件数の実数」を最低 1 つ併用する。判定はチェックリスト方式で構造化する。

Confirmation

観測可能 KPI で判定する(グッドハート回避のため複数指標を併用)。

• 実装スコープ節の保有率 ≥ 90%(導入 4 週後、adr-lint warn レポート集計)。
• 実装スコープ/コスト節の section_empty_rate ≤ 20%(telemetry 新設 field)。
• 実装スコープ盲点の finding 頻度 22% → 15% 以下(導入 8 週後、blind_spot_findings テーマ集計)。
• gate4 §5 impact_scope 平均スコア +0.5 pt 以上改善(導入 8 週後)。
• 実装スコープ節の内容充実度スコア(単語数または構造的要素数の中央値、層別分析用)。
• warn 発火数 / 対応数 / 無視数(4 週ごとレビューで可視化、warn 無視率撤退トリガ用)。
• 新規 ADR 起案件数の前後比較(起案放棄率上昇の早期検知)。
• DOC-OPS-14 KV デプロイ完了(未デプロイ状態での新規 ADR マージはブロックしないが Confirmation 未達として扱う)。

検証手段: adr-lint implementation-scope-section(warn)を全 PR の CI でチェックし、telemetry 集計を 4 週ごとレビューする。本 ADR が強化する Confirmation 仕様自体に「監視・計測指標を 1 つ以上明示する」を要求し、34% の監視盲点を Confirmation 集約で受ける運用例とする。実行頻度: PR 単位(adr-lint)+ 4 週ごと(telemetry レビュー)。違反時対応: warn 違反は起案者へ通知(merge はブロックしない)、KPI が撤退トリガに該当したら ADR オーナーがレビューしソフト化または撤回する。

参照 (References)

• 関連 ADR:
  • ADR-0088(コスト試算必須化 / Accepted): コスト試算は ADR-0088 が 3 層(起案前ゲート + operator_guide §4.1 テンプレ必須 + adr-lint cost-estimation-section = ## コスト試算 見出し + 数値 1 つ以上、ADR-0088+/Standard・Critical 適用)で第一級化を完了済み。本 ADR はコスト試算を追加しない。貢献は ADR-0088 が決めた事実を構造定義 doc(ADR-0024)と body-generation rule-9 マッピングに同期することに限定し、lint/ゲート/テンプレは ADR-0088 を再利用する(二重定義しない)。
  • ADR-0024(正規構造定義 / Accepted): ADR-0024 が定義する §1.x / §5.x 正規構造に、本 ADR が実装スコープを第一級セクションとして追加し、コスト試算の定位置を明記する。ADR-0024 の「1 人開発では過剰な区別を統合する」思想を踏襲し、追加は実装スコープ 1 節に限定、監視は Confirmation 集約とする。判断基準が ADR-0053 で構造定義に後付け追加されたのと同じく、構造定義への追補にあたる。
  • ADR-0097(起案↔本文 § 整合 / 採番済・PR #1239 merged 2026-06-01): ADR-0097 が起案テンプレ最上位見出しを本文正規 § に 1:1 で揃えるマッピング表を定義済。本 ADR はその正規構造に実装スコープ行を足す。ADR-0097 §参照の canonical-structure 条件節(「Accepted されれば 実装スコープ → ## 決定 配下 を追加。Rejected / 大幅修正なら現行維持」)に従い、本 ADR Accepted 後に ADR-0097 のマッピング表へ後続反映する。両 ADR の審議は時間的に分離し相互参照による確証バイアスを避ける。
  • ADR-0053(判断基準必須化 / Accepted): Standard 以上で §判断基準を起案者必須化。本 ADR の判断基準節はこれに準拠する。構造定義へ後から軸を追加した先行パターンとして、本 ADR の「実装スコープ追加」を正当化する。
  • ADR-0086 / ADR-0087(telemetry v3 / Accepted): 本 ADR の定量根拠(blind_spot_findings 31 run / 269 findings)の出所。本 ADR が新設する section_empty_rate field は telemetry スキーマへの追補にあたる。
  • ADR-0091(数値要件 / Accepted): 撤退条件・完了条件の数値必須化と placeholder 禁止ゲート。本 ADR も全ゲートを充足する。実装スコープ節の 未評価 固定トークンは placeholder スキャン対象外(コードブロック / Non-Goals 除外と同じ扱い)とし、空節は section_empty_rate で別途検知する。
  • ADR-0036(Confirmation / Accepted): 本 ADR は Confirmation 仕様を「監視 / 計測指標の明示要求」で強化する。
• 関連 PR/Issue:
  • DOC-OPS-14(TODO 項目・文脈言及): body-generation prompt(## コスト試算 / ## Confirmation H2 を含む v1.3.0 / 1.4.0)が KV 未デプロイのため新規 Standard ADR が adr-lint で fail し手動遡及している既知問題。本 ADR は「正規構造定義・デプロイ済み prompt・lint の三者がずれている」文脈の一部として言及する。本 ADR で追加する ## 実装スコープ テンプレも KV デプロイ後に有効化される(デプロイは main 領分・DOC-OPS-14 と同じ KV push 経路)。
  • ADR-0098 関連 commit e011029(手動 ## コスト試算 昇格事例)
• 外部資料: adr_decision_drivers_guide §4(ドキュメント/規約系アーキタイプ)