← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0079type: adrstatus: superseded
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Not Started (実装されず Superseded)proposed_at: 2026-05-27 19:05approved_at: -deciders: [email protected] (単独)business: meta
型付き辺: 出 8 / 入 1
関連: ADR-0090 ADR-0039 ADR-0045 ADR-0046 ADR-0048 ADR-0051 ADR-0055 ADR-0069 置換された: ADR-0128全体は INDEX →

ADR-0079: docs/ を engineering/corporate に再編し Cloudflare Pages サイトを分離

  • Status: Superseded by ADR-0128
  • Mode: Standard
  • Kruchten Type: Existence/Property
  • Scope: platform
  • Implementation Status: Not Started (実装されず Superseded)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-27 19:05
  • 承認日時 (JST): -
  • Deciders: [email protected] (単独)

Superseded 注記 (2026-06-08): 本 ADR（docs を engineering/corporate に分割し Cloudflare Pages サイトを分離）は Proposed / Not Started のまま実装されなかった。実際には単一サイト + Corp/MAS/DRP 事業軸フィルタ（PR #1544）が採られ、その入口 IA・概要ページ Tier 規約を ADR-0128 が定義したため Superseded とする。別サイト分割を再評価すべきトリガーは ADR-0128 に記載（軸数 5 以上、または顧客向けプロダクトの外部公開 docs が必要になった場合）。

1. コンテキスト

1.1 背景 (Background)

docs/ ディレクトリは GAS 実装ドキュメント (dev spec、data 定義、テスト手順) とコーポレート知識基盤 (ADR、RQ research、意思決定パイプライン、ITGC) を単一階層に蓄積してきた結果、581 ファイル・17MB に成長した。Jr 参加 (2026-10) を控え、ワークスペース境界とドキュメント構造の不整合が顕在化したため、再編議論を開始した。

1.2 現状 (Current State / As-Is)

docs/ 配下の内訳は以下:

  • _internal 239 files / 8.2MB (engineering/corporate 混在)
  • implementation 163 files (engineering)
  • adr 81 files (corporate)
  • research 14 files (corporate)
  • domains/architecture 50 files (corporate)
  • data/operations 21 files (engineering)

Cloudflare Pages は単一サイトでビルドされ、RAG chatbot は両ドメインを区別なくインデックスしている。_config.json の nav 配列は 117KB。

1.3 課題 (Problem)

  • nav 配列 117KB に肥大化し、新規ページ追加時に所属グループに迷う
  • RAG chatbot が engineering / corporate を区別なくヒットさせ検索精度が低下
  • Jr 参加時の認知負荷が高い
  • sub/main ワークスペース担当境界がディレクトリ構造に反映されていない

1.4 制約・要件 (Constraints & Requirements)

  • リポジトリ分割は ADR パイプライン・CLAUDE.md 相互参照を破壊するため不可
  • ADR-0039 (arc42+C4+MADR) / ADR-0046 (nav SSoT) / ADR-0069 (docs RAG chatbot) との整合性維持
  • ITGC ドキュメントは corporate サイト側で Cloudflare Access 制御が必要
  • Jr 参加 (2026-10) 前に完了させ認知負荷を低減する
  • 初期予算 2-3 日 (要追記: 盲点 #2, #3 を踏まえた再見積もりが必要)

1.5 目標 (Goals / To-Be)

docs/engineering/ と docs/corporate/ の物理分離を実現し、_config.json 2 分割 + Cloudflare Pages 2 サイト化により nav SSoT・ビルド・RAG corpus・Access ポリシーを境界化する。frontmatter audience タグも併用し RAG メタデータフィルタと物理分離の二段構えとする。Non-Goals: リポジトリ分割、サブワークスペース単位の追加サイト化。

2. 決定

同一リポジトリ内で docs/ を docs/engineering/ と docs/corporate/ に再編する。_config.json を 2 ファイルに分割し Cloudflare Pages を 2 サイトに分離する。_internal/ 239 件は内容に基づき分割し、分類ガイドラインを git mv 開始前に策定する。frontmatter audience タグを併用し RAG メタデータフィルタと物理分離の二段構えで検索精度を確保する。リポ分割は採用しない (ADR パイプライン・CLAUDE.md 相互参照保護のため)。

3. 判断基準 (Decision Drivers)

3.1 評価軸 (Q42 9 タグから 3-5 個選定)

#軸重要度 (係数)案件特有の解釈
1#maintainable[Must] (×2.0)nav SSoT・ディレクトリ構造・分類ガイドラインによる新規ページ追加時の判断負荷削減
2#secure[Must] (×2.0)corporate (ITGC 含む) と engineering の閲覧権限境界を Cloudflare Access で分離可能であること
3#suitable[High] (×1.0)RAG chatbot の検索精度向上 (audience フィルタ + corpus 分離による誤ヒット削減)
4#efficient[High] (×1.0)移行コスト (初期 2-3 日想定) と運用コスト増分が許容範囲内であること
5#flexible[Medium] (×0.5)将来のリポ分割や第三サイト追加への拡張余地

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

3.2 評価軸 × 案スコア表

軸係数採択案 (engineering/corporate 2 サイト分離)案 A (リポ分割)案 B (現状維持+nav 改善)案 C (タグベース分類のみ)
#maintainable×2.04312
#secure×2.04512
#suitable×1.04414
#efficient×1.03154
#flexible×0.53433
加重和 (正規化)0.7550.6600.3300.500
K.O. 通過 (Must ≥3)✓✓❌❌

(注: 採択案は案 C のタグベース分類を併用するハイブリッド構成)

4. 検討した代替案 (Alternatives Considered)

  • 案 A: リポジトリ分割 — ADR パイプライン・CLAUDE.md 相互参照が壊れ移行コストが大。盲点 #7 の通り Jr 参加時の権限分離ニーズと連動するため将来再検討余地は残すが、現時点では棄却。
  • 案 B: 現状維持 + nav 改善のみ — RAG 精度・認知負荷の根本解決にならず #maintainable K.O. により棄却。
  • 案 C: タグベース分類 (audience frontmatter) のみ — grep / ファイルブラウジング時の混在が未解消で #maintainable K.O.。ただし RAG メタデータフィルタには直接効くため採択案と併用する。

5. 影響 (Consequences)

5.1 正の影響 (Good)

  • nav SSoT が 2 ファイルに分割され、新規ページ追加時の所属判定が物理ディレクトリで自明化
  • RAG corpus を engineering/corporate で分離 + audience メタデータフィルタにより検索精度向上が見込める
  • Cloudflare Access を corporate サイトに適用することで ITGC ドキュメントの閲覧境界を明示化
  • Jr 参加 (2026-10) 前にディレクトリ境界が確立し認知負荷低減
  • ディレクトリ構造が将来のリポ分割時の構造と対応するため、2 段階移行コストの一部を先取り回収可能 (盲点 #7 対応)

5.2 負の影響 (Bad)

  • docs/ 配下 581 ファイルの git mv に伴う履歴追跡の複雑化
  • _config.json 2 分割、docs-build.mjs、docs-search-worker、CLAUDE.md、workspace_rules.md の同期改修コスト
  • クロスサイトリンクが別オリジン化により相対パスで解決不能になるリスク (盲点 #3): 581 ファイルにおけるクロスドメインリンクの現状値が未計測で、0.5 日のリンク検証見積は楽観的すぎる可能性。git mv 着手前に git grep でクロス参照を全数抽出し件数・修正パターン (絶対 URL 化 vs リダイレクト) を完了条件に明示する必要
  • _internal/ 239 件の分類工数が 0.5 日見積では 1 件 1.3 分相当となり著しく過小評価 (盲点 #2): 30-50 件のランダムサンプリングで実測してから 2-3 日へ再見積もりすべき
  • Cloudflare Access ポリシーが Terraform/Wrangler で IaC 管理されていない場合、内部権限過剰付与 (engineering メンバーが corporate ITGC 閲覧可能等) を CI の 401/302 テストでは検出不能で監査証跡が不十分 (盲点 #1)
  • CODEOWNERS が未整備の場合、同一リポ内で engineering 開発者が corporate ディレクトリへ git push 可能な状態が ITGC 監査で指摘されるリスク (盲点 #6)
  • RAG corpus 二重インデックス混入リスク (盲点 #4): 両コーパスを別ビルドしつつ同一ベクターストアに書き込む実装ミスが発生すると分離前より精度悪化。ベースライン未計測のため改善幅の仮説が定量化されていない

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

  • Cloudflare Pages 2 サイトのデプロイ順序依存により、片方が旧ビルドの間クロスサイトリンクが旧版を指す時間窓が発生 (盲点 #5): Pages deployment status API ポーリングによる完了待機 CI ステップ + スモークテスト + 大規模移行 PR のメンテナンスウィンドウ運用で緩和
  • リポ分割不採用は Jr 参加後の権限分離ニーズを先送りする (盲点 #7): branch protection・CODEOWNERS・secrets 分離で同一リポ構成でも必要要件を満たせるかを検証し、git mv 後のディレクトリ構造がリポ分割時の構造に対応するよう設計
  • 2 サイト成功体験による第三サイト追加要求の連鎖 (盲点 #8): ADR に「2 サイトを上限とし追加サイト要求は新規 ADR で審議」のガードレールを明記。Review After 評価項目に「サイト追加要求の有無と対応方針」を含める
  • ADR-0045 番号付き構造の再設計方針 (盲点 #9): engineering/corporate で独立採番 vs 通し番号維持 vs プレフィックス付与の設計方針を git mv 開始前に分類ガイドラインで確定
  • 月間運用コスト微増 (Access 2 ポリシーの整合性管理、四半期棚卸し)

6. 撤退条件 (Rollback Plan)

  • 判定指標:
    • corporate 誤公開インシデント発生 (Cloudflare Access の意図しない閲覧許可)
    • クロスサイトリンク切れの恒常化 (lint:links での 404 検出が毎週発生)
    • RAG top-5 precision がベースラインから低下 (要追記: 移行前にベースライン計測し最低改善閾値 (例: top-5 precision +15%) を撤退条件に数値化 — 盲点 #4)
    • ガバナンス不全 (CODEOWNERS / IaC ポリシーの運用破綻)
  • 期限: Review After 2026-11-27 で判定
  • 代替案: git mv のリバートで物理構造は戻せるが外部リンク (RAG corpus・bookmark) の完全復元は不可。撤退時は案 C (タグベース分類のみ) にフォールバック

6.5 Confirmation (準拠確認 / Fitness Function)

  • 検証手段:
    1. lint:links を 2 サイト横断モードで実行する CI ジョブ (engineering→corporate / corporate→engineering の外部参照を明示的にクロールし 404 検出 — 盲点 #3)
    2. Cloudflare Access ネガティブテスト CI: 「engineering グループメンバーが corporate サイトに 403 を返すこと」を確認 (盲点 #1)
    3. dead link checker (既存) ゼロ件
    4. corpus ビルド時の audience メタデータ整合性ユニットテスト (engineering ファイルが corporate index に混入していないか — 盲点 #4)
    5. PR テンプレートに audience チェック項目を追加し手動レビュー
    6. CODEOWNERS による corporate ディレクトリ変更時の designated approver レビュー必須化 (盲点 #6)
    7. 四半期ごとの Cloudflare Access ポリシー棚卸し (手動レビューチェックリスト — 盲点 #1)
  • 実行頻度: CI (1, 2, 3, 4) は PR / main push ごと。手動レビュー (5, 6) は PR ごと。棚卸し (7) は四半期ごと
  • 違反時の対応: CI 失敗は merge blocker。Access ネガティブテスト失敗時は即時 corporate サイトのデプロイ停止。棚卸しで権限ドリフト検出時は ITGC インシデントとして起票

7. 参照 (References)

  • 関連 ADR:
    • ADR-0039 (arc42+C4+MADR+feature-folder 構造): Refines — docs/ 上位再編として arc42 スコープとの両立を確認。分類ガイドラインで具体的に整合
    • ADR-0045 (_internal/ 番号付き構造): Refines — _internal/ を engineering/corporate に分割するため番号体系を再設計。完了条件の分類ガイドラインで具体化 (番号体系設計方針は git mv 開始前に確定 — 盲点 #9)
    • ADR-0046 (nav SSoT): Extends — _config.json 2 分割により SSoT を 2 ファイルに拡張。orphan 検出 lint を 2 サイト対応に改修
    • ADR-0048 (orphan ページ検出): Extends — 2 サイト対応で検出スコープを拡大
    • ADR-0051 (nav 未登録 lint): Extends — 2 サイト分離時の lint 対象パスを更新
    • ADR-0055 (nav prefix 体系): Refines — 2 サイト分離時の prefix 設計を再整合。engineering/corporate で namespace 分離
    • ADR-0069 (docs RAG chatbot): Extends — audience 絞り込みの中核実装。corpus 生成を 2 サイト対応に変更、メタデータフィルタ追加、Vectorize index 名を engineering/corporate で別管理 (盲点 #4)
  • 関連 PR/Issue: (要追記)
  • 外部資料: (要追記)
  • 完了条件 (移行 PR):
    • 2 サイト独立ビルド / 閲覧
    • audience 絞り込み動作
    • リダイレクト動作
    • lint:links + dead link checker ゼロ
    • corporate Access 401/302 CI テスト + 内部権限ネガティブテスト (盲点 #1)
    • クロスリンク全数カウント記録 (git mv 前後 — 盲点 #3)
    • _internal/ 分類ガイドライン策定 (git mv 開始前にレビュー完了 — 盲点 #2)
    • 未分類ファイルゼロ + UNCLASSIFIED.md インベントリ (盲点 #2)
    • RAG ベースライン計測 (top-5 precision — 盲点 #4)
    • PR テンプレートに audience チェック追加
    • CODEOWNERS に docs/corporate/ ルール追加 (盲点 #6)
    • Cloudflare Access ポリシーの IaC 化 (Terraform / Wrangler — 盲点 #1)
    • Pages deployment status API ポーリング CI (盲点 #5)
  • コスト試算: 初期 2-3 日 (git mv 1-2 日 + Access 設定 0.5 日 + リンク検証 0.5 日 + _internal 分類 0.5 日) — ただし盲点 #2 #3 を踏まえ実測サンプリング後に再見積もり予定 (推奨 4-6 日)。月間運用微増 (Access 2 ポリシー整合性 + 四半期棚卸し)
  • 長期的影響: 6 ヶ月レビューで _internal/ 誤分類数計測、RAG top-5 精度比較。Jr 入社 (2026-10) 前に完了し認知負荷低減。権限分離が必要になった時点でリポ分割を再検討 (今回のディレクトリ構造をリポ分割時の構造に対応させる設計)
  • Review After: 2026-11-27