ADR-0114: docs システム概要ページの冒頭規約（基本情報+エレベーターピッチ）

• Status: Accepted
• Mode: Standard
• Kruchten Type: Property/Executive
• Scope: platform
• Implementation Status: Partial — 棚卸し issue テンプレ整備済 (.github/ISSUE_TEMPLATE/tier-inventory.md, 2026-06-18). cron 自動起票・会計 2 本 (corporate-tax, project-accounting) の Tier A 適用 (税理士見解待ち) は別タスク
• 起案者: t_saitoh
• 起案日時 (JST): 2026-06-04 19:16
• 承認日時 (JST): 2026-06-04 (PR #1414 merge = 受理)
• Deciders: t_saitoh (単独)

コンテキスト

§1.1 背景

docs サイトの「意思決定 審査パイプライン」README の冒頭構造（§1 基本情報 = 英語名・状態・本番 URL・コード位置・基盤決定 ADR・変更履歴のファクトボックス、§2 エレベーターピッチ = 問いラベル 5 行の業界用語なし要約）が、新規読者の理解導入として機能している。これを他のシステム概要ページにも展開できるよう規約化したい。

§1.2 現状 (As-Is)

• エレベーターピッチは writing-guide §3.6 に規約済だが、適用範囲が「ADR Standard/Critical + 主要ページ」と曖昧で「主要ページ」の定義がない。準拠ページは 2 ページのみ。
• 基本情報（ファクトボックス型）は未規約化。準拠は decision_pipeline/README.md の 1 ページのみ。
• 名前衝突: ## 1. 基本情報 という見出しは spec 系 14 ページ（spec_rpa_*.md 等）で全く別の構造（関数名・入出力テーブル、guidelines_spec_template.md 準拠）として既に使用されている。

§1.3 課題

「主要ページ」の定義不在によりページごとに構造がばらつき、新規読者の理解導入機能が DRP README 以外に展開されていない。spec 系 14 ページとの見出し名衝突を回避しつつ、ファクトボックス + ピッチ規約を確立する必要がある。

§1.4 制約・要件

• 関連 ADR との整合: ADR-0105（用語 Tier・初出グロス）を Refine（§3.6 ピッチ規約の「主要ページ」を Tier 定義で明確化し、基本情報ファクトボックスを新規追加）。Supersede ではない。ADR-0039（arc42+C4+MADR+feature-folder）/ ADR-0045（_internal 配置）/ ADR-0070（nav title）/ ADR-0023（ADR 構造）と整合・Conflict なし。
• spec 系テンプレート（guidelines_spec_template.md）はリネーム・変更しない（共存）。
• 適用対象は docs/ 配下中心。scripts/ への追加（docs-lint staleness 検出 + 引用ブロックスモークテスト）は sub では読み取り専用のため main 領分への実装依頼または [cross-workspace] PR とする。
• GAS コード・データモデル・業務フロー・外部 I/F への変更なし。

§1.5 目標 (To-Be)

writing-guide.md にシステム概要ページ固有ルールを追加し、Tier A 必須 7 ページの冒頭を §1 基本情報（Enum 状態フィールド含む）+ §2 エレベーターピッチで統一する。Non-Goals: README 未作成 5 ドメイン（bank-reconciliation / budget-actual / cash-flow / master-data / monthly-close）の新設は本規約と切り離し DOC-OPS バックログの別タスク。spec 系 14 ページの「基本情報」見出しのリネームは対象外。

決定

本 ADR の決定は 2 層で構成する。核心決定（変更には ADR 改訂が必要）= §1§2 形式の lock、Tier A 必須 7 ページ、Tier 判定基準、Tier B 禁止条項（盲点 2 を受け実施細則から核心へ移管）、Tier A 上限ページ数 10 ページ以下（盲点 4）、product_overview.md を含めるための Tier A 判定基準 (a) 改訂（盲点 4）、層境界の判定基準。実施細則（writing-guide に委任、ADR 改訂なしで調整可）= 状態 Enum 更新トリガーの詳細、staleness 検知の閾値、棚卸しサイクル運用、検証手順詳細。writing-guide 側で調整可能な範囲は「Tier B 禁止条項の緩和は不可・強化のみ可」と明示制限する。

具体実装:

1. writing-guide.md に新セクション「システム概要ページ（README / landing）固有ルール」を追加し、DRP README §1-§2 を正規形として lock する。

   • 基本情報: 引用ブロック形式。必須 4 項目（状態 / コード / 基盤決定 / 変更履歴）+ 任意 3 項目（英語名 / 本番 URL / ドメインオーナー = 状態フィールド更新の責任者）
   • 「状態」フィールドの値は Enum で固定: Planned / Development / Production / Deprecated / Archived の 5 値。更新トリガーは本番リリース・非推奨化・退役・アーカイブの各イベント時（変更を入れた PR と同一 PR で更新）+ 半年毎の Tier 棚卸し時に検認。
   • 状態フィールドの自動 staleness 検知: docs-lint に「状態 = Production かつ変更履歴の最終日付が 6 ヶ月以上前のページに警告を出す」ルールを追加し CI 実行毎に機械検知。イベント駆動（一次）+ CI 警告（自動検知の網）+ 半年棚卸し（検認）の 3 段で防ぐ。
   • 半年毎の Tier 棚卸しは担当者明記の issue テンプレート（DOC-OPS バックログ行きチェックリスト）から起票し、カレンダー登録と組で実施漏れを防ぐ。
   • エレベーターピッチ: 既存 §3.6 の 5 行形式を参照。基本情報 → ピッチの順で §1 §2 固定。
   • 規約セクションに免責文言を明記: 「冒頭ブロック（基本情報・エレベーターピッチ）は内部開発ドキュメントの理解導入であり、監査証跡・法令対応の正式記述ではない」。
   • 会計業務ドメイン（corporate-tax / project-accounting）の README では、ファクトボックス直下に 1 行注記をテンプレートとして必須化: 「※本ブロックは開発理解導入用であり、法務・監査対応の正式記録ではない（正式記録は該当の運用文書を参照）」。盲点 1 を受け、これらドメインを Tier A 対象とする前提条件として、顧問税理士または法務担当者から「ファクトボックスが電帳法・会計指針上の記録文書に該当しない」旨の見解を取得し ADR に附記する。見解未取得段階では当該 2 ドメインの Tier A 適用を保留し、見解取得後に正式に Tier A へ組み込む。見解取得が困難な場合は、変更履歴フィールドをこれらドメインの README から除外するか別ファイルに分離する設計変更を行う。

2. 適用範囲を 3 Tier で確定し、Tier 判定基準も明文化する:

   • Tier A 必須（7 ページ、上限 10 ページ以下）: decision_pipeline/README.md（準拠済・模範）、domains//README.md 既存 5 本（corporate-tax / data-ingest / order-management / project-accounting / rpa-automation）、architecture/product_overview.md。
   • Tier A 判定基準（盲点 4 を受け改訂）: (a) 単一のシステム・パイプライン・機能ドメインの全体像を説明する landing または複数ドメインをまたぐ製品全体 landing である、(b) 対応する実装（コード位置）が存在する、の両方を満たすページ。product_overview.md は改訂後の (a) 後段により正規に該当（「例外」扱い廃止）。
   • Tier A 上限: 10 ページ以下を核心決定として明記。新規ページ作成 PR レビュー時にレビュアーが Tier 判定をコメントで明示し、Tier A 該当なら同 PR で writing-guide の Tier リストを更新する。
   • Tier B ピッチのみ任意（完全リスト 15 ページ）: docs/README.md、adr/README.md、architecture/README.md、data/README.md、data/data-definitions/README.md、data/master-definitions/README.md、domains/README.md、domains/_shared/README.md、implementation/README.md、implementation/legacy-dev/README.md、operations/README.md、operations/itgc/README.md、operations/testing/README.md、_internal/01_discovery/research_prompts/README.md、_internal/biz/README.md。
   • Tier B 運用禁止条項（核心決定に格上げ）: レビュアーは Tier B ページのピッチ不在を理由に差し戻してはならない。writing-guide 側での緩和は不可・強化のみ可。緩和を要する場合は ADR 改訂を必須とする。
   • Tier C 適用外: spec_*.md（別構造の基本情報を維持）、データ定義リファレンス本体、ADR 本体、RQ 調査結果（TL;DR grandfather 維持）、index.md / SUMMARY.md、_meta / _nav。

3. spec 系の ## 1. 基本情報（関数仕様テーブル）はリネームせず、別ドキュメント種別の規約として共存させる。規約に「spec 型基本情報は別物（guidelines_spec_template.md 準拠）」と 1 行明記して切り分ける。

4. README 未作成の 5 ドメイン（bank-reconciliation / budget-actual / cash-flow / master-data / monthly-close）への新設は本規約と切り離し、DOC-OPS バックログの別タスクとする。

5. 引用ブロック形式の機械検証を 2 段で行う:

   • 導入前に 1 回: 現行の docs ビルド（scripts/docs-build.mjs）で、引用ブロック内の全角スペース・コロン縦揃え・リンクが警告なくレンダリングされることを Tier A 1 ページのサンプルで確認してから残り 6 ページへ展開。
   • 継続的に: docs ビルドの CI 工程に「Tier A ページの引用ブロック必須 4 項目がレンダリング済み HTML に存在するか」をアサートするスモークテストを追加。
   • 盲点 5 を受け、docs-lint と docs ビルドの現在の実行環境（GitHub Actions runner / Cloudflare Workers / その他）を main 領分の実装依頼時に確認し ADR に附記する。Workers 上で動作する場合または移行計画がある場合は、staleness 検出と引用ブロックスモークテストの実装方式を Workers 制約（CPU/wall time 上限・subrequest 上限・git コマンド不可）に対応した設計（例: KV ストアへのメタデータキャッシュ・ビルド時に別スクリプトで事前抽出）に変更し、工数を 0.25 人日から再試算する。

判断基準 (Decision Drivers)

3.1 評価軸

K.O. criterion: Must 軸（#maintainable, #usable）の score < 3 は不採用。

3.2 評価軸 × 案スコア表

採択案と案 d はともに K.O. 通過。加重和で採択案（0.800）> 案 d（0.764）。模範例（DRP README）と規約の順序を一致させ移行コストが低い点で採択案を選定。

検討した代替案 (Alternatives Considered)

• 案 a: spec 系 14 ページの「基本情報」をリネームして衝突解消 — 却下。spec は B2→B3→B5 生成パイプラインの出力形式でもあり、テンプレート・生成スクリプト・既存 14 ページへの波及が大きい割に、ドキュメント種別が違えば同名見出しでも実害がない。
• 案 b: 規約化せず都度判断 — 却下。「主要ページ」の曖昧さが残り続け、ページごとに構造がばらつく現状が解消されない。
• 案 c: 全 README に基本情報+ピッチを義務化 — 却下。ナビゲーション目的の TOC ページ（index/SUMMARY/ディレクトリ landing）にファクトボックスを置いても埋める内容がなく形骸化する。
• 案 d: ピッチ先頭・ファクトボックス後置の順序 — 却下。DRP README の実績（§1 基本情報 → §2 ピッチ）で理解導入機能が確認できており、模範例と規約の順序を一致させる方が移行コストが低い。単一事例由来である点は認識しており、Confirmation のウォークスルーで §1→§2 / §2→§1 の 2 パターンを異なるドメインで比較して実証データを残す。将来 RAG 活用や静的サイト SEO 要件が変化した際の見直し材料として記録する。

影響 (Consequences)

§5.1 正の影響 (Good)

• Tier A 7 ページの冒頭が統一され、新規読者・対象ドメイン未経験者の理解導入機能が DRP README 以外にも展開される。
• 状態フィールドの陳腐化を 3 段（イベント駆動 / CI staleness 警告 / 半年棚卸し）で防ぐ設計により、人手運用への単一依存を解消。
• Tier 判定基準・判定プロセス・上限ページ数の明文化により、新規ページ追加時の例外申請膨張を構造的に抑制。
• Tier B 禁止条項を核心決定に格上げしたことで、レビュー作法の解釈分裂による差し戻し増加を ADR 改訂レベルの拘束力で防止。

§5.2 負の影響 (Bad)

• 初期 2.0 人日 + 維持年 0.5 人日 + 突発 0.5 人日/件 = 5 年 TCO 5.0 人日のコストが発生（LLM コスト約 $2/ADR 投入分含む）。
• 主対象は docs/ 配下（writing-guide.md への規約追記 + Tier A 7 ページの冒頭拡充、sub 編集可能範囲内）。付随して scripts/ への追加（docs-lint staleness 検出 + 引用ブロックスモークテスト）は sub では読み取り専用のため main 領分への実装依頼または [cross-workspace] PR が必要。
• 会計ドメイン 2 本（corporate-tax / project-accounting）の Tier A 適用は法務・税務見解取得待ちで遅延する可能性。見解取得が困難な場合は変更履歴フィールドの除外・別ファイル分離という設計変更が発生。
• docs-lint の実行環境が Cloudflare Workers である場合、staleness 検出の実装方式が根本的に変わり、main 領分 0.25 人日試算が過小評価になるリスク（盲点 5）。

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

• 2 層構造（核心 / 実施細則）は ADR の拘束力と運用柔軟性のトレードオフ。禁止条項の核心格上げで拘束力側に寄せたが、staleness 閾値・棚卸し運用詳細は writing-guide 委任のまま。
• 順序を §1 基本情報 → §2 ピッチで lock したことは DRP README 単一事例に依存する判断であり、Confirmation のウォークスルー結果を将来の見直し材料として記録。
• ステークホルダー: t_saitoh（起案者・docs オーナー・撤退判定権者）/ main 領分実装者（docs-lint staleness 検出 + スモークテストの実装担当）/ PR レビュアー（Tier 判定コメント・Tier B 禁止条項の遵守者）/ 顧問税理士または法務担当者（会計ドメイン 2 本の電帳法見解提供。Tier A 組み込みの前提条件）。
• GAS コード・データモデル・業務フロー・外部 I/F への変更なし。

撤退条件 (Rollback Plan)

• 撤退判定権者: t_saitoh（起案者兼 docs オーナー）。2 ヶ月時点（2026-08 月末）に判定 issue を起票し明示的に判定する（sunk cost を理由とした先送り防止）。
• 撤退閾値（盲点 3 を受け強化）: 規約導入後 2 ヶ月（2026-08 月末）時点で Tier A 7 ページのうち準拠が 4 ページ未満に留まる場合、または規約起因のレビュー差し戻しが月 3 件を超える場合、必須を「推奨」に降格する。閾値根拠の類似社内事例は本起案時点で存在しないため、初回判定後の知見を以降の ADR 撤退閾値設計の参照事例とする（メタ運用として記録）。
• 形骸化の追加判定指標: 2 ヶ月時点レビューで「状態」フィールドが実態（本番稼働状況）と不一致のページが 7 ページ中 2 ページ以上あれば降格検討対象（2 ヶ月時点の人手判定。以降の継続検知は CI staleness 警告が担う）。
• Tier B 形骸化指標: 規約導入後 1 年時点で Tier B 15 ページのうちピッチ採用が 3 ページ以下（20% 未満）の場合、禁止条項を維持しつつ Tier B 適用範囲そのものを ADR 改訂で見直す（禁止条項の緩和は writing-guide 単独では不可）。
• revert 手順: writing-guide の該当セクション削除 + 各ページ冒頭の git revert + docs-lint ルールの無効化で 0.5 人日以内に完全復元可能。revert 工数を含めても初期 2.0 人日 + revert 0.5 人日 = 2.5 人日のコスト確定となる点を初期コストとの比較として明示。
• Review After（正式レビュー期日）: 2026-12 月初（採択から半年後）。初回の半年 Tier 棚卸しと同タイミングで、層構造（核心 / 実施細則）の境界・staleness 検知の警告精度・Tier B 採用状況を正式レビューする。

コスト試算

初期導入（合計 2.0 人日）:

main 領分の確定値附記 (2026-06-04 実装時): 実行環境は GitHub Actions (docs-nav-lint workflow に統合) と確定し、試算どおり 0.25 人日 で完了 — Workers 方式への変更・再試算 (0.5〜0.75 人日) は不要。実装: scripts/tier-a-header-lint.mjs (T1 状態 staleness 183 日 = WARN / T2 引用ブロック smoke = FAIL)。T2 は docs-build.mjs に --only 部分ビルドフラグを追加して Tier A 7 ページのみビルド (~5 秒/run、フルビルド ~10 分を CI に載せない)。T1 は checkout fetch-depth: 0 で各ページの最終 commit 日付を取得。適用保留 2 ページ (corporate-tax / project-accounting) は §1 ブロック未展開を info 扱いで skip (税理士見解取得後に自動で検査対象化)。

維持コスト（年間 0.5 人日 / 5 年で 2.5 人日）:

突発コスト（発生時のみ）:

5 年 TCO = 初期 2.0 + 維持 2.5 + 突発 0.5 = 5.0 人日。LLM コスト: 本 ADR の Pipeline 審査 約 $0.5/run × 再投入込み 5 run = 約 $2.5。規約適用作業自体は人手の docs 編集のみで追加 LLM コスト 0 円/月。

実行環境による再見積もりレンジ: docs-lint / docs ビルドが GitHub Actions runner 上で動作する場合は上記試算どおり（main 領分 0.25 人日）。Cloudflare Workers 上で動作する（または移行計画がある）場合は、git コマンド不可・CPU/wall time 上限・subrequest 上限の制約により実装方式の変更（ビルド時の別スクリプト事前抽出・KV メタデータキャッシュ等）が必要となり、main 領分 0.25 人日 → 0.5〜0.75 人日、5 年 TCO は 5.0〜5.5 人日 のレンジとなる。実行環境の確認結果と確定値は main 領分の実装依頼時に本 ADR へ附記する。

Confirmation

• 検証手段:
  1. 規約マージ後 1 ヶ月以内に Tier A 7 ページ全てが §1 基本情報（必須 4 項目・状態は Enum 5 値のいずれか）+ §2 エレベーターピッチ（5 行形式）を冒頭に持つ（準拠率 7/7 = 100%）を adr-lint 派生スクリプトでアサート。
  2. writing-guide に適用範囲 3 Tier（必須 7 ページ / ピッチのみ任意 15 ページ完全リスト / 適用外）+ Tier 判定基準（改訂後 (a) 含む）と判定プロセス + Tier A 上限 10 ページ + Tier B 禁止条項（核心決定明示）+ 免責文言 + 会計注記テンプレートの明文化セクションが存在することを手動 QA で確認。
  3. docs-lint の staleness 検出ルール（状態 = Production かつ変更履歴 6 ヶ月以上前で警告）と引用ブロックスモークテスト（必須 4 項目の HTML 存在アサート）が CI で毎回実行される（main 領分の実装完了をもって確認、実行環境制約の調査結果を ADR に附記）。
  4. 半年棚卸しの issue テンプレートが存在し、初回の棚卸し issue が担当者明記で起票されている。
  5. 会計ドメイン 2 本については、顧問税理士または法務担当者の見解取得完了を Tier A 組み込みの前提とし、見解文書を ADR に附記。
  6. 定性検証: 2 ヶ月時点（撤退判定と同タイミング）で、対象ドメイン未経験の読者 1 名が Tier A サンプル 2 ページの §1 §2 のみを読み、システムの目的・状態・コード位置を 3 分以内に説明できるかウォークスルーで確認。同時に §1→§2 / §2→§1 の 2 パターンを異なるドメインページで比較し、達成率を writing-guide の注記に記録。
• 実行頻度: (1)(2)(3) は CI 実行毎、(4)(5) は導入時 1 回、(6) は 2 ヶ月時点で 1 回。
• 違反時対応: (1)(3) 違反は PR ブロック。(2)(4) 違反は docs オーナーが 1 週間以内に補修 PR を起票。(5) 違反は会計ドメインの Tier A 組み込みを保留。(6) 不達成は writing-guide の記述例を補強し、達成率が著しく低い場合は撤退条件に基づき降格判定。

参照 (References)

• 関連 ADR: ADR-0105 (Refine), ADR-0039, ADR-0045, ADR-0070, ADR-0023
• Refined by ADR-0128: コーポレート社内サイトへの再ポジショニングに伴い、本 ADR の Tier 体系を Refine（核心は温存・Supersede ではない）。新類型 Tier P（ポータル landing） と L0/L1 landing 階層を追加し、SUMMARY.md を Tier C → Tier P へ移した。既存 Tier A 7 ページの拘束は不変。詳細は writing-guide §7.3。
• 関連 PR/Issue: -（DOC-OPS バックログ・初回 Tier 棚卸し issue を導入時に起票）
• 外部資料: guidelines_spec_template.md（spec 系基本情報の準拠先・共存対象）