RQ-041 突合 (Synthesis): ADR リポジトリのディレクトリ構造ベストプラクティス — bizlp 採択方針

位置付け: Claude Research と Gemini Deep Research の RQ-041 両回答を論点ごとに突き合わせ、bizlp 文脈での採択方針案を整理する。

本ファイルは「ADR 起案準備資料」。正式採択判断は Decision Pipeline 経由で新規 ADR として行う。

• 突合対象: RQ-041_*_result_claude.md / RQ-041_*_result_gemini.md
• 起票日: 2026-05-13

0. TL;DR

• 両エンジン完全一致の核心: フラット構造 / docs/adr/ 配置 / Co-location with code / 4 桁連番 + ハイフン + ケバブケース / イミュータブル原則 (Supersede パターン) / 運用ガイドは README.md / アンチパターン (ステータス別フォルダ・運用ガイドの ADR 混在・連番リセット)
• 3 つの相違点 (bizlp 文脈の採択方針):
  1. メタ ADR 番号: Claude = ADR-0001 開始 / Gemini = ADR-0000 開始 → ADR-0000 採用を推奨 (Gemini 案 / Backstage の慣例)
  2. メタ ADR の分割: Claude = 1 本派 / Gemini = 三層分離モデルを強調 → Gemini 案 (三層分離) を概念モデルとして採用、実装は 1 本派
  3. MOC / Backstage: Claude = 言及のみ / Gemini = 詳細推奨 → 将来検討に格下げ (個人開発に過剰)
• bizlp 現状とのギャップ 5 件 (採用すべき): ①3 桁→4 桁 ②_→- ③メタ ADR 不在→新設 ④_template.md → templates/template.md ⑤既存 21 ADR の命名規約準拠
• 次工程: 本 synthesis を Decision Pipeline に投入 → **ADR-0023 「ADR ドキュメント群の構造リファクタリング」**として正式起案 (ADR-0022 は Policy Alignment ノード追加で使用中 = PR #625)

1. 完全一致部分 (採用根拠)

両エンジンが独立に到達した一致点は、bizlp 文脈における採択根拠の中で最も強い。

1.1 基本構造 (両者一致)

1.2 ファイル命名 (両者一致)

1.3 文書役割分離 (両者一致)

1.4 ライフサイクル (両者一致)

1.5 アンチパターン (両者一致 = 採用しない)

1.6 イミュータブル原則 (両者一致)

一度 Accepted となった ADR は本文を編集しない。決定が変わったら新しい ADR を作って古い方を Superseded by ADR-NNNN とマークする。

これにより「いつ、なぜ方向転換が行われたか」の組織の思考の歴史 (History of thinking) を保全する。

1.7 テンプレート (両者一致 / 細部相違)

• 両者ともテンプレートを別ファイルに置く方針 (templates/template.md または template/ 配下)
• bizlp は既に Nygard + MADR 4.0 ミニマル統合形式を _template.md に保持済 (内容は維持、配置位置のみ調整候補)

2. 相違点 1: メタ ADR 番号 (ADR-0000 vs ADR-0001)

2.1 両エンジンの主張

2.2 bizlp 文脈での評価

2.3 採択方針 (Synthesis 推奨)

ADR-0000 採用を推奨 (Gemini 案)。理由:

1. 既存 ADR-0001〜0021 を 4 桁化 (0001〜0021) にする際、メタ ADR を ADR-0000 として頭に置くことで連番が綺麗に並ぶ
2. Backstage / Kubernetes KEP の「予約番号」慣例と整合
3. Decision Pipeline 採番ロジックは次空き番号を自動採番するため、最初の 1 回だけ手動採番すれば以降の起案には影響なし

ただし内容は両エンジン共通の「ADR 導入の決定そのものを記録」=「Record architecture decisions」型を採用。

3. 相違点 2: メタ ADR の分割 (1 本派 vs 三層分離モデル)

3.1 両エンジンの主張

3.2 bizlp 文脈での評価

bizlp は既に README.md = 初期マスター ADR 役割 + 運用ガイド という構造を採用済 (前 PR で確立)。三層分離モデルは概念的にこれと一致するが、Gemini が言う「初期マスター ADR (不変)」と「README.md (可変)」を別ファイルに物理的に分離するかは別判断。

両者の中間案: README.md は運用ガイド (可変) として維持しつつ、別途 ADR-0000 として「ADR を採用する」決定そのものを不変アーティファクトとして残す = 三層分離モデルを採用しつつ実装は 1 本派の最小構成。

3.3 採択方針 (Synthesis 推奨)

Gemini 案 (三層分離モデル) を概念モデルとして採用、実装は 1 本派の最小構成:

• ADR-0000: 「Record architecture decisions」(不変、20-30 行)
  • ADR 採用の決定そのものを記録
  • Nygard + MADR 4.0 ミニマル形式の宣言
  • 一度 Accepted 後はイミュータブル
• README.md (docs/adr/README.md): 運用ガイド (可変)
  • 命名規則 / Status 遷移 / 起案フロー / アンチパターン警告
  • 用語定義 (Glossary)
  • リスク受容方針
  • 既存 ADR 一覧
• 個別 ADR (docs/adr/NNNN-*.md): 通常 ADR

3 ファイル種類の役割を明確にすることで、後から読む人が「どこに何があるか」を即座に把握できる。

4. 相違点 3: MOC / Backstage の扱い

4.1 両エンジンの主張

4.2 bizlp 文脈での評価

4.3 採択方針 (Synthesis 推奨)

全て将来検討に格下げ (Claude 案寄り):

• 今は導入しない: MOC / Backstage / Log4brains / 自動 TOC 生成
• 再評価トリガー:
  • ADR が 50 本超 → Log4brains / 自動 TOC 生成を検討
  • 別プロジェクトを始めた → Backstage 検討 (組織レベル ADR の分離)
  • 「現在の認証システムがなぜこうなっているか」型の横断的理解が頻繁に必要 → MOC を README.md 内に手書き で導入 (ツール不要)

Gemini の MOC / Backstage 推奨は「数百本規模」を前提とした内容で、bizlp の 21 本規模には合わない。Claude の拡張トリガー方式の方が個人開発に適する。

5. bizlp 現状とのギャップ + 採用判断

5.1 ギャップ一覧

5.2 既存 ADR-0001〜0022 の renaming 範囲

bizlp 規模 (21 本) なら A 案が綺麗。renaming スクリプトで一括処理可能。

5.3 タイトル命令形化の現実

既存 ADR-0001〜0021 のタイトルは名詞ベース (010_modular_monolith_numbering.md)。これを動詞形 (use-modular-monolith-numbering) に変える意義は薄い (履歴の連続性が消える)。

採用方針: 既存は名詞ベースのまま、新規 ADR-0022 以降のみ動詞形を推奨。テンプレートと README.md に「新規は動詞形が望ましいが既存形式の踏襲も可」と注記。

6. ADR 起案の骨格 (Decision Pipeline 経由)

本セクションは「ADR-0023 (ADR ドキュメント群の構造リファクタリング)」を Decision Pipeline で起案する際の素材。

6.1 タイトル候補

「ADR ドキュメント群の構造を業界標準 (Nygard + MADR 4.0 ミニマル) に整える」

6.2 Mode

Critical (既存 21 ADR を全件 renaming するため不可逆度高、ただし decision-specific には小さな決定の集合)

6.3 Context

• 既存 ADR-0001〜0021 は 3 桁連番 + アンダースコア区切り + 名詞ベースで運用
• メタ ADR が不在 (README.md が暗黙的に役割を兼ねる)
• テンプレートが _template.md (root + _ prefix)
• ADR-0022 は再起案され「Policy Alignment ノード追加」として PR #625 で確定 (旧テナント層分離 ADR-0022 は close 済)
• RQ-041 で Claude + Gemini が業界標準を調査、両者一致で構造改革を推奨

6.4 Decision

1. 採番: 既存 21 ADR を 4 桁化 (010_* → 0010-*)、新規は 4 桁開始
2. 区切り: アンダースコア → ハイフン
3. メタ ADR 新設: 0000-record-architecture-decisions.md で ADR 採用の決定を不変記録
4. テンプレート移動: _template.md → templates/template.md
5. タイトル命令形: 新規 ADR は動詞形推奨、既存は据え置き
6. README.md 維持: 運用ガイドは現状の README.md を維持 (前 PR で完成)
7. MOC / Backstage / Log4brains: 今は導入せず、再評価トリガー (50 本超 等) を README.md に明文化

6.5 Consequences

• Good: 業界標準準拠、ツール互換性 (adr-tools / adr-log / Log4brains) 確保、新規参加者の認知負荷低減
• Bad: 既存 21 ADR のファイル名変更でリンク切れリスク → 内部参照全件更新が必要 (約 40 箇所推定)
• Neutral: Decision Pipeline の slug 生成ロジックがハイフン形式に対応するかの確認が必要

6.6 Considered Options

• 案 A: 全件 renaming (4 桁 + ハイフン) ← 採択
  • Good, because 業界標準準拠、二重採番なし
  • Bad, because 21 ファイル + 約 40 参照を更新する作業コスト
• 案 B: 新規のみ新規約適用、既存据え置き
  • Good, because 移行コスト最小
  • Bad, because 二重採番が永続化、新規参加者が混乱
• 案 C: メタ ADR + テンプレート移動のみ、命名はそのまま
  • Good, because 影響範囲限定
  • Bad, because 業界互換性 (ツールチェーン) が半端な状態に

6.7 撤退条件

• リンク切れ多発 → 個別修正 PR で順次対応、ロールバックは不要
• Decision Pipeline 採番が新形式 (0000+ハイフン) でエラー → Pipeline 側の slug 生成ロジック修正で対応 (本 ADR の決定自体は撤退不要)

7. 次のアクション

1. 本 PR (RQ-041 保存 + synthesis) をマージ
2. 本 synthesis を Decision Pipeline (POST /draft) に投入 → ADR-0023 「ADR ドキュメント群の構造リファクタリング」 として起案
3. ADR-0023 がマージされたら、§5.2 Option A (全件 renaming) を別 PR で実施
4. renaming 完了後、ADR-0000 メタ ADR を新規作成 (Decision Pipeline 経由 or 直接 PR)

8. Caveats

• 本 synthesis は 2 エンジンの回答に対する解釈。Claude / Gemini 自身の合議結果ではない
• bizlp 規模 (21 本 ADR / 1 人開発 + Jr 1 名予定) に最適化した判断
• MOC / Backstage / Log4brains を不採用とするのは現規模での判断。50 本超や複数プロジェクト化で再評価
• ADR-0000 を採用する判断は Backstage / Kubernetes KEP / Gemini 推奨に従ったが、adr-tools 標準 (0001 開始) と異なる点に注意 (将来 adr-tools 連携時は要調整)
• 既存 21 ADR の renaming は履歴の連続性を保つため、Git の git mv で実施 (旧パス削除 + 新パス追加ではなく rename を明示)

9. 関連ドキュメント

• 突合元: RQ-041_*_result_claude.md / RQ-041_*_result_gemini.md
• 関連 ADR (既存): ADR-0018 (Markdown 単一ファイル管理 / 拡張) / ADR-0019 (Decision Pipeline) / ADR-0021 (UC スライス採用)
• 関連 RQ: RQ-040 (開発組織化パラダイム)
• 業界標準参照: Michael Nygard "Documenting Architecture Decisions" / MADR 4.0 / Joel Parker Henderson "ADR" / Backstage / adr-tools / Log4brains