RQ-045 調査統合 (Synthesis)

RQ ID: RQ-045
統合日: 2026-05-15
調査モデル: Claude Research / Gemini Deep Research / ChatGPT Deep Research
後続作業: ADR-0043 起草

TL;DR（意思決定者向け要約）

3モデルが完全一致した結論：

1. docs/_internal/ は arc42 に吸収しない。維持する。
2. 内部に Diátaxis 由来の4〜5サブディレクトリ を追加する。
3. 全ファイルに YAML frontmatter を必須化する（最小3フィールド）。
4. ルートに AGENTS.md（〜60行） を置き、CLAUDE.md はナビゲーションハブに絞る。
5. 実行プロンプトは docs/ 外（.claude/skills/ 等）へ分離する。
6. RQ のライフサイクルを open → active → synthesized → archived に形式化する。

bizlp への即時推奨: docs/_internal/ 内に how-to/・runbooks/・research/・agents/（＋任意で business/）を追加し、既存ファイルを移動する（移行コスト：中、約半日〜1日）。

1. 3モデル合意マトリクス

2. モデル別固有知見（他モデルが補完できない洞察）

Claude 固有

• 「責務分離・意図主導型（案1）」: runbooks/ をプロジェクトルートに独立させる最も大胆な分離案を提示。AIエージェント適性「極めて高」と評価。
• Rule of Three を ADR に明記: 「同じ目的・性質のファイルが3未満なら専用ディレクトリ不要」を制約として ADR に刻む提案。過剰投資防止の安全装置として有用。
• CLAUDE.md の役割再定義: 「百科事典からナビゲーションハブへ」。詳細は外部ファイルへのポインタ（@docs/...）のみに限定する。

Gemini 固有

• AGENTS.md 標準化の詳細エビデンス: Linux Foundation 配下 Agentic AI Foundation が管理。60,000以上のOSSが採用。Cursor、Codex、Aider、Devin、Jules、GitHub Copilot、VS Code、Gemini CLI 等の主要ツールが対応済み。
• 「指示数を増やすと全体の遵守率が一律に下がる」: HumanLayer の実測データ。frontier thinking LLM で 150〜200 指示が上限。これが「60行ルール」の定量的根拠。
• 3層アーキテクチャの明文化: Tier 1 (AGENTS.md 60行) → Tier 2 (docs/_internal/agents/) → Tier 3 (参照資料) の階層を最も詳細に記述。
• 四半期レビューサイクル: GitLab Handbook の慣行（「オンボーディング時に必ず1箇所改善」）を RQ 管理に適用。

GPT 固有

• 「隠すこと」と「分類すること」は別問題: _internal/ プレフィックスは公開除外には便利だが、文書タイプの混在を解決しない。パス規約 ＋ frontmatter visibility ＋ ビルド除外設定 ＋ リポジトリ権限の4層で考えるべき。
• 最も詳細な frontmatter スキーマ: agent_load: always | on-demand | never という AIエージェント専用フィールドを提案。エージェントがコンテキストウィンドウを節約するための明示的ヒント。
• arc42 境界の最も具体的な定義: hooks_setup.md・migration_guide.md・ui_verification.md・failure_patterns.md は operations/ へ昇格候補。それ以外（git_workflow, research_prompts, biz/）は _internal/ 維持。
• 「今すぐ案A、AIプロンプト資産だけ案Cを先行導入」: 段階的移行戦略として最も現実的な提案。
• biz/ を最初に権限分離する候補として明示: 将来の業務委託者アクセス制御で、ビジネス資料が最初に独立させるべき対象。

3. 分岐点の整理と統合判断

分岐1: runbooks/ の場所

統合判断: docs/_internal/runbooks/ に収容（Gemini/GPT 案を採用）
根拠: 移行コストが低く、bizlp の現フェーズ（ソロ＋Jr.1名）では過剰な分離は YAGNI。_internal/ の外に出すメリットはファイル数が増えてから判断する（Rule of Three）。

分岐2: CLAUDE.md のシンボリックリンク化

統合判断: CLAUDE.md を維持しつつ内容をスリム化（Claude/GPT 案を採用）
根拠: Claude Code は CLAUDE.md をネイティブサポート。現プロジェクトに AGENTS.md 対応ツール移行の具体的計画はない。将来 AGENTS.md 対応が必要になった時点でシンボリックリンク化を検討（ADR-0043 のポストモーテム対象）。

4. 統合推奨ディレクトリ構造

docs/
├── arch/                          # arc42 ベース（ADR-0039 準拠）
├── dev/                           # 開発仕様書
├── spec/                          # データ定義・API 仕様
├── adr/                           # ADR（0001〜、既存構造維持）
└── _internal/                     # チーム内側（運用・調査・AI向け）
    ├── README.md                  # _internal/ の地図（CLAUDE.md からリンク）
    ├── how-to/                    # 手順書（Diátaxis: how-to guides）
    │   ├── git_workflow.md        # ← 移動
    │   ├── hooks_setup.md         # ← operations/ 昇格候補（arc42 判断後）
    │   ├── migration_guide.md     # ← operations/ 昇格候補
    │   └── workspace_rules.md    # ← 移動
    ├── runbooks/                  # 障害対応・定型運用
    │   ├── failure_patterns.md   # ← 移動
    │   └── ui_verification.md    # ← 移動
    ├── research/                  # 探索・RQ系（ライフサイクル管理）
    │   ├── active/
    │   │   └── RQ-NNN-*.md       # status: active のもの
    │   ├── _archive/              # status: synthesized / archived
    │   │   └── RQ-NNN-*.md
    │   ├── research_questions.md  # RQ マスタ一覧
    │   └── research_prompts/     # プロンプト・結果ファイル群（現行維持）
    ├── agents/                    # AIエージェント向け参考資料
    │   └── prompts/              # 人間/エージェントが参考にするテンプレート説明
    └── business/                  # ビジネス資料（提案書、要件メモ等）

# プロジェクトルート
CLAUDE.md                          # ナビゲーションハブ（詳細はポインタのみ）
                                   # 目標: 200行以内、各行「これがないと Claude がミスするか？」でフィルタ

# AI実行資産（doc/ 外）
.claude/settings.json              # 既存
.claude/skills/                    # Claude Code skills（実行時ロード）
src/prompts/                       # LangGraph 等から実行時に読み込むプロンプト（将来）

5. 統合推奨 frontmatter スキーマ

最小必須（フェーズ1・今すぐ）:

---
type: how-to | runbook | research | prompt | policy | setup | tracking | workflow
status: draft | active | synthesized | archived | superseded
audience: human | agent | both
---

推奨拡張（フェーズ2・Jr. 参加前）:

---
title: Git workflow
type: workflow
status: active
audience: both
visibility: internal          # public | internal | restricted
reviewed_on: 2026-05-15
review_cycle_days: 90
related_adrs: [ADR-0039]
tags: [git, workflow]
agent_load: on-demand         # always | on-demand | never
---

フィールド設計の原則:

• type（何の文書か）/ status（今どの段階か）/ visibility（誰に見せるか）は必ず別フィールドにする（GPT 固有知見）
• agent_load は Claude Code がコンテキストウィンドウを節約するための明示的ヒント（GPT 固有知見）
• Junior 参加後に pre-commit で frontmatter 必須チェックを自動化する

6. RQ ライフサイクル定義

3モデル完全一致した状態遷移：

open（調査中）
  ↓
active（調査実施中、プロンプト投入済み）
  ↓
synthesized（結論が ADR / spec / runbook に昇格済み）
  ↓
archived（物理アーカイブ、_archive/ へ移動）

• 状態変更は research_questions.md の行更新 ＋ frontmatter status: 更新で行う
• archived に移動しても 削除はしない（ADR 起草・再調査の参照元として保全）
• 四半期（3ヶ月）ごとに active ファイルのレビューを行い、stale なものを archived に移す

7. arc42 への移行境界（GPT の最も具体的な分類を採用）

8. ADR-0043 への入力まとめ

ADR-0043「docs/_internal/ 組織化・内部ドキュメント管理方針」で決定すべき事項：

Decision 1: サブディレクトリ構造（本 Synthesis で推奨）

• docs/_internal/ を維持し、how-to/・runbooks/・research/・agents/（＋任意で business/）の4〜5サブディレクトリを追加
• 根拠: 3モデル完全合意。arc42 founders 自身が arc42 のスコープを意図的に絞っており、ワークフロー・調査記録・プロンプトは対象外。

Decision 2: frontmatter 必須化

• 全 _internal/*.md に最小3フィールド（type / status / audience）必須
• 根拠: LLM にとっての「型シグネチャ」として機能し、Progressive Disclosure を可能にする（3モデル完全合意）。

Decision 3: CLAUDE.md スリム化

• CLAUDE.md を200行以内のナビゲーションハブに絞る。詳細は @docs/... ポインタのみ。
• 根拠: 「指示数↑ → 遵守率が一律↓」（HumanLayer 実測）。現状の CLAUDE.md はすでに encyclopedic になりつつある。

Decision 4: 実行プロンプトの分離

• AIエージェントが「実行」のために参照するプロンプトは .claude/skills/ へ移動
• 人間/エージェントが「参考」にするテンプレート説明は docs/_internal/agents/prompts/ に残す
• 根拠: 3モデル完全合意。実行資産とドキュメントの混在が hallucination とトークン無駄遣いを招く。

Decision 5: Rule of Three の明記

• 「同じ目的・性質のファイルが3本未満の間は専用サブディレクトリを作らない」を ADR の制約事項として記録
• 根拠: 過剰階層化（Big Framework Trap）を防ぐガイドレール（Claude / Gemini 合意）。

Decision 6: RQ ライフサイクル

• research/active/ と research/_archive/ を分離
• 全 RQ に status frontmatter 必須。四半期レビューで stale を archived に移す
• 根拠: RFC / PEP パターンの応用（3モデル完全合意）。

9. 移行ステップ（優先順位付き）

関連ファイル

• result_claude.md — Claude Research 結果（14ページ）
• result_gemini.md — Gemini Deep Research 結果（15ページ）
• result_gpt.md — ChatGPT Deep Research 結果（10ページ）
• RQ-044 synthesis — LLM プロンプトライフサイクル管理（関連 ADR-0042）