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

RQ-046 ドキュメントインベントリ管理・カバレッジ追跡ベストプラクティス（GPT 回答 / _manifest.yaml AI前処理 + AGENTS.md優先読込指示）

GPT Deep Research 回答 / bizlp-gas-accounting 向け詳細レポート

TL;DR

小規模チームでは、YAML frontmatter を活用し外部マニフェスト（例：docs/_manifest.yaml）を維持してドキュメント索引とする方法が有効です。CI により未登録ドキュメントの検出やステータスチェックを自動化し、status: planned/draft/active/deprecated 等で進捗管理します。AIエージェントには AGENTS.md/CLAUDE.md で「フロントマターを読む」「ドラフト・planned は参照しない」ルールを伝え、欠落ドキュメントを明示します。最終的には、前述の仕組みを組み合わせ定期レビューでフォローアップすることで、6ヶ月後もドキュメントギャップを防ぎます。

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

  • インデックスファイル方式（README/SUMMARY）: GitBook などでは SUMMARY.md に全ドキュメントの目次を手作業で列挙しますが、ドキュメントが増えると手動更新が煩雑になりがちです。またフォルダ構成やファイル名に依存しているため、機械的に検索するには限界があります。ユーザレベルでは有用ですが、自動化・大規模化には不向きです。

  • YAML frontmatter 活用: Docusaurus や Obsidian では、各 Markdown ファイル冒頭に YAML frontmatter を書き込み、description や tags、status 等のメタ情報を管理できます。例えばある例では、YAML frontmatter に status: active/draft 等を置くことで、AI エージェントが「ドラフトは未完了だから参照しない」と判断できるようにしています。このようにメタデータを明示することで、人も機械もドキュメントを絞り込みやすくなります。

  • Nav 定義ファイルの兼用: mkdocs や Docusaurus では mkdocs.yml や sidebars.js にナビゲーション定義を書きます。これを「ドキュメントインベントリ」として活用することも可能です。例えば mkdocs の nav 設定に全 .md を列挙し、CI で Markdown ファイル全体と突き合わせて「未登録ファイルあり」を検出する運用が考えられます。ただし、これも手動管理が必要な点や、ファイル数が増えるとメンテが面倒になる欠点があります。

  • CI による未登録ファイル検出: 一部のチームでは、ビルド時にナビゲーション定義と docs/ 配下を突き合わせるスクリプトを実行し、未登録の .md があるとエラーにする仕組みを組み込んでいます（Shell スクリプトや Python でファイル一覧を読み込ませ、nav 定義と比較）。また、YAML frontmatter を全ファイルから抽出して一元化するスクリプトを実行し（下例のような）、その結果をインベントリ（_manifest.yaml）としてコミットさせる例があります。

  • AI エージェント視点の最適化: Claude Code や Copilot など AI コーディングエージェントは、文書検索において全ファイルをフルスキャンするとトークン消費が激しく非効率です。そこで、各ファイルの YAML frontmatter を先に読むワークフローが提案されています。例えば、docs/_manifest.yaml を作成して AI に「まずこれを読め、関連ありと判断したファイルだけ本文を読め」と指示する方法があります。実際に OpenCode（Claude Code 風エージェント）の事例では、_manifest.yaml を前処理で生成し、AGENTS.md 内で「最初に Manifest を読むこと」を明示するルールを加えています。これにより、AI はドキュメントの存在や概要を素早く把握でき、存在しないファイル参照時も「リストにないから未作成」と判断しやすくなります。

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

  • スタブ（未着手）慣習: 書くべきドキュメントを空のプレースホルダー（status: planned や status: draft）として先にリポジトリに置いておく方法です。メリットは「書くべき項目が目視で分かる」「AI にもメタデータで未完了と認識させられる」点です（例：status: draft と記すとエージェントは「未完了」と見なす）。しかしスタブが増えすぎると混乱を招く恐れがあり、内容がないファイルを放置すると無駄になります。したがって、サイズや更新日で CI チェックし「内容ゼロならエラー」などのルールを設ける運用が推奨されます。

  • チェックリスト方式: プロジェクト全体で必要なドキュメントの一覧を作り、未着手のものを管理する方法です。例えば ADR やチケットに「ドキュメント化必須事項」を明記したり、専用の README（または Notion/CONFLUENCE など）に TODO リストを作成したりします。このリストを CI やプルリクテンプレートで参照すれば、「仕様変更時に対応ドキュメントを更新済みか」のチェックリストにもなります。

  • イベントトリガ方式: コードマージや ADR 承認時に「対応ドキュメントの存在」を CI で自動検出する仕組みです。たとえば GitHub Actions で PR がマージされた際、追加・変更されたコード領域に関連するドキュメントが作られていなければワーニングを出す、といったフックが考えられます。

  • 定期棚卸方式: 定期的にチームでドキュメント全体をレビュし、抜けや古い情報を洗い出す運用です。例えば週次ミーティングや月次レビューで「最新の機能でドキュメント化してないものはないか」を議論し、ステータスを planned→draft→published と進めます。

  • 組み合わせの有効性と規模別: 小規模（1〜3名）ならスタブ＋プルリクチェックリスト＋週次確認の組み合わせで十分です。中規模以上ではさらに CI フックや自動通知を導入します。

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

  • 値域例: 小規模チームで管理しやすいステータスのパターン例としては、planned（作成予定）、draft（執筆中）、active または stable（公開/完成済）、deprecated（非推奨）くらいの4段階が考えられます。

    • 小規模での最小値域: 例えば planned / draft / published / deprecated の4値で十分運用可能です。最終的にはチームの慣習に合わせ、あまり多くしないことが鍵です。

  • planned（スタブ）の扱い: ファイルが存在するが内容がない状態を許容するかは運用次第ですが、有効な情報とみなせません。許容する場合は CI で file.size < N（例えば数十バイト）なら警告 or エラー、あるいは status: planned に反応して警告を出すスクリプトを実装しておくとよいでしょう。AI エージェント向けには status: planned を「未着手スタブ」として認識させ、本文を読まないようルール化できます。

  • deprecated vs archived: 一般的には deprecated（古く推奨しない）で十分対応可能です。archived を別に設けるとすると「参照のみ目的の履歴データ」という意味になりますが、小チームでは管理が煩雑になるため、deprecated 状態のドキュメントは自動でアーカイブ（例：フォルダ移動やタグ付け）する運用で代用するケースが多いです。

  • ADR 状態との整合性: ADR の status（Proposed/Accepted/Deprecated/Superseded）とは別ドメインですが、用語に整合性は持たせられます。例えば、ADR が Accepted（採択済）なら対応ドキュメントの状態を active、ADR が Deprecated ならドキュメントも deprecated といった対応です。

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

  • 存在しないドキュメント検出: エージェントに docs/ 内を検索させる際、まず docs/_manifest.yaml や frontmatter だけを読むワークフローを設定し、新規ファイルの存在をチェックさせるパターンがあります。例えば CLAUDE.md に「検索時は最初に _manifest.yaml を読む」と指示すれば、Manifest に記載のないトピックは「未作成」と判定できます。また、CLAUDE 自身に「status: planned は未実装、archived は参照禁止」と教えることで、AI 側で文書の有無・完成度を区別させることも可能です。

  • status: planned をエージェントに伝える: ファイルに status: planned（または draft）を付与し、AGENTS.md/CLAUDE.md に「ドラフトや planned は引用しない」と明記する方法があります。例として、ある知見ブログでは CLAUDE.md に「ドキュメント生成時には必ずタイトル・作成日・修正日・カテゴリ・ステータス・タグ・関連ファイルを frontmatter に書く」というルールを置き、Claude Code が作成するファイルにも自動的にメタデータを付与させています。

  • AGENTS.md/CLAUDE.md でのカバレッジ一覧管理: ドキュメントギャップを明示的に管理する例として、AGENTS.md や CLAUDE.md に「未実装のドキュメント一覧」を記載し、エージェントに参照させる方法があります。docs/_manifest.yaml を読み込ませる手法なども参考になります。

Q5. 推奨アーキテクチャの提案（bizlp-gas-accounting）

  1. カバレッジギャップ検出の最小実装: ドキュメントごとに frontmatter 必須化（既に ADR-0045 で決定済）に加え、CI ワークフローで「マニフェスト生成スクリプト」を実行します。docs/ 配下の Markdown をスキャンして _manifest.yaml を生成する Python や Bash スクリプトを組み込み、CI の pre-commit/hook で自動更新させます。さらに、「本文が空のファイルがある」「status が planned なのに一定期間更新がない」といった条件でビルド失敗とするルールも追加します。

  2. インベントリ管理の最小実装: docs/_manifest.yaml を全ドキュメントのインデックスとして活用します。CI で前述のマニフェスト生成を自動化し、常にコミット状態に保ちます。エージェントには AGENTS.md/CLAUDE.md で「マニフェストを最初に読む」指示を加え、docs/_manifest.yaml を索引ファイル兼ナビゲーションとします。

  3. status フィールドの推奨値域: 小規模チーム運用に適した例として、planned / draft / active / deprecated を推奨します（archived は deprecated フラグ + docs/_archived/ フォルダ移動で代用）。

  4. 6ヶ月後の再発防止策: _manifest.yaml 自動更新と「ファイル新規時に必ず frontmatter を含める」ルールを CI と連携させることで、Claude Code が新規ドキュメントを作成する際にもメタデータを自動追加させます。月次あるいは四半期の定期レビュー会議でマニフェストとドキュメント一覧を目視チェックし、ステータスが planned のまま放置されている項目を更新する習慣を付けます。

他モデルとの比較観点

本回答では、特に AI エージェント視点から実践例を活用しました。他のモデルで見落としがちな観点として、「AI に前処理させるマニフェスト生成」や「AGENTS.md/CLAUDE.md でエージェントに明示ルールを与える手法」を挙げられます。低コストでの CI 自動化と、Claude Code 連携のための frontmatter 活用という特徴的なソリューションを取り入れており、「AI 活用前提のドキュメント構造最適化」に踏み込んだ点に特徴があります。