ADR-0107: ADR 群を「探して再利用できる情報資産」にする

• Status: Accepted (PR merge = 受理の規約により 2026-06-11 受理・代表取締役判断)
• Mode: Standard
• Kruchten Type: Existence / Executive
• Scope: platform
• Implementation Status: In Progress (PR #1715 = 抽出器 + adr-index.json + ①索引 INDEX.md + 完全性テスト。残: メタバックフィル・②絞り込み・④RAG 連携)
• 起案者: [email protected] ([email protected])
• 起案日時 (JST): 2026-06-02 23:40
• 承認日時 (JST): 2026-06-11 02:04
• Deciders: [email protected] (単独)

決定の早わかり（Y-statement）

決定を 1 つに圧縮した型。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

• 文脈: 決定の記録（ADR）が 107 本まで増え、「個別の決定」から「探して再利用したい資産」へ期待が上がった。
• 問題: なのに過去の判断を活かせず、同じ検討の繰り返しや過去と矛盾する決定が起きる（＝実害）。
• 問題点と課題（直せる原因 → 発生を止めるためにやること。いずれも「再利用したい」期待から生まれた要求）:
  • 絞り込み不能 → ②種類・状態で絞り込めるようにする。
  • 関係が不可視 → ③関係を図で辿れるようにする。
  • 再利用導線なし → ④AI が読める形で書き出す。
• 前提（この問題空間の外で決まっている与件。回復は本決定が引き受ける）:
  • 索引の陳腐化: 「索引は手作業で更新せず自動生成で実体と一致させる」という規律（ADR-0130）が、ADR の目次について破れている（31/107）。規律の正典は ADR-0130 が所有し、本決定の出力①がその準拠を回復する。
  • 属性情報（メタデータ）の欠落: 索引・絞り込みの信頼性は属性情報の揃い具合に依存する。欠落（Scope 48 本ほか）は自動では直らず、別途の補完作業が要る（今すぐは解決しない問題点）。
• 決定（対応策）: 現状維持・機能ごとに別々の仕組みを 4 つ作る・外部ツール（adr-kit）に任せる、のいずれでもなく、全 ADR から情報を自動で抜き出して 1 つの元データ（adr-index.json）にまとめ、前提の回復（①）と課題②〜④に次の 4 出力で応える。
  • ①索引: 元データから目次ページを自動で作る（規律 ADR-0130 への準拠回復）。
  • ②絞り込み: 目次を種類・状態で並べ替え・絞り込みできるようにする。
  • ③関係図: 決定どうしの置き換え・参照の関係を図に自動で描く。
  • ④再利用: 元データを AI がそのまま読める形で書き出す。
• 目的: 常に最新の索引と、AI への関連決定の自動提示で、過去の判断を毎回活かせるようにする。
• 代償: 情報を抜き出す仕組みの保守が 1 つ増え、属性情報の補完作業が要る。

用語の早わかり（この後の本文で出てくる言葉）

• Mode = 決定の重み。Light／Standard／Critical の 3 段階。
• Kruchten Type = 決定の種類。新要素の新設／横断ルール／技術・プロセス選定。
• Scope = 影響範囲。
• MCDA・WSM・K.O. criterion = 複数の観点に重みを付けて採点し、必須観点で基準点に届かない案は落とす「案の選び方」。
• SSoT = 正となるデータを 1 か所に置く考え方。
• RAG = AI が答える前に関連情報を読み込ませる仕組み。
• Supersede = ある決定が前の決定を置き換えること。
• メタデータ = 各 ADR の冒頭に付く属性情報。種類・状態・影響範囲など。
• バックフィル = 既存分の欠落を後からまとめて補完すること。
• 元データ（adr-index.json） = 全 ADR から自動で抜き出した情報を 1 か所に集めたデータ。本文では「中間データ」とも呼ぶ。

1. コンテキスト

1.1 背景 (Background)

ADR が 107 本 (0000–0106) に達し、「個別の意思決定」から「横断的に検索・再利用したい情報資産」へと性質が変わった。

1.2 現状 (Current State / As-Is)

既存の索引は二系統あるが、どちらも足りない。

• docs/adr/README.md の「既存 ADR 一覧」は手書きの表。31 行しか載らず、実体 107 本に追いついていない。
• _config.json は 107 本を列挙する。だが種類・規模・状態での絞り込みも、関係の可視化もできない。

検索は grep 頼り。adr-kit(ADR-0019)は lint・コード連携が主で、本プロジェクト固有の 4 軸索引は持たない。

1.3 課題 (Problem)

実測で 4 つの痛みがある。うち「索引の陳腐化」は本 ADR の問題空間の外で定義された規律の破れ(前提・ADR-0130)であり、残り 3 つが本 ADR 固有の問題点である。

• 索引の陳腐化(前提 = 規律の破れ): 一覧は 31/107 しか載らず、実体に追いついていない。索引の常時一致は ADR-0130(索引・目次・カタログの手作業更新廃止)が規律として所有する。本 ADR の出力①が、この破れを ADR 索引について回復する。
• 絞り込み不能: 種類・状態(Kruchten Type / Mode / Scope / Status)で絞れず、grep 頼り。
• 関係が不可視: どの決定が何を置き換え・参照したか、人手で辿れない。最多被参照のハブ ADR-0036 は 46 本から参照される。
• 再利用導線なし: 蓄積した判断を、新規起票や Claude の文脈へ機械的に渡せない。

さらにメタデータに欠落がある。Scope は 59/107 のみ(48 本欠落)、Status/Mode は 89/107。これが索引・絞り込みの信頼性を下げている(今すぐは解決しない問題点 = 前提。別途バックフィルで補完する)。

1.4 制約・要件 (Constraints & Requirements)

• 役割分担: scripts/**・.github/workflows/** の実装は main 専属。本 ADR は設計のみ。実装は [cross-workspace] で main へ引き継ぐ。
• 本文不変: Accepted ADR の本文は Immutable。メタデータ後付けは ADR-0031 範疇とし、B_complete_adr_metadata.mjs 経由のみ。
• 既存を壊さない: adr-lint / docs-nav-lint / docs-build を壊さない。
• 既存型を再利用: 自動生成・--check の型を prompt-catalog.mjs(ADR-0106)と揃える。重複実装と独自運用を避ける。
• adr-kit と棲み分け: adr-kit(ADR-0019 で採用済)と機能が重複しない範囲に限る。

1.5 目標 (Goals / To-Be)

ADR 群を、次の 4 機能で「探して再利用できる情報資産」にする。この 4 つ(①索引・②絞り込み・③関係図・④再利用)を、以降の代替案・決定・影響でも同じ名前で通す。

• ①索引: 全 ADR の最新の目次を 1 ページに集約する(規律 ADR-0130 への準拠回復 = 前提作業)。
• ②絞り込み: 種類・規模・状態でフィルタできる。
• ③関係図: 置換・参照の関係を図にする。
• ④再利用: AI が読める形で書き出す。

Non-Goals(やらないこと): 全文検索エンジンの導入、ADR 本文の書き換え、新規メタデータ軸の追加。

2. 判断基準 (Decision Drivers)

ADR-0050 の Q42 9-tag MCDA を適用 (WSM + K.O. criterion / Suhr 1999 CBA〔Choosing By Advantages〕準拠)。

2.1 評価軸

K.O. criterion: Must 軸の score < 3 は不採用。

2.2 評価軸 × 案スコア表

各案を 0-5 で評価。加重和は (Σ score × 係数) / (満点 × Σ 係数) で正規化 (0.0-1.0)。

要は: 4 案を 5 つの観点で採点した結果、採用案（0.95）が他案（0.35〜0.71）を明確に上回った。必須観点（探しやすさ・陳腐化しないこと）を 1 つでも落とすと不採用で、現状維持案はここで脱落している。

採択首位 = 単一抽出器 → adr-index.json (SSoT) → 4 出力。

3. 検討した代替案 (Considered Options)

判断の軸は「4 出力(①索引・②絞り込み・③関係図・④再利用)を食い違いなく賄えるか」。各案を一行で見る。

• 案 A(採用): 抽出器 1 つ → adr-index.json(SSoT)→ 4 出力
  • Good, because 元データ(中間データ)が 1 つなので 4 出力が食い違わず、prompt-catalog.mjs(ADR-0106)の型を再利用できる。
  • Bad, because 抽出器の保守が 1 つ増え、メタデータ欠落 48 本のバックフィルが要る。
• 案 B(X1): 現状維持(README §15 手書き表)
  • Good, because 追加作業がゼロ。
  • Bad, because 31/107 の陳腐化が続き、②絞り込みと③関係図ができない(Must 2 軸で K.O.)。
• 案 C(X2): 出力別に独立スクリプト 4 本
  • Good, because 各出力を個別に最適化できる。
  • Bad, because 解析が 4 重化し、出力間で索引内容がドリフトする(#maintainable=2)。
• 案 D(X3): adr-kit に全面委譲
  • Good, because 自前実装が不要で外部メンテに乗れる。
  • Bad, because 固有の 4 軸(Kruchten/Mode/Scope/Impl)②絞り込みと決定パイプライン連携を表現できない(#suitable=2)。

4. 決定 (Decision Outcome)

採用は 案 A。元データ(中間データ)1 つを SSoT にすれば 4 出力が食い違わず、実証済みの自動カタログ型(ADR-0106)をそのまま転用できる。

土台は 1 つの抽出器。抽出器 SSoT: scripts/adr-index.mjs(main 実装)が docs/adr/*.md を 1 パス走査し、frontmatter(Status/Mode/Kruchten/Scope/Impl/起案日)・相互参照(ADR-NNNN)・Supersede 関係を adr-index.json に構造化する。手書き禁止。--check で CI 整合を確認する。

ここから §1.5 と同じ 4 出力を作る。

• ①索引: adr-index.json から docs/adr/INDEX.md を自動生成する。README §15 の手書き表はカタログへのポインタにする(ADR-0130 の規律への準拠回復・適用 2 号)。
• ②絞り込み: docs-build がカタログに Kruchten/Mode/Scope/Status 列のソート・絞り込みを付ける(静的サイトのクライアントサイド)。
• ③関係図: Supersede 鎖・被参照を mermaid で可視化する。孤立 ADR・メタデータ欠落 ADR は警告リストに出す。
• ④再利用: adr-index.json を機械可読エクスポートにする。決定パイプライン(ADR-0019 triage)が新規起票時に関連 ADR を自動提示する文脈ソースにする。

前提として、検索の信頼性のため Scope 欠落 48 本等を B_complete_adr_metadata.mjs でバックフィルする(ADR-0031 メタデータ後付け範疇)。役割は設計(本 ADR)= sub、実装(scripts・CI)= main で、[cross-workspace] でハンドオフする。

5. 影響 (Consequences)

5.1 正の影響 (Good)

4 出力がそのまま効く。

• ①索引・②絞り込み: 探す入口が 1 枚に集約され、107 本を種類・規模・状態で横断把握できる。
• ③関係図: Supersede 鎖・被参照が見え、新 ADR 起票時の重複・矛盾を検知しやすくなる。
• ④再利用: 蓄積判断が機械可読資産になり、決定パイプライン・Claude が再利用できる。

5.2 負の影響 (Bad)

• 抽出器スクリプトの保守対象が 1 つ増える。
• 索引品質がメタデータ網羅率に依存し、バックフィルを怠ると絞り込みが不完全なまま固定する。
• 設計 (sub) と実装 (main) の分業でリードタイムが発生する。

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

• adr-kit との機能線引き (lint・コード連携は adr-kit / 4 軸索引・グラフは自前) を継続的に維持する必要がある。
• INDEX.md 自動生成により README §15 の手書き運用は廃止する (監査証跡は git 履歴に残る)。

コスト試算 (Cost Estimate)

• 初期 (AI 支援あり): 抽出器 + JSON 3h / カタログ + グラフ ~2h / メタデータ 48 本バックフィル ~2h / RAG 連携 ~2h = 計 **9h**。
• 初期 (手作業換算・参考): 上記 1.5 倍の **14h**。
• 継続: 新規 ADR 追加時の再生成 ~1min (CI)、メタデータ更新は起票時に frontmatter へ記入するのみ。
• 削減効果: 107 本の横断把握・絞り込みの認知コスト削減、README §15 手書き更新 (恒久的に乖離する手作業) の廃止。

6. 撤退条件 (Rollback Plan)

• 再評価トリガー: 抽出器の保守コストが月 30min を超える、または adr-kit が 4 軸索引・グラフを標準提供する。
• 判定タイミング: 3 ヶ月後 (2026-09-02)。
• 判定主体: 代表取締役。
• ロールバック手順: (A) adr-index --check を CI から外し手動運用へ格下げ (5min) → (B) 自動生成を廃止し INDEX.md を静的化 (30min)。adr-index.json とバックフィル済みメタデータは残置。

Confirmation (準拠確認 / Fitness Function)

本 ADR は Proposed / Implementation Status = Not Started のため、以下は main の実装後に有効化する (Standard Mode のため N/A 不可、実装予定の検証手段を記述)。

• 検証手段: node scripts/adr-index.mjs --check (カタログ・JSON が最新か) + node scripts/docs-nav-lint.mjs (新規 ADR の nav 整合)。
• 実行頻度: PR ごと (CI)。
• 違反時の対応: --check 不一致なら再生成してコミット (自動 fail)。月次でメタデータ欠落 ADR (4 軸のいずれか未記入) が閾値未満であることを確認。

7. 参照 (References)

7.1 プロジェクト内参照

• 関連 ADR: ADR-0130 (索引・目次・カタログの手作業更新廃止規律 — 前提の行き先。出力①はその適用 2 号) / ADR-0106 / ADR-0042 (プロンプト自動カタログの同型先例) / ADR-0019 (adr-kit・決定パイプライン) / ADR-0030 (Kruchten Type) / ADR-0032 (Implementation Status) / ADR-0049 (Scope 4 層) / ADR-0050 (Q42 MCDA) / ADR-0031 (メタデータ後付け範疇) / ADR-0036 (Confirmation 必須) / ADR-0055 (nav 形式)
• 関連 PR/Issue: (未着手)
• 既存 doc: scripts/prompt-catalog.mjs / scripts/B_complete_adr_metadata.mjs / scripts/adr-lint.mjs / docs/adr/README.md (§15 既存 ADR 一覧)

7.2 設計根拠 (Theoretical Foundation)

• Nygard (2011) — Documenting Architecture Decisions
• MADR 4.0 (Markdown Architectural Decision Records): adr.github.io/madr
• Kruchten et al. (2006) — "Building Up and Reasoning About Architectural Knowledge". DOI: 10.1007/11921998_8
• Suhr, The Choosing By Advantages Decisionmaking System, Quorum Books, 1999 (ISBN: 1-56720-217-9)