最終更新: 2026/06/22 18:56
commonid: rq-046-result-geminitype: research-resultstatus: archived

RQ-046 ドキュメントインベントリ管理・カバレッジ追跡ベストプラクティス（Gemini 回答 / nav定義SSOT必須 + Backlogパターン + archived物理分離）

Gemini Deep Research 回答 / AIネイティブ開発チームのためのアーキテクチャ設計

TL;DR

  • インベントリの単一情報源化と CI 自動化: ナビゲーション定義ファイル（mkdocs.yml 等）を構造の「正」とし、CI で孤立ファイルやリンク切れを自動検出するアーキテクチャが発見可能性の課題を解決する。
  • カバレッジギャップのスタブ化と定量検証: 「書くべきだが未着手」のドキュメントは status: planned の空ファイルとしてコミットし、CI でのファイルサイズ判定（例: 100バイト以下）と組み合わせることで不可視のギャップを顕在化させる。
  • AI エージェントの段階的開示パターン（Backlogパターン）: CLAUDE.md にはグローバルルールのみを記述し、未執筆ドキュメントやタスク状況は別ファイル（Backlog.md）へ分離することで、コンテキスト肥大化とハルシネーションを防ぐ。

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

インデックスファイル方式の限界

GitBook などで古くから採用されてきた SUMMARY.md や README.md に手動でリンク集を作成する方式は、最も直感的で導入コストが低い。しかしながら、ファイル名の変更・ディレクトリ構造のリファクタリング・新規ドキュメントの追加時にインデックスの更新漏れが必然的に発生し、「リンク切れ（Link Rot）」が蓄積していく。さらに深刻なのは、インデックスに記載されていない「孤立したファイル（Orphaned Files）」の発生である。

YAML Frontmatter によるメタデータ管理

Obsidian、Hugo、Docusaurus などのモダンなドキュメントツールでは、Markdown ファイルの先頭に YAML 形式の Frontmatter を記述し、メタデータを付与する手法が業界標準となっている。各ファイルが自身の属性（type, status, audience, tags など）を自己記述するため、中央集権的なインデックスファイルに依存しない分散型の管理を可能にする。ただし、メタデータを解釈し動的なビューを生成するためには、特定のビルドツールやエディタの拡張機能が必要となるというエコシステム依存の課題が伴う。

静的サイトジェネレータのナビゲーション定義ファイル（例: mkdocs.yml の nav セクション）を「唯一の真実の情報源（Single Source of Truth）」として活用するアプローチは、構造の可視化と制御を同時に実現する。このアプローチの最大の利点は、人間にとってもAIにとってもプロジェクト全体の構造を俯瞰しやすいことである。インベントリファイルがシステムのナビゲーションレンダリングと直結しているため、開発者は必然的にこのファイルを更新せざるを得なくなり、インベントリの陳腐化が構造的に防止される（強く推奨）。

CI で孤立ファイルを自動検出

  • リンク切れの自動検出: markdown-link-check をGitHub Actions で実行し、PRのタイミングでリンク整合性を検証する。
  • 孤立ファイルの自動検出: リポジトリ内のすべての .md ファイルをスクリプトで列挙し、ナビゲーションツリーに含まれているかを検証する（必須要件）。

AI エージェント文脈での最適化

Claude Code のような自律型AIエージェントにとって、ディレクトリを再帰的に探索しすべてのファイルを読み込む処理は、トークンの著しい消費とコンテキストウィンドウの浪費につながる。CLAUDE.md や AGENTS.md といったエージェント専用のシステムプロンプトファイル内に、プロジェクトの「アーキテクチャマップ（インベントリの要約）」を記述する手法が標準化しつつある。

インベントリ管理手法発見可能性運用コストAI適性小規模推奨度
手動インデックス (README.md)低高低非推奨
動的メタデータ (Frontmatter)高 (ツール依存)低中条件付き推奨
Nav 定義兼用 (mkdocs.yml 等)非常に高中非常に高強く推奨
CI 自動検出 (孤立ファイル)最高初期設定のみ高最高必須要件

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

スタブ慣習（status: planned）

未着手のドキュメントに対して、空のファイルまたは最小限のテンプレートのみを含む Markdown ファイルを即座に作成し、Frontmatter に status: planned を付与する手法。ファイルシステム上に物理的なエンティティが生成されることで、「そこに情報が存在しない」という事実自体がインベントリ上に可視化される。

デメリット: 検索ノイズの増加。検索エンジンのインデックス対象から status: planned のファイルを除外する設定が必須。

チェックリスト方式（ADR との連動）

ADR の「Consequences」セクションに「このADRが採択された結果、必要になるドキュメント一覧」を明記する。また、Pull Request テンプレートに「関連する ADR やドキュメントを更新したか、またはスタブを作成したか」というチェックボックスを設ける。

イベントトリガー方式（CI 連携）

src/api/ 配下のソースコードが変更された場合、同一の PR 内で docs/api/ 配下のMarkdownファイルも同時に変更されているかを CI スクリプトで検証する。

定期棚卸し方式

status: planned のまま30日以上放置されているスタブファイルのリストを定期的に抽出し、チームの定例ミーティングでの確認事項に組み込む。

チームサイズ別推奨

小規模チーム（ソロ〜数名）においては、「スタブ慣習」と「イベントトリガー（CI での検証）」の組み合わせが最も投資対効果が高い。

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

推奨最小値域: 5値

ステータス値定義状態
plannedスタブ。本文は未執筆。カバレッジギャップの可視化用。存在を予約。内容は参照不可。
draft執筆中、またはチーム内レビュー中。内容が不完全・未確定。作業中。公式な参照情報ではない。
active現在有効。チームや AI が信頼して参照すべき「正」のドキュメント。運用中。信頼可能な真実の情報源。
deprecated過去の仕様。参照可能だが新規利用は非推奨。非推奨。歴史的文脈としてのみ参照。
superseded（主にADR用）新しい決定によって完全に上書き・置換された状態。無効化。代替ドキュメントが存在する。

archived の取り扱い

archived は Frontmatter の値域から除外することを強く推奨する。アーカイブの本質は「日常の検索空間からは完全に隔離する」ことであり、Frontmatter のステータスとして archived を持つのではなく、ファイル自体を docs/archive/ という専用の隔離ディレクトリに移動させるか、Git の履歴にのみ残してファイルシステム上からは削除するのがベストプラクティスである。

ADR との整合性

ADR の Proposed は一般ドキュメントの draft に相当し、ADR の Accepted は active に相当する。Deprecated と Superseded は両者で共通の概念として扱える。ADR と一般仕様書の Frontmatter スキーマを統一することで、CI でのバリデーションロジックと AI へのプロンプト指示をシンプルに保つことができる。

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

ハルシネーション防止のための設計

AI エージェントに「このトピックに関するドキュメントは存在しない」と正確に認識させるためには、プロジェクト全体の情報の境界線を明示的に提示する必要がある。CLAUDE.md 内において、「詳細な仕様やアーキテクチャを探す前に、必ず最初にインベントリマスター（mkdocs.yml）の構造を確認せよ。そこにエントリが存在しないトピックについては、ドキュメントが存在しないと判断し、推測で回答したりコーディングを進めたりせず、必ず人間に質問せよ」という厳格なガバナンスルールを課す。

status: planned スタブへの対処

CLAUDE.md の中で、「Frontmatter において status: planned と定義されているドキュメントは、チームが作成を予定しているが、現時点では意図的に未着手であることを意味する。このファイルの内容を埋めるよう明示的な指示を受けない限り、内容を推測してはならない」という明示的なルールを記述する。

Backlog パターン（段階的開示）

最重要設計パターン: CLAUDE.md や AGENTS.md の内部に直接「カバレッジギャップ一覧」を記述する手法は、プロジェクトのスケールに伴い深刻なアンチパターンとなる（コンテキスト長の圧迫・更新コストの増大）。

推奨されるアプローチは、カバレッジギャップや進行中のドキュメントタスクを、CLAUDE.md から切り離し、docs/_internal/Backlog.md や tasks.md といった専用の動的な状態管理ファイルへ分離する「Backlog パターン」である。

CLAUDE.md には「現在のタスク進行状況や、未作成のドキュメント（カバレッジギャップ）の一覧については、docs/_internal/Backlog.md を参照せよ」という1行のポインタのみを記述する。これにより、日常的なコーディング時のトークン消費を抑えつつ、AI の指示理解の精度（Signal-to-Noise 比）を高く保つことができる。

Q5. bizlp-gas-accounting への具体的推奨

1. カバレッジギャップ検出の最小実装（CI スクリプト）

  • Frontmatter バリデーション: docs/_internal/ 配下のすべての .md ファイルが、必須である type, status, audience の3フィールドを欠落なく持っているかをチェックする。
  • スタブの整合性チェック: status: active または draft に設定されているファイルで、ファイルサイズが150バイト未満の場合は CI をエラーで停止させる。
  • カバレッジの可視化出力: status: planned となっているファイルのリストをコンソール（または PR のコメント）に出力する。

2. インベントリ管理の最小実装

docs/nav.json または mkdocs.yml フォーマットを借用した軽量なインベントリマスターを導入する。CI に孤立ファイル検出スクリプトを組み込み、「インベントリ定義ファイルに記載があるが物理ファイルが存在しない」状態や、逆に「物理ファイルは作成されたがインベントリ定義ファイルに未登録」の状態を自動で検知する。

3. status フィールドの推奨値域

ADR-0045 の決定に準拠し、以下の4値を標準スキーマとして採用し、維持可能なシンプルさを優先する:

  • planned: 空ファイル・スタブ用。CI でのファイルサイズ下限チェックの対象外。
  • draft: 作成中の状態。
  • active: 最新の有効な仕様・手順。
  • deprecated: 過去の仕様。ファイルは履歴として残すが、新規開発での適用は不可。
  • ※ superseded は deprecated に統一し値域を単純化する（一般ドキュメント限定）。ADR には superseded を引き続き使用。

4. 6ヶ月後の再発防止（Jr. 参加を見据えて）

  • PR テンプレートへの強制: 「関連するドキュメントを追加・更新した、または status: planned のスタブを作成してコミットした」チェック欄を追加。
  • Claude Code のコミットフック化: AIコーディングの終了時に、「今回のコード変更で影響を受けるドキュメントを洗い出し、必要に応じて status: planned のスタブファイルを生成し、nav.json に追記せよ」という定型プロンプトを実行するワークフローを標準化する。

移行コスト試算: 既存の 30 本超のドキュメントへの Frontmatter 一括付与と nav.json の初回生成は、Claude Code に一括指示することで約 10〜15 分のレビュー時間で完了する。