エレベーターピッチ
- これは何？ : DRP の説明書を「要求 → 要件 → 外部設計 → 内部設計 → テスト」の層に分けるための調査まとめです。
- だれのため？ : DRP のドキュメントを再編する人と、改修の影響範囲を事前に知りたい人。
- なにが起きる？: 3 つの AI が別々に調査 → 一致点を突合 → 文書カタログ 41 件と移行手順に落とし込み。
- 譲れない一線 : 一覧表（トレーサビリティマトリクス）は手書きしない。必ず機械生成にする。
- だから : 「この改修はビジネス要件まで変わるのか？」に、文書を辿るだけで答えられるようになります。
1. 調査概要
- Research Question: ソロ開発 docs-as-code プロジェクトで、層別ドキュメント（ビジネス要件 / システム要件 / 外部設計 / 内部設計）と軽量な変更影響トレーサビリティを実現する最適な体系は何か（調査プロンプト）
- 実行: 2026-06-04、
scripts/run_deep_research.mjs で 3 モデル並列（コスト計 $5.36）
- 生結果: openai (o3) / gemini / claude (opus-4-7)
| モデル | 性格 | 評価 |
|---|
| claude | DRP 文脈に最適化。ページツリー・L1〜L4 影響分類・移行 10 ステップ・完了指標まで具体 | 高（設計の叩き台） |
| openai | 日本流（要件定義→基本設計→詳細設計）と国際標準の橋渡し・比較マトリクスが丁寧 | 高（判断根拠の裏取り） |
| gemini | 前半の RDRA 解説は有用、後半は ERD 変換・edge インフラ等へ脱線 | 中（前半のみ参考） |
2. 3 モデル一致点（確度高）
- 単一標準の丸呑みは不適 → ハイブリッド: 層の名前 = ISO/IEC/IEEE 29148 + 日本流（BR / SR / 外部設計 / 内部設計）、骨格 = arc42（ADR-0039 で採用済）、決定の記録 = 既存 ADR をそのまま維持。RDRA 2.0 は図中心でソロ docs-as-code に不向き（gemini のみ推奨 = 少数派）。
- 外部 / 内部の境界 = 「外から観測可能な契約か」: API・プロンプト I/O 契約・queue 封筒・状態機械・エラーモデル = 外部設計。リトライ曲線・ルーティング・ロック = 内部設計。
- ID + 上方向リンクのみ + マトリクスは生成物: 全要素に
<種別>-<領域>-<連番> ID。下層から上層へ Covers: の一方向参照のみ。トレーサビリティマトリクスは手書き・コミット禁止（matrix rot が最頻失敗モード）。CI が Covers: を走査して生成 + orphan 検出。
- ADR は「なぜ」の層: 要件・設計の再記述禁止。frontmatter に
Covers: / Constrains: を持たせ参照のみ。Append-only。
- 移行は strangler-fig: 用語集 → BR → SR → NFR → 外部設計 → 内部設計 → arc42 ビュー → ADR への Covers 後付け → 運用分離 → README ナビハブ化（≤150 行）。抽出したら同一コミットで旧 README から本文を消しリンク化（新旧併存 = drift の最頻原因）。
3. L1〜L4 変更影響分類（claude 提案・本調査の中核成果）
「この改修はどのレベルまで影響するか？」を改修前に機械判定する枠組み。PR テンプレートに組み込む。
| Level | 何が変わる改修か | 必須更新 | ADR | 再実行するテスト層 |
|---|
| L1 | ビジネス要件（目的・対象者・ROI） | BR + 配下の SR/設計を全数再検証 | 推奨 | 受入（Confirmation KPI） |
| L2 | システム要件（機能・非機能） | SR/NFR + 配下の外部・内部設計 | 推奨 | システムテスト（TC 系） |
| L3 | 外部設計（API・プロンプト I/O 契約・スキーマ） | 外部設計 + 破壊的変更判定 + 利用側追従 | 必須 | 契約テスト（golden eval / OpenAPI diff） |
| L4 | 内部設計のみ（契約不変） | 契約テスト pass の確認のみ | 任意 | 単体（vitest） |
- 迷ったら L3 扱いにして ADR を書く（コストは md 1 枚・監査痕跡が残る）。
- DRP Triage との関係: Triage（Light/Standard/Critical）= 審査の厳しさ、L1〜L4 = 更新すべき文書層。直交する 2 軸で相互補完。
4. テスト文書の補正（調査ギャップの自己修正）
調査プロンプト Q3 がテスト仕様を設問に含めなかったため、3 モデルともテスト文書の扱いが薄い（独立成果物として明示したのは openai #6「Test Plan & Traceability Matrix」のみ・nice-to-have 扱い。claude はページツリーに test-spec 欠落）。本 synthesis では V 字モデルの「各層 = 設計成果物とテスト成果物の対」（claude Q1 引用）に基づき検証層（TC-）を一級レイヤに昇格して補正する。既存資産がそのまま写像できるため追加コストは小さい:
| 層 | テスト成果物（既存資産） |
|---|
| ビジネス要求（受入） | ADR の Confirmation 節（KPI 検証） |
| システム要件（システムテスト） | test_cases.md（TC-01〜07）+ TC-S / TC-C 系 |
| 外部設計（契約テスト） | golden eval（prompts-eval/datasets/*/golden.jsonl + tools/triage-eval FN=0 ゲート）/ Web UI mocked-route e2e（ADR-0111） |
| 内部設計（単体） | vitest（crossval_loopbreaker.test.ts 等） |
5. 文書カタログ（9 層・41 件）
ID 体系: BR- / SR- / NFR- / UC-（既存）/ EDD- / IDD- / TC- / ADR-（既存） の 8 種。
優先度: Must 17 / Should 17 / Nice 7。Must の過半は既存資産の再配置で充足し、純粋な新規執筆は 7〜8 本（BR/SR/NFR/OpenAPI/テスト計画ほか）。
0. 入口・概要層
| 文書 | 優先度 | 既存資産 |
|---|
| README（ナビハブ・≤150 行） | Must | 現 749 行 README を縮退 |
| 基本情報 + エレベーターピッチ | Must | 冒頭規約 ADR（起案中）と接続 |
| 用語集（JA↔EN） | Must | architecture/glossary.md 拡張 |
1. ビジネス要求層（BR-）
| 文書 | 優先度 | 既存資産 |
|---|
| ビジネス要求定義書 | Must | README §3〜4 から抽出 |
| 対象ユーザー・ステークホルダー定義 | Must | README §5 の一部 |
| 設計原則 | Must | README §5 |
| ビジネスフロー図 | Should | README §6 を図化 |
2. システム要件層（SR- / NFR- / UC-）
| 文書 | 優先度 | 既存資産 |
|---|
| システム要件定義書（ゲート別） | Must | README §7 + nodes/*.md の要件部 |
| 非機能要件定義書 | Must | 散在記述（wall time / コスト等）を集約 |
| ユースケース一覧 | Should | UC-{N} 採番が既存 |
3. 外部設計層（EDD-）
| 文書 | 優先度 | 既存資産 |
|---|
| API 仕様書 + OpenAPI 定義 | Must | index.ts の 19 ルートから起こす |
| データ定義書（D1・DO キー・queue 封筒） | Must | telemetry schema v8 等を集約 |
| プロンプト仕様書（ゲート別 I/O 契約） | Must | prompts/0X_*.md を再編 |
| 状態遷移仕様 | Must | README §8.1-3 mermaid（既存） |
| エラーモデル・コード表 | Should | §12 エラーハンドリング節から |
| 画面設計書（Web UI） | Should | ADR-0111 e2e 文書と接続 |
| 外部 I/F 一覧 | Should | §8 構成要素マッピング表から |
| CRUD マトリクス | Nice | gemini 推奨 |
4. 内部設計層（IDD-）
| 文書 | 優先度 | 既存資産 |
|---|
| ゲート内部設計書（ノード別） | Must | nodes/01〜.md がほぼ移行可能 |
| キュー・DO 設計書 | Should | ADR-0066/0103 実装記述を集約 |
| LiteLLM ルーティング設計書 | Should | litellm/ + §8 |
| リトライ・バックオフ設計書 | Nice | DLQ/max_retries 記述から |
5. アーキテクチャビュー層（arc42 / C4 — 図はここに集約・各層から参照のみ）
| 文書 | 優先度 | 既存資産 |
|---|
| システムコンテキスト図（C4 L1） | Must | §8.1-1 の上位を分離 |
| コンテナ図（C4 L2） | Must | §8.1-1 mermaid（既存） |
| コンポーネント図（C4 L3） | Should | §8.2 ASCII 詳細図（既存） |
| シーケンス図 | Must | §8.1-2 mermaid（既存） |
| デプロイ・CI/CD 構成図 | Should | git_workflow + §12 から |
| 横断的関心事（ログ・シークレット・認証） | Should | ADR-0104/0110 と接続 |
| ランタイムウォークスルー | Nice | README §6 の技術版 |
6. 決定層（ADR-）
| 文書 | 優先度 | 既存資産 |
|---|
| ADR 本体（Covers:/Constrains: 追加） | Must | 既存 110+ 本そのまま |
| ADR インデックス（自動生成） | Should | MAS-367/368 計画と合流 |
7. 検証層（TC-）
| 文書 | 優先度 | 既存資産 |
|---|
| テスト計画書（層×テスト種別の戦略） | Should | CLAUDE.md「変更時テスト」表の一般化 |
| テスト設計書（層別） | Should | test_cases.md + TC-S/TC-C |
| golden データセット仕様 | Should | prompts-eval/（既存） |
| トレーサビリティマトリクス（CI 生成・コミット禁止） | Must | 新規（grep ベース lint から） |
8. 品質・リスク・運用層
| 文書 | 優先度 | 既存資産 |
|---|
| 品質シナリオ（arc42 §10） | Nice | — |
| リスク・技術的負債台帳（arc42 §11） | Should | BUG_tracking + failure_patterns が実質 |
| 運用ガイド | Must | operator_guide_langgraph.md（既存） |
| ランブック（障害対応） | Should | operator_guide §7.x 群を分離 |
| 監視・テレメトリ仕様 | Should | schema v8 記述を集約 |
| 変更履歴 | Must | changelog.md（既存） |
6. 移行の定量的完了条件（claude 提案の採用候補）
| 指標 | 目標 |
|---|
| README 行数 | ≤150 行（80% 以上がリンク/見出し） |
| README 内の正典コンテンツ残存 | 0 セクション（CI の見出し grep で検査） |
BR/SR/NFR の Covers: 解決率 | 100%（orphan 0） |
新規 ADR の Covers: 付与 | 100%（既存 ADR は被参照上位 20 本から後付け） |
| 外部契約の OpenAPI / JSON スキーマ化 | 100% |
7. 次のアクション
- 本 synthesis を根拠に「DRP ドキュメントの層別再編 + L1〜L4 影響分類」の ADR を Pipeline 起案（Standard 想定）
- 実装は strangler-fig の週次刻み: 週 1 = claude must-have 8 項目（用語集 / ID 規約 / BR 3 件 / ゲート別 SR / ADR テンプレ Covers / README ハブ化 / CI lint / PR テンプレ L1-L4）
- 別軸の関連案件と接続: 冒頭規約 ADR（§0 層）/ 知識レイヤ 6 層 ADR（置き場所のメタ規約）/ MAS-367〜370（ADR インデックス自動生成)