ADR-0090: RQ 研究アーティファクトを単一サブツリーへ統合し parent-only nav にする (ADR-0079 precursor)

• Status: Accepted
• Mode: Standard
• Kruchten Type: Existence/Executive
• Scope: corporate
• Implementation Status: Not Started
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-29 23:53
• 承認日時 (JST): 2026-05-30 00:05 (Pipeline 通常 flow Standard 46/50 通過 + Consistency/Policy INFO、PR #1151 マージ)
• Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

RQ 研究アーティファクト(メタプロンプト→プロンプト→各モデル結果→synthesis)の置き場が分散し、同一 RQ の全成果物を 1 箇所で辿れない状態が継続している。ADR-0079(docs を engineering/corporate へ物理再編・Proposed)が起案者同一で並行進行しており、本 ADR はその precursor として位置付ける。

§1.2 現状 (As-Is)

• docs/research/ (nav M.02・26 file/10 RQ) と docs/_internal/01_discovery/research_prompts/ (nav I.01・90 file/27 RQ) の 2 ディレクトリに分裂。
• 両者とも docs-build audience 分類は corporate(Cloudflare Access 社内・非インターネット公開)。
• nav は per-vendor まで全登録(計 116 entry)。

§1.3 課題

• 同一 RQ の全成果物を 1 箇所で辿れない(クロスディレクトリ参照が必要)。
• nav 116 entry は RQ 59 件規模に非スケール(さらに増加見込み)。
• synthesis 無し 12 RQ の親エントリが不定。

§1.4 制約・要件

1. ADR-0079 互換: 統合は自己完結サブツリーとして作り、ADR-0079 着地時に docs/corporate/.../research/ へ単一 git mv で原子的再配置できる形にする(二重移動回避が核心)。
2. 履歴保持: git mv で履歴保持。rename とリンク書換を別コミットに分離(同一コミットだと Git rename 検出を下回り git log --follow 断絶)。
3. リンク完全性: 「旧パス参照 grep = 0」を完了条件とし、grep 対象は *.md/*.yml/*.yaml/*.json/_redirects/mkdocs.yml(GitHub Actions・動的生成・外部埋め込みは対象外として記録)。
4. Access ポリシー同期: Cloudflare Access パスベースポリシーの新パス追加を git mv と同一デプロイサイクルで実施。
5. PR スコープ制限: PR diff 対象を docs/_internal/01_discovery/research/ 以下に CI で制限(0079 構造先取りのスコープクリープ防止)。
6. 追加 LLM/インフラコストなし、GAS 増分なし、Pages 再ビルド無料枠内。

§1.5 目標 (To-Be)

RQ アーティファクトを docs/_internal/01_discovery/research/ の単一サブツリー(corporate 社内)へ集約し、nav は parent(synthesis)-only。synthesis 以外は synthesis の References リンク + frontmatter parent: で到達(ADR-0088 と同方式)。命名は RQ-NNN_<slug>_<type> 統一。Non-Goals: ADR-0079 で行う engineering/corporate 物理再編そのものは本 ADR の対象外。

決定

RQ 研究アーティファクトを docs/_internal/01_discovery/research/ の単一サブツリーへ集約し、nav は synthesis のみ登録の parent-only 構成へ移行する。命名規約は RQ-NNN_<slug>_<type> に統一、parent: frontmatter で階層を表現する。ADR-0079 が単一 git mv で docs/corporate/.../research/ に再配置できる自己完結形を維持し、step-by-step 手順は tasks/migration_rq-research-consolidation.md(Phase 0–7) に分離する。

判断基準 (Decision Drivers)

3.1 評価軸

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

3.2 評価軸 × 案スコア表

加重和は K.O. 通過候補のタイブレーク用(Suhr 1999 CBA 準拠)。本案件は採択案のみが K.O. 通過。

検討した代替案 (Alternatives Considered)

• 案 A (現状維持・2 ディレクトリ並存): docs/research/ と docs/_internal/01_discovery/research_prompts/ を維持 — 同一 RQ を 1 箇所で辿れず、nav 116 entry が 59 RQ 規模に非スケール(#maintainable=1 で K.O.)。
• 案 B (ADR-0079 を待たず corporate 直下に先回り配置): docs/corporate/.../research/ を本 ADR で先に作成 — ADR-0079 が Reject/大幅修正された場合に再 mv が必要で #flexible=2 で K.O.。0079 構造先取りのスコープクリープに該当。
• 案 C (ディレクトリ統合のみ・nav は全 file 登録を継続): 物理統合は行うが parent-only 化せず nav per-file 登録を維持 — #maintainable=3(同一 RQ は 1 箇所で辿れるが nav は肥大のまま)/ #flexible=5(統合済みなので 0079 単一 mv は可)/ #reliable=4 / #secure=4 / #efficient=3(nav 編集分やや増)。加重和 ≈ 0.800 で K.O. は通過するが、59→100+ RQ で nav 肥大が続き「nav スケール」目的の半分しか達成しないため採択案に劣る。次点。

影響 (Consequences)

§5.1 正の影響 (Good)

• 同一 RQ の全成果物(メタプロンプト→プロンプト→各モデル結果→synthesis)を 1 サブツリーで辿れる。
• nav が parent-only で 59 RQ 規模もスケール、将来 100+ にもテーマ別サブグループ化で対応可能。
• ADR-0079 着地時に単一 git mv で corporate 配下へ原子的再配置でき、0079 の工数を削減。
• ADR-0088(コスト試算必須化)を dogfood 適用。

§5.2 負の影響 (Bad)

• ~116 file 移動 + 全リンク書換が必要(工数 約 3.75 人日)。
• synthesis 無し 12 RQ(全体の ~20%)の親が不定で「プロンプトを親にする」規約で対処するが、進行中 / 中断 / 廃止 の分類なしで統合すると品質負債が残る(Gate 1 #9)。→ Phase 0 で分類し、廃止分はアーカイブパス(nav 外)に分離。
• nav 外ファイルが検索インデックスから外れる実装が多く、ビルドツールの検索設定で nav 外も明示インデックス化が必要(Gate 1 #7)。Phase 0 でテストビルドにより検索インデックス収載を検証必須。
• 命名規約・parent: frontmatter の運用が移行後に風化するリスク(Gate 1 #10)→ scripts/new-rq.sh スキャフォールド + CI lint で RQ-[0-9]{3}_[a-z0-9-]+_(meta|prompt|result|synthesis)\.md を強制。

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

• リンク取りこぼしリスク: 「grep=0(対象拡張)」+ docs:lint:links 新規 broken 0 で担保。grep 対象外の CI workflow ファイル・allowlist は Phase 0 で明示列挙し、除外理由をインパクト評価込みで記録(Gate 1 #6)。
• MkDocs インクリメンタルビルドのキャッシュ汚染(Gate 1 #1): Phase ゲートでは mkdocs build --clean のフルクリーンビルドを必須化。CI ジョブ full-link-audit を Phase マージ時に必ず実行し、PR チェックのインクリメンタルビルドとは分離。runbook に明記。
• Cloudflare Access 伝播ラグ(Gate 1 #2): デプロイ後の疎通テストで新パス 3 件を Access トークン無しで叩き HTTP 302/403 を検証、200 ならデプロイパイプライン失敗。プレビュー URL でポリシー検証後に本番昇格。Phase 0 チェックリスト項目ではなく自動ゲートとして実装。
• Git リネーム検出失敗(Gate 1 #5): リネームのみのコミットに CI ステップを追加し、git diff でパス更新以外の行差分があれば失敗。コミットメッセージ規約 chore(mv-only): を lint フックで強制。
• ADR-0079 非互換採択リスク(Gate 1 #3): Phase 2 開始前に ADR-0079 想定の corporate レイアウトとの互換性契約を明文化し、0079 決定プロセスから非公式の承認(サインオフ)を取得。45 日目にカレンダートリガで継続可否を判定。
• CI ビルド時間: 統合後 ~295 file での docs:lint:links は O(N*M) で増加。Pages 20 分タイムアウト懸念を Phase 0 で計測し、インクリメンタル化の要否を判断。
• 判断者バイアス(Gate 1 #8): Phase 0 チェックリストを GitHub Issue として公開し 48h 以上 open に保って非同期レビューを許容、self-review 結果を ADR コメントに記録。Jr 入社後は 2 名承認制へ移行。

コスト試算 (Cost Estimate)

Corrigendum (2026-05-30): 本 § は cost-estimation-section lint (ADR-0088) 準拠のための構造補正 (ADR-0031 immutable + corrigendum パターン)。工数見積は §1 コンテキスト / §3.2 #efficient 軸 (本文 immutable) に既出で、ここでは要約のみ再掲する。

• 移行工数 合計 約 3.75 人日: ~116 file 移動 + 全リンク書換 (Phase 別内訳は §1 内蔵表を参照)。追加インフラコスト 0。

撤退条件 (Rollback Plan)

• リンク切れ: 各 Phase 完了後 24h 以内に新規リンク切れ 3 件超 → 即時 git revert。自動検知として 6h 毎の定期実行 GitHub Action で docs:lint:links を走らせ、閾値超過時に GitHub Issue 自動起票 + 自動 revert PR を起動(Gate 1 #4)。閾値は Phase 毎に独立適用。
• 工数超過(2 段階・Gate 1 #4): 1 Phase の作業が見積もりの 150% 超 → 全体計画を必須で棚卸し。200% 超 → 自動停止。
• ADR-0079 待ち: 30 日以内に ADR-0079 が Accepted されない → 暫定パス(_internal/01_discovery/research/)で継続、Accepted 後に単一 mv。0079 が Rejected または 3 ヶ月停滞(Stale) → 本サブツリーを最終形として確定(0079 依存解除)。45 日目で継続可否の中間判定(Gate 1 #3)。
• 判断者(個人開発の制約): 単独判断のバイアス回避として 24h クーリングオフ + Phase 0 チェックリストの self-review(GitHub Issue 48h open) を撤退判断ゲートとする。Jr 入社後は 2 名承認制。
• 移行期間中の汚染防止: 旧パスへの新規追加/リンクを CI の path-based lint で Phase 0 完了時点から禁止。
• revert 手順: ワンコマンドの runbook 手順として tasks/migration_rq-research-consolidation.md に記載。

確認 (Confirmation)

• 検証手段:
  1. docs-nav-lint / docs:lint:links (PR 毎、incremental)
  2. full-link-audit CI ジョブ (mkdocs build --clean、Phase マージゲート)
  3. 旧パス grep カウント = 0 ( *.md/*.yml/*.yaml/*.json/_redirects/mkdocs.yml、Phase 3 完了条件)
  4. デプロイ後の疎通テスト(新パス 3 件を Access トークン無しで叩き HTTP 302/403 を検証)
  5. frontmatter parent: 実在チェック(Phase 6 で CI 常設化)
  6. 命名 lint: RQ-[0-9]{3}_[a-z0-9-]+_(meta|prompt|result|synthesis)\.md(Phase 6 以降常設)
  7. 検索インデックス収載のテストビルド(Phase 0 で nav 外ファイルが検索インデックスに出ることを確認)
• 実行頻度: PR 毎(1,3,5,6)/ Phase マージ毎(2)/ デプロイ毎(4)/ Phase 0 一度(7)/ 6h 毎の定期実行(1 のリグレッション監視)
• 違反時対応: リンク切れ 3 件超 24h 以内→git revert、Access 疎通テスト 200→デプロイ失敗、grep ≠ 0→Phase 完了不可、命名/frontmatter lint 失敗→PR ブロック。

参照 (References)

• 関連 ADR:
  • ADR-0079 (docs を engineering/corporate へ物理再編・Proposed): 本 ADR は precursor。Phase 1 を前提確定ゲートとし 0079 が Accepted/Freeze するまで Phase 2 以降を開始しない(30 日の暫定フォールバック併用)。
  • ADR-0055 (nav 番号体系): 統合後 nav 連番・parent-only 準拠。
  • ADR-0049 (4 層 Scope): research は corporate audience、Scope は triage で確定。
  • ADR-0088 (コスト試算必須化): 本 ADR がコスト試算を内包(dogfood)。
  • ADR-0070: research 子ファイルの H1↔nav 不一致は別案件。
• follow-up: I.01.x の parent-only 化は本 ADR の nav 統合に包含。
• 関連 PR/Issue: -
• 外部資料:
  • tasks/migration_rq-research-consolidation.md (Phase 0–7・synthesis 無し 12 RQ の親ルール)
  • Phase 別工数試算表(合計 約 3.75 人日、本 ADR §1 内蔵)
• Review After: 2026-08-29(導入 3 ヶ月後) — 負債化シナリオ点検:
  • synthesis 無し 12 RQ の「親=プロンプト」規約形骸化による孤立ファイル化 → frontmatter parent: 実在 CI 常設の有効性確認。
  • ADR-0079 長期 Stale で _internal/01_discovery/research/ が事実上の最終形として固着 → 撤退条件の 3 ヶ月確定ルールで処理。
  • 59 RQ→増加で nav 親エントリが 100+ になりテーマ別サブグループ化(I.01 方式)の要否判定。
  • scripts/new-rq.sh および命名 lint の運用継続確認(Gate 1 #10)。

11. 参照: Pipeline 審査履歴 (2026-05-29 実行時, 通常 flow)

Decision Pipeline で本草案を通常 flow (retroactive=false) で審査した結果。Gate4 46/50 (Standard 閾値 40 + 6pt 余裕、Critical 45 も到達) + Consistency PASS + Policy 条件付き Accept。代替案≥3・影響ファイル列挙・コスト内訳+金額・Review After・定量撤退・KPI を全充足した再投入で 39→46 に改善。