ADR-0097: 起案者生テキストのセクション構造を ADR 本文の正規構造に揃える (盲点効果検証・品質分析のため)

• Status: Accepted
• Mode: Standard
• Kruchten Type: Property/Executive
• Scope: platform
• Implementation Status: Done
• 起案者: [email protected]
• 起案日時 (JST): 2026-06-01 16:26
• 承認日時 (JST): 2026-06-21
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

ADR 制度の品質分析 (どの § が薄いか・盲点指摘がどの § にどう反映されたか) を回すには、起案テキストと本文を § 単位で照合・集計できる必要がある。しかし現状、起案者生テキスト (operator_guide §4.1 形式) と Pipeline が生成する本文 (body_generation / ADR-0024 の正規構造) でセクション体系が異なり、機械的な突き合わせができない。最上位 § は両者でほぼ 1:1 対応するのに見出しが揃っていないことが原因。

§1.2 現状 (As-Is)

2026-06-01 時点で ADR は計 96 件 (Accepted 76 / Proposed 17 / Superseded 3)。起案テキストと本文の § 構造が揃っているものは 0 件で、§ 単位の横断集計の母集団が事実上ゼロ。2026-05-12 以降の約 3 週で 88→96 件に増加 (Proposed 39→17 と多くが Accepted 化)。

§1.3 課題

起案は活発で母数は十分あるのに § 整合が無いため照合・集計に使えていない。

本 ADR が解くこと / 解かないこと (自己完結性と限界を明示):

• 解く = (1) § 単位で照合・集計可能にする構造的基盤 (新規 ADR の見出し整合 + 既存 96 件の外付けインデックス) の生成、(2) その基盤が集計に使えることの最小実証 (外付けインデックスを入力に § 別集計を one-shot で 1 回出す)。本 ADR は基盤生成と 1 回の集計実証までで完結し、成功判定が他 ADR に依存しない。
• 解かない (別 ADR に委譲) = (e) 集計の定常運用環境 (スケジューラ・実行環境管理・属人化対策・継続集計) と、(B) 盲点の因果効果の証明 (中間出力保存=2 パス化)。重要: (e) は「集計の自動化・定常運用」であって「最初の集計実証」の前提ではない。one-shot 実証 (本 ADR の (d2)) は外付けインデックスさえ在れば簡易スクリプトで実行でき、(e) の完了を待たない。したがって主目的「§ 単位で照合・集計できる」は本 ADR 単体で達成・検証できる (Cross-Validation 盲点 #1 解消)。
• 因果効果の厳密証明は別問題: 同一 § で「盲点注入前/後」を厳密比較するには body_generation 前の中間出力保存 (2 パス化) が必要だが、現状は単一パス上書き (body_generation.ts:170)。見出しを揃えても counterfactual の片方が無く、§ 差分は「整形 + 言い換え + 盲点加筆」の混合のまま。これは案 B (別 ADR) に委譲し、本 ADR の KPI は「§ 別集計が 1 回出せること」までとする (因果証明を KPI にしない)。

§1.4 制約・要件

• 既存 96 件の本文は不変更 (監査上の原文不変性確保)。
• 見出し正規化レイヤーは LLM 不使用 (文字列処理のみ)。
• クリティカル § (決定 / 判断基準 / 撤退条件) は完全一致のみ、誤マッピング 0 件必須。
• Pipeline は UNMATCHED でも停止しない (起案フロー阻害禁止)。
• 本 ADR スコープは最小 (約 4.0 人日)、(e)(f)(B) は別 ADR に分離。

§1.5 目標 (To-Be)

新規 ADR の起案↔本文を § 単位で照合可能にし、既存 96 件は外付けインデックスで照合可能化。one-shot で § 別集計が 1 回出せる状態を本 ADR 単体で達成する。Non-Goals: 因果効果の厳密証明、定常運用環境構築、3 ドキュメント整合 CI。

決定

起案テンプレ (§4.1) の最上位見出しを本文の正規 § に 1:1 で揃える。適用範囲とデータ破壊回避を最小スコープで設計する。

1. 新規 ADR のみ前進適用: 見出し統一は本 ADR Accepted 後に起案される新規 ADR に適用する。
2. 既存 96 件は本文を一切書き換えない (外付けインデックス方式): 既存 ADR の本文は不変更とし、別ファイルの外付け「見出しマッピング・インデックス」(メタデータのみ) を生成して § 照合を可能にする。これにより、移行バッチによる Accepted 済み ADR の原文改竄・正規表現の本文誤ヒット・ADR-0024 サブ見出しとの衝突・Superseded 特殊フォーマット破損のリスクを構造的にゼロにする (一括本文書き換えを行わない)。
3. 判断基準は起案者必須セクション: 判断基準の軸選定 (Q42 タグ) は ADR-0053 で起案者が supply する必須セクションであり、Pipeline が生成するのは評価軸の加重和スコア表 (§2.2) のみ (operator_guide §227)。判断基準・コスト試算・Confirmation/完了条件 は起案者が記述する。
4. 見出し正規化は LLM 不使用 + 厳格 UNMATCHED: body_generation 前段に見出し正規化レイヤー (文字列の完全一致辞書) を置く。未ヒットは推測転記せず必ず UNMATCHED 扱いとし、サイレント誤マッピングを禁止する。特に § 決定 / §判断基準 / §撤退条件 のクリティカル § は完全一致のみ・誤マッピング 0 件を必須基準とする。マッピング失敗時は UNMATCHED タグを付けて Pipeline は続行 (停止しない) し、転記結果を起案者にプレビュー表示して人間確認を挟む (挙動を仕様として固定)。

判断基準 (Decision Drivers)

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

3.1 評価軸

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

3.2 評価軸 × 案スコア表

検討した代替案 (Alternatives Considered)

• 案 A (現状維持): 起案テンプレ §4.1 と本文 § を別体系のまま維持 — #suitable で K.O. (§ 別集計の母集団が 0 件のまま、品質分析が成立しない)。
• 案 B (中間出力保存=2 パス化で因果効果証明): body_generation を 2 パス化し盲点注入前/後を保存 — スコープ過大 (因果証明は別問題)、本 ADR の主目的「§ 照合基盤」を独立に達成する方が筋が良いため別 ADR に委譲。
• 案 C (既存 96 件本文一括書き換え): 移行バッチで既存 ADR の見出しも揃える — Accepted 済み原文改竄 / Superseded 特殊フォーマット破損リスクが大きく #maintainable で K.O.。

影響 (Consequences)

§5.1 正の影響 (Good)

• 起案↔本文を § 単位で照合でき、§ 別横断集計 (どの § が薄いか) が回せる。
• 既存 ADR を書き換えないため原文の不変性 (監査要件) を保ったまま照合可能。
• body_generation ルール 9 が「同名見出し→同 §」に単純化し転記漏れが減る。

§5.2 負の影響 (Bad / トレードオフ)

• 起案者に最小限の見出し付けを課す (自由記述→軽い構造化)。起案件数が減るリスク → プレースホルダーをデフォルト挿入 (「埋める」だけ) で緩和。導入前後 8 週で起案件数 10% 以上減を追加撤退トリガーに (盲点 #11)。
• 外付けインデックスは本文と二重管理になる → インデックスは生成スクリプトで再生成可能とし手編集しない (ドリフト防止)。
• 新形式 (見出し統一) と旧形式が混在する期間、横断集計は「新形式 + 外付けインデックスで照合済み」を母集団と明示。
• 外付けインデックスの「準正典」化ロックイン (Gate1 盲点 #1, #12): インデックスが下流スクリプトの中心ノードになると撤退困難になる。撤退条件にインデックス無効化・依存解除手順を明示 (後述)。インデックス方式の見直しトリガー = 「インデックス生成から 12 ヶ月後、または ADR-0024 改版時に本文書き換え移行の費用対効果を再評価」を Confirmation に組み込む。
• § 別集計のグッドハート汚染 (盲点 #11): § 件数だけ満たすボイラープレート水増しを誘発しうる。(d2) 出力に § 文字数/行数分布を含め、利用ガイドラインに「§ 件数はナビゲーション支援であり品質評価指標ではない」と明記。

§5.3 中立・トレードオフ (Risks / 盲点レポート対応)

• R1 (盲点 #1, #suitable): 因果効果の証明は中間出力保存が必要 → 本 ADR スコープ外と明示。Confirmation は「§ 別集計が出せる」までに限定 (因果 KPI にしない)。
• R2 (盲点 #2, #suitable/#maintainable): 辞書サイレント誤マッピング → 完全一致のみ・未ヒットは厳格 UNMATCHED・クリティカル § 誤マッピング 0 件必須・起案者プレビュー・受け入れテスト 50 件。
• R3 (盲点 #3, #maintainable): 移行バッチのデータ破壊 → 既存本文を書き換えず外付けインデックス方式で構造的に回避。
• R4 (盲点 #high): スコープ拡散 → (e) 横断分析基盤・(f) CI チェックを別 ADR に分離。
• R5 (盲点 #13): canonical-structure 草案依存 → 後述「参照」で Rejected/大幅修正時の扱いを明示。本 ADR の Confirmation KPI は canonical-structure 依存条件を含めない。
• R6 (Gate1 盲点 #2 電帳法・監査要件): 外付けインデックスの監査上位置づけ未検証。インデックスファイルヘッダーに「本文を補足するメタデータであり本文と乖離した場合は本文を正とする」を機械可読に明記。社内文書管理規程との照合を §5.1 完了条件に含め、結果を本 ADR 完了報告に記載する。改ざん防止としてハッシュ検証・generatedAt・schemaVersion を埋め込む。
• R7 (Gate1 盲点 #3 Sheets API 副作用): インデックスおよび集計出力の正典ストアは JSON ファイルとし Sheets は表示用コピーに限定する。Sheets に書く場合は batchUpdate 一括化・フィルタビュー事前無効化・書き込み後チェックサム検証を実装仕様に含める。
• R8 (Gate1 盲点 #4 UNMATCHED 偏在): クリティカル § (決定/判断基準/撤退条件) の UNMATCHED 率を独立 KPI 化 (後述 Confirmation)。受け入れテスト 50 件に「Superseded・旧形式 ADR を最低 10 件含む」を必須化。
• R9 (Gate1 盲点 #5 プレビュー運用): プレビュー確認フロー (確認ボタン・タイムスタンプ記録・UNMATCHED 残存時は ADR メタに index-incomplete フラグ付与) を実装スコープ (b) に明記。被覆率集計は index-incomplete を除外母数とする。
• R10 (Gate1 盲点 #6 静かなドリフト): ハッシュ突合を主 KPI に昇格。(d2) 実行前の必須ステップとして本文ハッシュ検証を本 ADR スコープ内に含める ((f) 完了を待たない)。
• R11 (Gate1 盲点 #7 文字コード揺れ): 完全一致の前段に Unicode 正規化 (NFKC) + 空白統一 + BOM 除去の前処理。受け入れテストに「不可視文字混入バリアント」を含める。UNMATCHED プレビューに「正規化後の比較文字列」を表示。
• R12 (Gate1 盲点 #8 属人化): one-shot スクリプトに README (実行コマンド・必要権限・依存バージョン・出力形式) を必須成果物化。(d2) 完了定義に「第三者が README だけで再実行できること」を追加。実行環境は mise / Docker で固定。
• R13 (Gate1 盲点 #9 UNMATCHED 高止まり): 新規起案の UNMATCHED セクション率 ≤ 20% を副次 KPI に追加。4 週判定で高止まり時は辞書拡充 / プレースホルダー改善をアクション化。
• R14 (Gate1 盲点 #10 二重管理): インデックスファイルヘッダーに「本文が常に優先」を機械可読に明記。ハッシュ乖離検出時はインデックスを参照禁止フラグで即無効化。
• R15 (Gate1 盲点 #13 確証バイアス): (d2) 実証後 4 週以内に案 B と (e) の起案タイムラインをレビューするチェックポイントを設置。先送りが 3 ヶ月超の場合は「基盤あるが活用 0 件」と同等の問題として記録。

実装スコープ

本 ADR (最小スコープ):

• (a) 3 ドキュメント改訂 (§4.1 / operator_guide / body_generation ルール 9)。
• (b) 見出し正規化レイヤー実装 (完全一致辞書 + 厳格 UNMATCHED + クリティカル § 完全一致必須 + 起案者プレビュー + NFKC/空白/BOM 前処理 + プレビュー確認証跡)。
• (c') 既存 ADR 外付けインデックス生成 (本文不変更。見出し→§ マッピングのメタデータ別ファイルのみ出力。schemaVersion / generatedAt / 本文ハッシュ / 「本文優先」ヘッダーを埋め込み)。
• (d) 受け入れテスト 50 件以上 (過去 ADR の実見出しバリアントを網羅。Superseded・旧形式を最低 10 件含む。§ 決定/判断基準/撤退条件の誤マッピング 0 件を検証。UNMATCHED 率の実測値も計測。不可視文字バリアントを含む)。
• (d2) § 別集計の one-shot 実証: 外付けインデックスを入力に「§ 別件数」+「§ 文字数/行数分布」を集計する最小スクリプトを実装し、1 回実行して結果を確認。実行前に本文ハッシュ突合を必須ステップ化。README 同梱で第三者再現性を確保。

本 ADR のスコープ外 (別 ADR に分離):

• (e) 横断分析の定常運用環境 (スケジューラ・実行環境管理・継続集計) → 別 ADR。
• (f) 3 ドキュメント同時更新 CI チェック → 別 ADR (緊急修正をブロックしない警告モード/オーバーライド設計が要るため独立検討)。
• (B) 盲点前後の中間出力保存 (body_generation 2 パス化) → 別 ADR (因果効果の厳密検証が必要と判明した場合)。

役割境界: §4.1 / operator_guide / 外付けインデックス仕様の文書は sub。body_generation 改修・正規化レイヤー・インデックス生成スクリプトは main (cross-workspace)。

コスト試算

• 追加 LLM コスト: なし (正規化は文字列処理、body_generation は単一パス維持、(d2) も件数集計で LLM 不使用)。Opus 追加コール 0 / 運用コスト増 ≈ 0 円/起案。
• GAS 実行時間: 増分なし (Pipeline は GAS 外)。
• 旧 ~6.5 人日から、移行バッチ廃止 (本文書き換え→外付けインデックス) と (e)(f) 分離で約 4.0 人日に縮小 ((d2) one-shot 実証 0.25 を含む)。

撤退条件 (Rollback Plan)

以下のいずれかで §4.1 を自由形式に戻し、body_generation ルール 9 も従前の柔軟版に戻す (新規前進適用のみのため既存 ADR への影響なし)。

撤退トリガー:

• 起案見出しの強制が起案体験を著しく損なう: 導入前後 8 週で起案件数が 10% 以上減少 (盲点 #11)。
• 基盤が成立しない / 活用されない: 導入後 8 週以内に (d2) one-shot § 別集計が一度も実行できない (基盤不成立)、または 6 ヶ月時点で § 別集計の活用実績が累計 0 件 (活用フロー未整備)。判定は 4 週ごと (担当: 代表取締役)。4 週時点の前哨指標 = 見出し正規化レイヤーの稼働確認 (盲点 #10)。
• クリティカル § (決定/判断基準/撤退条件) の誤マッピングが本番で 1 件でも発生。
• インデックスと本文のハッシュ乖離が累計 5 件以上未解消で 4 週以上残置 (Gate1 盲点 #6)。

撤退手順 (Gate1 盲点 #1 対応・インデックス無効化):

1. §4.1 テンプレートと body_generation ルール 9 を従前の柔軟版に戻す PR を作成。
2. 外付けインデックスファイルに tombstone: true フラグと無効化日時を書き込み、参照禁止状態にする (削除はせず Git 履歴保持)。
3. (d2) 集計スクリプトおよび下流参照箇所 (将来の (e) スクリプト含む) を tombstone 検出時にエラー停止するよう改修。
4. インデックスを参照しているドキュメント・README から該当リンクを削除。
5. 撤退記録 ADR を起案し、tombstone 化日時・原因・残存 Git 履歴の取り扱いを明記。

インデックス方式の有効期限 (Gate1 盲点 #12): インデックス生成から 12 ヶ月後、または ADR-0024 改版時に本文書き換え移行の費用対効果を再評価する。

Confirmation

観測可能 KPI で判定。主 KPI は本 ADR 単体で完結する (別 ADR (e) に依存しない) ものに限定し、因果証明でなく「§ 別集計の基盤が成立し、実際に 1 回集計が出せたか」を主眼に置く (グッドハート回避で単一指標依存を避ける)。

主 KPI (本 ADR 単体で達成・検証可能):

• 外付けインデックス被覆率 ≥ 80%: 既存 96 件のうち UNMATCHED および index-incomplete フラグを除く照合可能件数 / 96。検証手段 = (d2) スクリプト出力 / 実行頻度 = 本 ADR 完了時 1 回 + 4 週毎レビュー / 違反時対応 = 辞書拡充または撤退判定。
• 見出しマッピング正解率 ≥ 90% かつクリティカル § (決定/判断基準/撤退条件) 誤マッピング 0 件: 受け入れテスト 50 件で検証 (Superseded/旧形式 ≥ 10 件含む)。検証手段 = 受け入れテストスイート / 実行頻度 = 本 ADR 完了時 + 辞書改修毎 / 違反時対応 = リリースブロック。
• クリティカル § UNMATCHED 率 ≤ 10% (Gate1 盲点 #4): 既存 96 件中のクリティカル § のうち UNMATCHED となった件数 / 全クリティカル §。検証手段 = (d2) スクリプトの内訳出力 / 実行頻度 = 本 ADR 完了時 1 回 / 違反時対応 = 辞書拡充必須、未達なら被覆率 KPI と独立に撤退検討。
• § 別集計の one-shot 実証 = 1 回成功: (d2) スクリプトで外付けインデックスを入力に § 別件数 + § 文字数/行数分布の集計を 1 回出力できること。(e) 定常運用環境を前提とせず本 ADR 内で完結し、主目的「§ 単位で照合・集計できる」の達成を本 ADR 単体で証明する (盲点 #1 解消)。検証手段 = スクリプト 1 回実行 / 実行頻度 = 本 ADR 完了時 / 違反時対応 = 完了判定保留。
• 本文 ↔ インデックスのハッシュ突合 = 100% (Gate1 盲点 #6): (d2) 実行前の必須ステップ。検証手段 = ハッシュ突合スクリプト / 実行頻度 = (d2) 実行毎 / 違反時対応 = 乖離分はインデックス再生成または tombstone 化。

副次 KPI:

• 活用実績 ≥ 1 件: § 別集計が実際の意思決定 (ADR 差し戻し・追記依頼など) に使われた件数。8 週で 0 件なら「基盤は成立したが活用フロー未整備」と明示記録。継続的な定常集計は別 ADR (e)。
• 新規起案の UNMATCHED セクション率 ≤ 20% (Gate1 盲点 #9): 4 週毎計測。高止まり時は辞書拡充 / プレースホルダー改善。
• 限界宣言 (Gate1 盲点 #13): one-shot 実証成功は § 照合基盤の成立を示すが、盲点効果の有無・因果関係・定常活用の達成を意味しない。(d2) 実証後 4 週以内に案 B と (e) の起案タイムラインをレビューするチェックポイントを設置。先送りが 3 ヶ月超で「基盤あるが活用 0 件」と同等の問題として記録。
• 監査要件整合性調査 (Gate1 盲点 #2): 社内文書管理規程と外付けインデックスの位置づけを照合し、結果を本 ADR 完了報告に記載する。

参照 (References)

• 関連 ADR:
  • ADR-0024: 本文 §1/§5 サブ見出し構造を定義 (Accepted)。本 ADR は起案側を合わせ本文側 § は変更しない (前提維持)。
  • ADR-0053: §判断基準を Standard 以上で起案者必須化 (Accepted)。判断基準を起案者 supply 見出しとしてマッピング対象に含める根拠。
  • ADR-0088: コスト試算を起案必須化 (Accepted)。コスト試算見出しも整合対象 (相補的)。
  • ADR-0071: 盲点検出を情報提供型に再定義。本 ADR の § 別集計は Gate 1 の価値可視化につながる。
  • ADR-0076: finding × Must 評価軸の毀損判定。本 ADR の § 整合と組み合わせ「盲点→評価軸→本文 §」の追跡に近づく (相補的)。
  • canonical-structure 草案 (未 Accepted / KV adr-canonical-structure-cost-scope-sections): 実装スコープを第一級化。Accepted されれば 実装スコープ → ## 決定 配下 を追加。Rejected / 大幅修正なら本マッピングは現行のまま維持し追加しない。両 ADR の審議は時間的に分離し、canonical-structure の評価に本 ADR の採択状況を参照させない (確証バイアス回避 / 盲点 #13)。
  • 別 ADR (将来): (B) 中間出力保存 (2 パス化、因果効果の厳密検証) / (e) 横断分析基盤 / (f) 3 ドキュメント整合 CI。
• 関連 operator_guide: §4.1 / §4.3.1 (「起案者は生テキストだけ」を最上位見出しの範囲で一部緩める) / §227。
• 関連コード: body_generation.ts:170 (単一パス上書き箇所)。
• 関連 PR/Issue: PR #1239 (本 ADR)。
• 外部資料: 電子帳簿保存法 2024 年改正 / 中小企業会計指針 2023 年版 (R6 監査要件調査用)。