← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:32
commonid: adr-0130type: adrstatus: accepted
pagemode: Standardkruchten: Executive/Propertyscope: platformimplementation_status: In Progressproposed_at: 2026-06-10 19:49approved_at: 2026-06-21deciders: [email protected] (単独)business: meta
型付き辺: 出 12 / 入 3
関連: ADR-0144 ADR-0142 ADR-0031 ADR-0042 ADR-0107 ADR-0133 ADR-0019 ADR-0131 ADR-0134 ADR-0106 ADR-0140 ADR-0141 細分化された: ADR-0107 ADR-0145 宿題回答された: ADR-0132全体は INDEX →

ADR-0130: 索引・目次・カタログの手作業更新を廃止し、自動生成で維持する — 文書運用の横断規律

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Executive/Property
  • Scope: platform
  • Implementation Status: In Progress
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-06-10 19:49
  • 承認日時 (JST): 2026-06-21
  • Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

docs サイトには、人が考えて書く本文のほかに、索引・目次・カタログ・一覧表など、実体から機械的に作れるページが増えている(関係図や AI 向けの書き出しも同じ仲間。多くは文書についての情報 = メタ情報の集まり)。これらを人が手作業で更新してきた一覧が実体とずれ、探せない・信頼できない状態が顕在化している。

§1.2 現状 (As-Is)

ずれの証拠は 2 つある。

  • 実例 1: docs/adr/README.md §15 の「既存 ADR 一覧」(人が手で編集してきた Markdown の表)は 31 本分で更新が止まり、実体は 107 本ある(生成の仕組みなし → ずれ放置)。
  • 実例 2: プロンプト管理は ADR-0106 で自動生成の仕組み(prompt-catalog)を導入したが、Confirmation が約束した CI 強制(PR ごと --check)が未配線のままで、2026-06-10 の実査時点で --check が FAIL していた(生成の仕組みがあっても CI 強制がないと再びずれることの実査済み実証)。同日、ADR-0106 Confirmation の履行として CI 配線を実施し解消済み(PR #1671 merged・本番稼働)。

§1.3 課題

これらのページを人の手作業・手動運用で実体に同期させる仕組みになっていること。手作業の同期は実体が増えるほど追従できず構造的に破綻し(実例 1)、生成の仕組みを導入しても手動実行頼みでは同じ破綻が再発する(実例 2)。手作業同期への依存をなくす必要がある。

§1.4 制約・要件

  • 規律の構成要素は 3 点セット(どれか欠けると破綻する):生成器の導入 / CI による一致強制(--check を PR ごと実行)/ 走査範囲の明文化。
  • 対象判定基準は「そのページの内容を、他の場所に既にある情報だけから機械的に作り直せるか」のみ。ADR 本文・設計書・手順書は対象外。
  • 適用範囲は場所(ディレクトリ)では定めない。判定基準を満たすページすべてが対象。
  • 既存の CI 基盤 (adr-lint.yml)・ADR-0019 lint 体系に乗ること(新規 CI 基盤を作らない)。
  • 個別適用決定(走査パス・除外)は本規律では決めず、対象ページごとの個別 ADR・案件に送る。

§1.5 目標 (To-Be)

索引・目次類が、人の注意力に依存せず常に実体と一致している状態。Non-Goals: ADR 本文・設計書など人の判断を含む文書の自動生成は対象外。個別のページの走査パス決定も対象外(個別 ADR に送る)。

決定

索引・目次・カタログなど、実体から機械的に作れるページの手作業更新を廃止する。 代わりに、実体から自動で作る生成器を導入し、実体との一致は CI(--check)が PR ごとに機械的に確認する。本規律は「維持の方式」(3 点セット = 生成器 + CI 強制 + 走査範囲の明文化)と「走査範囲を決めて明文化する義務」までを定め、個別ページの走査パス・除外は対象ページごとの個別決定とする。新設は受理日から即時適用(手作業更新前提の新設は不可)、既存は受理から 1 ヶ月以内に棚卸し → 6 ヶ月後の判定タイミングまでに「生成器化案件起票 / 例外指定」のいずれかに振り分ける。

判断基準 (Decision Drivers)

3.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#reliable[Must] (×2.0)索引・カタログと実体の一致が、人の注意力に依存せず構造的に保証されるか
2#maintainable[High] (×1.0)対象ページが増えても保守が破綻しないか(1 系統あたり月 30min 未満)
3#operable[High] (×1.0)既存 CI(adr-lint.yml / --check)に乗り、新規基盤を増やさないか
4#suitable[Medium] (×0.5)後続 ADR(索引・カタログ系)が「規律の正典」として参照できるか
5#efficient[Medium] (×0.5)規律導入のコストが手作業同期の恒久工数を下回るか

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

3.2 評価軸 × 案スコア表

各案 0-5 で評価。加重和 = (Σ score × 係数) / (満点 × Σ 係数)。満点 = 5、Σ係数 = 2.0+1.0+1.0+0.5+0.5 = 5.0。

軸係数採択案(横断規律)案 X1(現状維持)案 X2(定期棚卸し)案 X3(個別判断のみ)案 X4(ADR-0106 完遂のみ)
#reliable×2.051233
#maintainable×1.041233
#operable×1.053334
#suitable×0.551122
#efficient×0.542133
加重和 (正規化)0.9400.3000.3800.5800.620
K.O. 通過 (Must ≥3)✓❌❌✓✓

検討した代替案 (Alternatives Considered)

  • 案 X1 現状維持(手作業更新のまま注意喚起): 人の注意力頼みで再発防止にならない。31/107 が反証 — Must 軸不通過。
  • 案 X2 定期棚卸し(四半期ごと手作業同期): 対症療法。棚卸し間隔の分だけ常にずれる。工数も恒久発生 — Must 軸不通過。
  • 案 X3 ページごと個別判断(横断規律なし): ADR-0106 のような個別解決は出るが、新設の手作業一覧を止められない — 加重和で劣後。
  • 案 X4 ADR-0106 の CI 配線完遂のみ・新規律なし: prompt-catalog のずれは直るが、(a) ADR 索引(README §15)等他の対象ページに効かない、(b) 手作業一覧の新設を止める禁止則を持たない、(c) 横断規律の正典として後続 ADR から参照できない。必要だが不十分 — 本規律は X4 を前提作業として包含し横展開する。

影響 (Consequences)

§5.1 正の影響 (Good)

  • 索引類のずれが構造的に消える。
  • 手作業同期の恒久工数と、古い一覧で探し損ねるコスト(README §15 で実証済み)を排除。
  • 後続 ADR(索引・カタログ系、ADR-0107 等)が本規律を行き先として参照できる。

§5.2 負の影響 (Bad)

  • 対象ページを新設するハードルが上がる(生成器とセットが条件)。
  • 生成器の保守対象が増える(1 系統あたり月 30min 未満・撤退条件で監視)。
  • 盲点リスク群(Gate 1 検出、影響範囲として明記):
    • 手作業新設の禁止が PR レビュー観点のみに依存する構造リスク (high): §6.5 Confirmation でファイル名パターンの lint 自動検査(ADR-0019 への追加可否を含む)を機械ゲートとして明記し、人の注意力依存を排除する(後述)。
    • 走査ルート固定による無音欠損 (critical): --check は「生成結果と出力ファイルの一致」しか見ず、走査ルート定義の縮小・ディレクトリ移動を検知できない(prompt-catalog 実測で走査外 225 本)。→ §6.5 Confirmation で「走査対象ファイル数が前回比 X% 以上減少したら FAIL」閾値チェックを各生成器の必須要件として個別適用に義務付ける。
    • 棚卸しリスト自体が手作業管理物化する自己矛盾 (high): 棚卸しリスト自身を本規律の適用対象に含め、CI でリストと実ファイルの一致を検査する(§6.5)。
    • 保守コスト総量の積み上げ盲点 (high): 個別系統が 29min に収まりつつ全系統合計で肥大化するシナリオを撤退条件で検知できない。→ §6 撤退条件に総量閾値を追加。
    • tasks/prompts/ 215 本の解消期限不在 (medium): 「個別 ADR に送る」だけでは ADR-0106 と同じ放置パターンが再発。→ §6.5 Confirmation で受理から 1 ヶ月以内の起票義務を明記。
    • 見積もり 2〜3h の根拠不足 (medium): 複雑ページ(複数ソース結合・外部依存あり)で 8〜20h 要する事例あり。棚卸しで難易度別分類を行い、難易度別コスト上限を個別 ADR に明記。
    • CI 常時緑の確証バイアス (medium): 生成器対象外の本文ページの陳腐化・リンク切れに対する人のレビュー圧力低下。→ 本文ページの定期レビュー(四半期・担当者明記)を CI 緑とは独立して実施することを明記。

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

  • 既存の手作業ページは 2 段階の移行手順(1 ヶ月で棚卸し → 6 ヶ月で振り分け)で漸進移行。
  • 本規律は「維持の方式」と「走査範囲明文化義務」までを定め、個別の走査パス・除外決定は個別 ADR に送る分離設計。塊の境界が明確な反面、個別 ADR 起票の運用負荷が増える。

撤退条件 (Rollback Plan)

  • 再評価トリガー:
    • (a) 生成器の保守コストが月 30min を超える系統が 2 つ以上になった場合。
    • (b) 生成器整備コストが手作業更新 3 年分を超える見込みのページが現れた場合。
    • (c) 【追加】全系統合計の月次保守工数が 3h を超えた場合(各系統が 29min に収まりつつ総量で肥大化するシナリオの検知用)。
  • 対応: 当該ページを例外リストに指定(規律全体の撤回ではなく例外運用)。
  • 判定タイミング: 受理から 6 ヶ月後(2026-12 想定)。既存ページの振り分け完了の確認と兼ねる。系統数と総工数の両方を代表取締役が確認する。
  • 判定主体: 代表取締役。
  • ロールバック手順: 例外リストへの追記のみ(~10min)。既存生成器は残置。

コスト試算

  • 初期: 規律宣言(本 ADR)のみで実装ゼロ。レビュー観点・lint への追加(main 領分) ~2h。既存ページの棚卸し(受理から 1 ヶ月以内) ~1h。
  • 個別適用: 生成器の整備は 1 系統あたり ~2〜3h(ADR-0106 実績・ADR-0107 見積もり〔抽出器 + JSON ~3h〕が根拠)。走査範囲・意図的除外の注記は ~0.5h 未満(生成器整備に含む)。個別 ADR・案件で計上し、本 ADR には含めない。複雑ページ(複数ソース結合・外部依存あり)では 8〜20h を要する事例あり(Backstage TechDocs / Docusaurus custom plugin 報告)→ 棚卸しで難易度別分類を行い、難易度別コスト上限を個別 ADR に明記する。
  • 継続: 既存 CI(--check)に乗るため追加ランニング 0h。生成器保守は 1 系統あたり月 30min 未満(超過は例外化)。全系統合計 3h/月を撤退条件閾値とする。月 30min の根拠は ADR-0106 の保守実測(prompt_catalog.md の git 履歴: 2026-06-02 導入から 8 日間で運用コミット 7 件〔初回整備 2 件含む〕・1 件あたり数分の再生成作業)を月換算した参考値。受理後は各系統の保守実測を git 履歴ベースで記録し、判定タイミング(受理 6 ヶ月後)に 30min/系統・3h/月の両閾値の妥当性を実測で検証・必要なら改定する。
  • 削減効果: 手作業同期の恒久工数(README §15 相当の更新作業)と、ずれ由来の検索コストを構造的に排除。

Confirmation

  • 検証手段:
    1. 既存 --check 系(prompt-catalog、ADR-0107 実装後は adr-index)の CI 通過。
    2. 手作業新設の機械ゲート: 新規 Markdown が索引・目次・カタログ相当のファイル名パターン(*-catalog.md / *-index.md / README.md §一覧 等)で追加された際、生成器の有無を lint で自動検査(ADR-0019 lint 体系への追加可否を本 ADR 受理後 1 ヶ月以内に判定)。レビュー観点ではなく機械ゲートで担保する。
    3. 走査範囲縮小の閾値検査: 各生成器は「走査対象ファイル数が前回比 X% 以上減少したら CI を FAIL させる」閾値チェックを必須要件として持つ(個別適用 ADR で X を決定)。
    4. 棚卸しリスト自体の自動検査: 棚卸しリストを本規律の適用対象に含め、CI でリストと実ファイルの一致を検査する。
    5. 走査範囲・意図的除外の注記レビュー: 各対象ページに走査範囲(in-scope path)と意図的除外(out-of-scope + 理由)の注記があることをレビュー観点に含める。
    6. tasks/prompts/ 215 本の解消起票義務: 本 ADR 受理から 1 ヶ月以内に ADR-0042/0106 系で扱いを決定する個別 ADR を起票する。期限超過は撤退条件の追加トリガーとする。
    7. 本文ページの独立レビュー: 生成器対象外の本文ページの陳腐化・リンク切れ防止のため、四半期ごとに担当者を明記した定期レビューを CI 緑とは独立して実施。
  • 実行頻度: PR ごと(CI)/ 四半期(本文レビュー)/ 受理 6 ヶ月後(判定タイミング)。
  • 違反時対応:
    • --check 不一致 → 再生成コミット。
    • 手作業新設の検出時 → 生成器整備の案件化を要求(該当 PR ブロック)。
    • 走査範囲縮小閾値超過 → CI FAIL、走査ルート定義の更新 PR を要求。
    • 判定タイミングで振り分け未完了ページが残存 → 移行計画の案件化と代表取締役判定。
  • 移行完了確認: 判定タイミング(受理 6 ヶ月後)に、棚卸しリストの全ページが「生成器化済み / 案件起票済み / 例外指定」のいずれかに振り分けられていること、および系統数・全系統合計の月次保守工数を代表取締役が確認する。

参照 (References)

  • 関連 ADR:
    • ADR-0106(prompt カタログ): 本規律の実装雛形。生成器導入済み + CI 配線完遂済み(PR #1671・2026-06-10。それまで未配線で --check FAIL していた実装ギャップを Confirmation 履行として解消)+ 意図的除外の注記あり。3 点セットの実証例(案 X4 参照・本規律はその横展開)。
    • ADR-0107(Proposed): 出力①(ADR 索引の自動生成)が本規律の適用 2 号。受理後、ADR-0107 の前提が本 ADR を規律の正典として参照する予定。
    • ADR-0019(adr-kit・lint 体系): 本規律の CI 強制および手作業新設の機械ゲート lint は同体系に乗る。準拠。
    • ADR-0031(メタデータ後付け範疇): 対象ページの元になる frontmatter 整備と整合。準拠。
    • ADR-0042(プロンプト管理 Type 体系): prompt-catalog の意図的除外(prompts/production/** = Type 1 SSoT)の根拠。tasks/prompts/ の未決定の穴の解消先。
  • 関連 PR/Issue: PR #1671(ADR-0106 CI 配線完遂・2026-06-10 merged)
  • 外部資料:
    • 構造 doc docs/_internal/05_how-to/adr_structure_pyramid_principle.md D-1: スコープ的与件の「行き先」として本 ADR が機能する。
    • Google SRE Book Chapter 5(マイクロサービスの運用オーバーヘッド・小さなコストの積み重ね)— 撤退条件の総量閾値追加根拠。