← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0046type: adrstatus: superseded
pagemode: Standardkruchten: Property/Executivescope: platformimplementation_status: N/A (退役)proposed_at: 2026-05-15approved_at: -deciders: [email protected] (単独)business: meta
型付き辺: 出 3 / 入 1
細分化する: ADR-0045 関連: ADR-0039 ADR-0079 置換された: ADR-0048全体は INDEX →

ADR-0046: ドキュメントインベントリ管理・カバレッジ追跡方針の確立

  • Status: Superseded by ADR-0048
  • Mode: Standard
  • Kruchten Type: Property/Executive
  • Scope: platform
  • Implementation Status: N/A (退役)
  • supersededBy: ADR-0048
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-15
  • 承認日時 (JST): -
  • Superseded 日時 (JST): 2026-05-16
  • Deciders: [email protected] (単独)

Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

退役メモ (2026-05-16): 本 ADR は Proposed 段階で複数の差し戻し対応 PR (#771 / #772) が並行し、本文改訂と新規ファイル追加 (ADR 番号衝突含む) が混在した。整理のため ADR-0048 で再起案し、本 ADR は Superseded とする。決定内容そのもの (5 施策) は ADR-0048 に引き継がれ、加えて差し戻し対応 (数値根拠 / 評価軸 6 軸 / 撤退手順表 / 工数以外コスト) を取り込んだリッチ版になる。また ADR-0048 は body-generation プロンプトパイプラインによるテーブル劣化テストの題材を兼ねる (詳細は ADR-0048 §パイプライン投入テスト計画)。

コンテキスト

1.1 背景 (Background)

ADR-0045 で docs/_internal/ のディレクトリ構造（番号付きサブディレクトリ）と YAML frontmatter の基本方針（type/status/audience 必須）を確立した。しかし以下の2問題が未解決のまま残っている。

訂正注記（2026-06-10）: 上記「audience 必須」は起案当時の記述。後発の ADR-0123（frontmatter 3 層モデル）が common 必須トリオを id/type/status に確定し audience 必須化を却下したため、ADR-0045 も Corrigendum（2026-06-09）で audience 必須化を撤回。現行正典は ADR-0123 で、audience は「推奨・任意」（詳細は docs/_internal/05_how-to/frontmatter-lint_rules.md §7.1）。

問題①（発見可能性）: 「どのドキュメントがどこにあるかわからない」。現在 _config.json の nav 配列がインベントリとして機能しているが、nav 登録漏れ（orphan ファイル）をシステム的に検出する仕組みがない。

問題②（カバレッジギャップ）: 「書いたつもりで書いていない」。会話の中で口頭決定したこと、検討途中で保留になったことが文書化されず、後から「あれどこに書いてあったっけ？→書いてなかった」が繰り返し発生。意図的な未記録（口頭で済む些末事項）と偶発的な未記録の区別ができていない。

また、ADR-0045 が規定した status フィールドの値域は暫定的であり、実用的な最小値域と各値の運用ルールが未定義だった。さらに Claude Code が「未着手ドキュメント」を読んだとき、その内容を存在するものとして扱ってしまう（幻覚）リスクが未対処だった。

1.2 現状 (Current State / As-Is)

  • docs/ 配下に 230本超のファイルが存在するが、frontmatter を持つファイルはほぼゼロ。
  • _config.json の nav 配列が事実上の唯一のインベントリだが、nav 未登録を検出する CI がなく、orphan ファイルが蓄積している。
  • ADR-0045 は status フィールドを必須化したが、値域（planned / draft / active / deprecated / superseded）の定義と運用ルールが本 ADR まで defer されていた。
  • COVERAGE_GAPS.md に相当するファイルが存在せず、「意図的な未記録」と「偶発的な未記録」が区別できない。
  • CLAUDE.md の status 言及がなく、Claude Code は status: planned のスタブファイルの内容を捏造するリスクがある。

1.3 課題 (Problem)

  1. orphan ファイルの蓄積: nav に登録されないファイルがサイレントに増え、静的サイトビルドでもエージェント検索でも到達できない。
  2. スタブ墓場化: スタブを作ったまま放置すると、あたかもコンテンツが存在するかのように見える誤解を生む。
  3. カバレッジ不可視: 「書いていないこと」が明示されないため、ユーザーが Claude Code に質問したとき幻覚回答が発生する。
  4. status 値域の曖昧さ: active vs stable、deprecated vs archived の使い分けが不明確で誤運用が発生しやすい。

1.4 制約・要件 (Constraints & Requirements)

  • ソロ〜2人体制で継続可能な低コスト運用に限定する（週60分以上のランニングコストは不可）。
  • ADR-0045 の frontmatter 基本方針（type/status/audience 必須）と整合すること（audience 必須化は ADR-0123 で撤回・上記 §1.1 訂正注記参照。現行の必須トリオは id/type/status）。
  • _config.json の nav 配列を引き続き「唯一の真実（Single Source of Truth）」として使用する（bizlp の静的サイトビルドは scripts/docs-build.mjs が _config.json を読むため）。
  • CI（GitHub Actions）への依存は最小限にとどめ、まず「COVERAGE_GAPS.md 手動管理 + 月次目視棚卸し」で運用し、必要に応じて CI 自動化を追加する（段階的導入）。
  • CLAUDE.md は 200行以内（Anthropic 公式推奨）を維持すること。status 規約の追加は既存行を圧縮して吸収する。

1.5 目標 (Goals / To-Be)

  • _config.json orphan 検出スクリプトを CI に追加し、nav 未登録ファイル = 0 を常時維持。
  • status 5値の定義と運用ルールを確定し、全 docs/ ファイルに適用（移行は AI 活用で実施）。
  • docs/COVERAGE_GAPS.md を新設し、「意図的な未記録」と「偶発的な未記録」を区別する。
  • CLAUDE.md に status 規約と AI-first nav 読み取り順序を追記し、Claude Code が status: planned を「未着手」として認識できるようにする。
  • status: planned のまま 30日超のスタブを検出する CI スクリプトを追加し、スタブ墓場化を抑止する。
  • Pull Request テンプレートにドキュメント更新確認のチェックボックスを追加し、実装変更時のドキュメント更新漏れをレビュー時に検出する。

Non-Goals: mkdocs --strict への移行（bizlp は独自ビルドを使用）、MkDocs / Docusaurus への移行、GitBook 導入、ADR 以外のドキュメントへの supersededBy 強制。

決定

以下の5施策を採用する。（RQ-046: Claude / GPT / Gemini 3モデル合意に基づく）

決定①: status 値域を5値に確定する

planned    スタブ。中身がない。作る予定だけある。
draft      書き始めたが未完。レビュー不要。
active     現行ドキュメント。Claude Code が信頼してよい。
deprecated 古い。新規参照非推奨だが履歴として残す。
superseded 完全に置き換えられた。supersededBy フィールドで後継を指す。

ADR ファイルに限り、status: proposed | accepted | rejected も使用可（MADR 4.0 互換）。active の代わりに accepted を使い分ける。archived は当面導入しない（deprecated と運用差がなく、値域が増えると迷いコストが上回る）。

frontmatter スキーマ（全 docs/*.md 共通）:

---
type: adr | spec | runbook | guide | reference | onboarding | research
status: planned | draft | active | deprecated | superseded  # ADRは proposed|accepted|rejected も可
audience: developer | operator | future-self
owner: "@t_saitoh"
created: YYYY-MM-DD
updated: YYYY-MM-DD
supersededBy: ADR-NNNN    # status: superseded のときのみ必須
planned_for: YYYY-MM-DD   # status: planned のときのみ推奨
---

例外: README.md、SUMMARY.md、COVERAGE_GAPS.md、MEMORY.md は frontmatter 不要。

ADR ファイルの二重メタ運用: docs/adr/*.md は冒頭の - **Status**: Proposed 行（MADR 4.0 慣習）を SSOT とし、frontmatter status フィールドはそのミラーとする。両者が不一致のときは冒頭行を正とし、adr-lint.mjs で同期チェックする（ADR-0045 Confirmation 要件に追加）。accepted / active の使い分け: ADR ファイルは accepted、それ以外の docs/*.md は active を使う（MADR 慣習を尊重）。

決定②: COVERAGE_GAPS.md を新設してカバレッジギャップを可視化する

docs/COVERAGE_GAPS.md を「known-unknowns（意図的な未記録）一覧」として維持する。記載内容は:

  • 口頭で決まったが文書化されていない事柄
  • 検討中・保留中の事柄
  • 将来 ADR 化を予定している事柄（ADR 番号予約含む）

Claude Code は本ファイルを参照し、ギャップ事項について質問されたら「文書化されていません。ユーザーに確認してください。」と回答する（幻覚禁止）。

運用パターン（Gemini: Backlogパターン）: CLAUDE.md には COVERAGE_GAPS.md へのポインタ1行のみを記述する。ギャップリストの全文は CLAUDE.md に書かず本ファイルで管理する。これにより CLAUDE.md のコンテキスト肥大化を防ぎつつ、Claude Code が必要時に詳細を参照できる構造を維持する。

決定③: _config.json nav 検証スクリプトを導入してorphan を防ぐ

既存の scripts/adr-lint.mjs を docs/_internal/ 対応に拡張する（ADR-0045 の Confirmation 要件）。加えて:

  • docs/ 配下の .md ファイルで _config.json の nav に未登録のものを orphan として検出するスクリプト scripts/docs-nav-lint.mjs を新設する。
  • CI（GitHub Actions）の docs ジョブに組み込み、orphan 検出時は PR をブロックする（warn ではなく error）。
  • 例外リスト: README.md、COVERAGE_GAPS.md、_internal/01_discovery/research_prompts/*.md（研究メモは nav 登録不要）。
  • Phase 3 に status: planned のまま 30日超のスタブを検出する scripts/check_stale_stubs.py を追加する（Claude + Gemini 合意）。検出時は CI warning（error にしない: 計画スタブが即 PR ブロックにならないよう）。

決定④: CLAUDE.md に status 規約を追記する

CLAUDE.md に以下を追加し、Claude Code が文書の状態を正しく認識できるようにする（200行上限内に収める）:

## Documentation status conventions
**IMPORTANT**: If a doc has `status: planned`, treat its content as nonexistent — do NOT infer or invent.
- `planned`: stub, no content yet → ask the user
- `draft`: partial, verify with user before relying
- `active`: trusted, up-to-date
- `deprecated`: historical context only
- `superseded`: follow `supersededBy` field
Unknown status → ask user. See `docs/COVERAGE_GAPS.md` for known-unknowns list.

AI へのドキュメント提示順序（GPT 提案）: Claude Code が調査を開始する際は、個別ファイルを読む前に必ず _config.json の nav 構造を確認することで、到達可能なドキュメントの全体像を把握してから詳細調査に入る。このパターンにより「存在しないドキュメントへの問い合わせ」が減り、幻覚リスクを軽減する。CLAUDE.md の「Progress tracking」セクションに追記する。

決定⑤: Pull Request テンプレートにドキュメント更新チェックボックスを追加する

.github/PULL_REQUEST_TEMPLATE.md に以下のチェックボックスを追加し、実装変更に伴うドキュメント更新漏れをレビュー時に検出できるようにする（Gemini 提案）:

## ドキュメント確認
- [ ] 関連ドキュメントを更新した、または `status: planned` スタブをコミットした
- [ ] 更新不要の場合はその理由を PR 説明に記載した

このチェックボックスは強制ではなく（CI ブロックしない）、レビュアーへの注意喚起を目的とする。スタブ追加だけでも OK とすることで「とりあえず planned で登録する」習慣を促進し、カバレッジギャップの偶発的な発生を抑制する。

検討した代替案 (Alternatives Considered)

評価軸本案（5施策）案B: MkDocs 移行 + --strict案C: Obsidian グラフビュー案D: 現状維持
運用コスト（ソロ）◎ 月60分以内△ MkDocs 学習 + 移行コスト大△ Obsidian 導入・習慣化コスト◎ 0
orphan 検出精度◎ _config.json 直接検証◎ --strict で確実△ 目視依存× なし
AI 適性◎ frontmatter 機械可読◎△×
bizlp との整合◎ 現行ビルド維持× ビルド刷新が必要△◎
段階的導入◎ Phase 1〜3× 一括移行△—
  • 案B MkDocs移行 — 不採用理由: bizlp は独自の scripts/docs-build.mjs を使い Cloudflare Pages に公開している。MkDocs 移行は本 ADR のスコープを超え、ビルドパイプライン全体の刷新が必要になる。
  • 案C Obsidianグラフビュー — 不採用理由: エディタ依存であり CLI 作業時・CI では機能しない。Claude Code はグラフビューを持たない。
  • 案D 現状維持 — 不採用理由: orphan ファイルが蓄積し続け、Claude Code の幻覚リスクが増大する。

phase 構成（段階的導入）:

Phase内容所要時間
Phase 1（即実施）COVERAGE_GAPS.md 新設 / CLAUDE.md に status 規約追記 / status 値域確定 / PR テンプレートにチェックボックス追加1時間
Phase 2（2週間後）既存 docs/*.md への frontmatter バルク付与（Claude Code 活用）2時間
Phase 3（1ヶ月後）docs-nav-lint.mjs 新設 + CI 組み込み / adr-lint.mjs の _internal/ 対応拡張1時間

影響 (Consequences)

5.1 正の影響 (Good)

  • Claude Code が status: planned を認識することで、スタブを「存在するドキュメント」として扱う幻覚を防止できる。
  • COVERAGE_GAPS.md により「意図的な未記録」が明示化され、ユーザーが「書き忘れたのか・意図的か」を区別できる。
  • orphan 検出 CI により、nav 登録漏れによる到達不能ファイルの蓄積を防止。
  • frontmatter スキーマの統一により、将来的な「status: planned 30日超スタブ検出 CI」の実装が容易になる。
  • PR テンプレートのドキュメント確認チェックボックスにより、実装変更時のドキュメント更新漏れをレビュー段階で検出可能になり、偶発的なカバレッジギャップ発生を抑制できる。

5.2 負の影響 (Bad)

  • 既存 230本への frontmatter バルク付与（Phase 2）に約2時間の実装コストが発生。
  • docs-nav-lint.mjs の例外リスト管理が必要（research_prompts/*.md 等は意図的に nav 外）。
  • CLAUDE.md への追記で6〜8行を消費。現在の CLAUDE.md 行数によっては既存記述の圧縮が必要。

5.3 中立・トレードオフ (Neutral / Trade-offs)

  • archived の将来導入: ADR が100本を超えた場合や Jr. エンジニア参加後に archived の導入を再検討する。その際は本 ADR を supersede する新 ADR を起案する。
  • planned_for フィールド: 義務化せず「推奨」とする。スタブの滞留を強制的に管理したい場合のオプト・イン。
  • 3モデル合意の確認: Claude・GPT・Gemini の3モデルで調査を実施し Synthesis を作成した（docs/_internal/01_discovery/research_prompts/RQ-046_synthesis.md）。GPT 提案の _manifest.yaml 別ファイル案は bizlp の _config.json アーキテクチャと非整合のため不採用。Gemini 提案の docs/archive/ 物理ディレクトリによる旧文書分離も、ADR が 100本未満の現状ではフォルダ移動コストがメリットを上回るため本 ADR では不採用とし、将来再検討（5.3 archived 将来導入と同期）。

撤退条件 (Rollback Plan)

  • Phase 3 の CI 導入後、正常ファイルを orphan と誤検知するケースが3件以上続く場合は docs-nav-lint.mjs の例外リストを拡張するか CI ルールを warn 降格。
  • status: planned ルールにより Claude Code が正常なドキュメントへの回答を不当に拒否するケースが複数発生した場合は CLAUDE.md の表現を緩める。

Confirmation (準拠確認 / Fitness Function)

指標計測方法目標値
orphan ファイル数scripts/docs-nav-lint.mjs0本（研究メモ除く）
frontmatter 準拠率scripts/check_frontmatter.py docs/違反 0本（Phase 2 完了後）
COVERAGE_GAPS.md 更新頻度git log --oneline docs/COVERAGE_GAPS.md月1回以上
Claude 幻覚事象手動モニタリング（1週間）planned スタブ内容の捏造 0件

Review After 2026-08-15（Phase 3 完了から約2ヶ月後）:

  • CI orphan 検出の偽陽性件数確認
  • status: planned 30日超スタブ件数（スタブ墓場リスク評価）
  • COVERAGE_GAPS.md の実際の利用状況確認
  • archived 導入要否の判断

参照 (References)

  • 関連 ADR:
    • ADR-0045: docs/adr/0045-organize-docs-internal-document-management-policy.md（frontmatter 基本方針の前提）
    • ADR-0039: docs/adr/0039-adopt-arc42-for-architecture-documentation.md（docs/ 全体構造の前提）
    • ADR-0028: docs/adr/0028-adopt-6-stage-workflow-uc-slice-dev-cd-gas-mvp.md（ステージ番号整合性）
  • 関連調査:
    • docs/_internal/01_discovery/research_prompts/RQ-046_result_claude.md
    • docs/_internal/01_discovery/research_prompts/RQ-046_result_gpt.md
    • docs/_internal/01_discovery/research_prompts/RQ-046_result_gemini.md
    • docs/_internal/01_discovery/research_prompts/RQ-046_synthesis.md（Synthesis: 3モデル合意 + bizlp 採択方針）
  • 外部資料:
    • MADR 4.0: https://adr.github.io/madr/
    • Diátaxis: https://diataxis.fr/
    • Anthropic CLAUDE.md ベストプラクティス（200行上限）
    • ETH Zurich: "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" arXiv:2602.11988（2026-02-13）