最終更新: 2026/06/22 18:56
commonid: rq-046-doc-inventory-coverage-prompttype: promptstatus: active

RQ-046 ドキュメントインベントリ管理・カバレッジ追跡ベストプラクティス調査プロンプト（発見可能性 + カバレッジギャップ検出 / ADR-0046 起草前）

RQ ID: RQ-046
作成日: 2026-05-15
調査トリガー: ADR-0045（docs/_internal/ 組織化）対応中に浮上した2つの問題。①「どのドキュメントがどこにあるかわからない」（発見可能性）②「ドキュメント化したつもりで実はしていない」（カバレッジ不可視）。ADR-0045 のfrontmatter方針（type/status/audience）で部分解決できるが、カバレッジギャップ検出の仕組みは別途設計が必要。
関連 ADR: ADR-0045（_internal/ 組織化・frontmatter必須化）
3 モデル並列調査: Gemini Deep Research / Claude Research / GPT-4o Deep Research に同一プロンプトを投入する

プロジェクト背景（モデルへの文脈提供）

調査対象プロジェクトの特性:

  • 規模: ソロ開発（まもなく Jr. 1名参加）、GAS + LangGraph + Cloudflare Workers + GitHub Actions
  • ドキュメント体制: ADR 45本・開発仕様書 150本超・内部運用ドキュメント 30本超を docs/ 配下で管理。ADR-0039（arc42）で構造整備中。
  • 課題①（発見可能性）: docs/_internal/ に 30本超がフラット混在。目的のファイルを見つけるのに 2〜3分かかる（実測）。ADR-0045 で番号付きサブディレクトリ構造への移行を決定済みだが、ディレクトリを切り替えた後も「この件は既にドキュメントがあるか？」の確認に時間がかかる。
  • 課題②（カバレッジギャップ）: 「会話の中で口頭決定したこと」「検討途中で保留になったこと」が文書化されず、後から「あれどこに書いてあったっけ？→書いてなかった」が繰り返し発生。意図的に決定した事柄と偶発的に未記録になった事柄の区別ができていない。
  • AI エージェント利用: Claude Code が毎日 docs/ を参照。ドキュメントが存在しない場合に「存在しない」と知らずにハルシネーションするリスクがある。
  • frontmatter（ADR-0045 で決定済み）: 全 _internal/*.md に type / status / audience の3フィールドを必須化する方針。status フィールドの値域はまだ確定していない。

調査してほしいこと

Q1. ドキュメントインベントリ管理の業界パターン

小規模ソフトウェアチーム（1〜5名）において、「何がどこにあるか」を管理する手法として実績のあるパターンを教えてください。

  • インデックスファイル方式（単一 README.md / SUMMARY.md 等）の実例と限界
  • YAML frontmatter を活用したメタデータ管理の実例（GitBook / Docusaurus / Obsidian 等）
  • docs/_config.json や mkdocs.yml のような nav 定義ファイルをインベントリとして兼用する手法
  • CI で「ナビゲーション未登録ファイル」を自動検出する実例
  • AI エージェント（Claude Code / GitHub Copilot）の文脈でドキュメントインベントリを最適化している事例

Q2. カバレッジギャップ検出の手法

「書いたつもりで書いていない」状態を早期検出するための仕組みとして、実績のある手法を教えてください。

  • スタブ慣習: 未着手のドキュメントを空ファイルまたはプレースホルダーとして登録する手法（status: planned frontmatter 等）のメリット・デメリット
  • チェックリスト方式: 「書くべきドキュメントの一覧」を別ファイルで管理する手法（ADR の "Consequences" セクションに「ドキュメント化必須事項」を列挙する等）
  • イベントトリガー方式: コードマージ・ADR Accepted 等のイベント時にドキュメント作成をチェックする CI 連携パターン
  • 定期棚卸し方式: 週次・月次レビューでカバレッジを確認する運用パターン
  • 上記の組み合わせが有効なケースと、チームサイズ・規模別の推奨

Q3. frontmatter status フィールドの設計

docs/_internal/*.md 全ファイルに status フィールドを必須化する場合、以下の設計論点について推奨を教えてください。

  • 値域の設計: draft / active / deprecated / archived vs planned / draft / stable / deprecated vs その他パターン。小規模チームで維持可能な最小値域は何か
  • planned（スタブ）の運用: ファイルが存在するが内容がない状態を許容すべきか。許容するならファイルサイズ・最終更新日でのCI チェック方法
  • deprecated vs archived の使い分け: 参照は可能だが新規使用を推奨しない（deprecated）vs 履歴目的でのみ保存（archived）の区別が必要か
  • ADR の status（Proposed / Accepted / Deprecated / Superseded）との整合性をどう保つか

Q4. AI エージェントとドキュメントカバレッジの関係

Claude Code 等の AI エージェントがドキュメントを参照する環境において:

  • 「存在しないドキュメントへの参照」をエージェントが検出・報告できるようにするための設計パターン
  • status: planned スタブが存在する場合、エージェントが「ドキュメントはあるが未着手」と認識できるようにするためのベストプラクティス
  • AGENTS.md / CLAUDE.md に「カバレッジギャップ一覧」を記載する手法の実例と運用コスト

Q5. 推奨アーキテクチャの提案

本プロジェクト（ソロ開発・Jr.参加予定・ADR-0045 の frontmatter 方針確定済み）に対して:

  1. カバレッジギャップ検出の最小実装（CI スクリプト or 運用ルールのみ）
  2. インベントリ管理の最小実装（インデックスファイル or nav 定義兼用）
  3. status フィールドの推奨値域
  4. 6ヶ月後に「書いたつもりで書いていない問題」が再発しないための仕組み

を具体的に提案してください。移行コストは Claude Code 活用前提で試算（純手動作業での試算は不要）。

出力形式

以下の形式で回答してください：

  1. TL;DR（3行以内）: 最も重要な推奨を要約
  2. Q1〜Q5 への回答: 各設問に番号を付けて回答
  3. 本プロジェクトへの具体的推奨: Q5 の内容を bizlp-gas-accounting プロジェクトに特化した形で具体化
  4. 他モデルとの比較観点: このモデル固有の知見（他モデルが見落としがちな観点）があれば明示

以上がプロンプトです。調査対象プロジェクトの文脈に沿って、実践的・具体的な回答をお願いします。