発展トピック¶

リファレンス索引 (CLI / CONFIG_DB / YANG / cross-reference) を回し続けるための index 再生成スクリプト群、新 mapping の追加手順、CI drift の対応をまとめます。22 章は索引そのものを扱うメタ章なので、ここでは「索引を生成する側」の運用を扱います。

index 再生成スクリプト群¶

meta/scripts/ 配下に index 再生成系のスクリプトが集中しています。22 章の運用で日常的に触るのは次の七本です。

スクリプト	役割	主な出力
`gen_coverage.py`	reference ページの verification 内訳 / カバー率を集計	`docs/reference/index.md` 内の coverage 表
`gen_cross_ref.py`	章 ↔ reference の双方向リンクを生成	`docs/topics/*/index.md` の「次に読むべき記事」
`gen_chapter_progress.py`	各章の 5 サブページ完成度を集計	章 index の `<!-- chapter-progress -->` ブロック
`gen_next_reads.py`	関連 HLD / runbook 候補を frontmatter から拾う	章 index 末尾の関連リンク
`gen_ref_triangle.py`	CLI / CONFIG_DB / YANG の三角関係を抽出	`docs/topics/22-reference-index/*-index.md`
`apply_cli_yang_map.py`	`meta/index/*.json` 上の CLI ↔ YANG 対応を frontmatter に反映	reference / topics ページの `related:`
`inject_glossary_links.py`	用語の最初の出現に glossary リンクを差し込む	全 docs ページの本文

これらは run_all_generators.sh で一括実行できます。drift を疑うときも、まずは run_all_generators.sh && git diff --stat で差分を眺めるのが入口になります。

新 mapping を追加する手順¶

新規 CLI / CONFIG_DB / YANG ページを追加した、あるいは既存 reference の関係を増やしたいときは、次の順に作業します。

reference ページを書く / 更新する: docs/reference/cli/<slug>.md などに新ページを置き、frontmatter の related: に CLI / CONFIG_DB / YANG 三系統の対応を列挙する。
meta/index/*.json を更新する: 自動 Indexer がカバーしていない領域は meta/index/cli.json / config-db.json / yang.json に手動で項目を追加する。slug、title、related_areas を最低限埋める。
apply_cli_yang_map.py を回す: frontmatter ↔ index json の整合を双方向に同期する。CLI/YANG 対応はここで topics 章にも伝播する。
gen_cross_ref.py / gen_ref_triangle.py を回す: 22 章の cli-index.md / config-db-index.md / yang-index.md の表が更新される。
frontmatter_lint.py を回す: 必須キーと enum 値、last_verified の形式を確認する。
mkdocs build --strict で確認: link 切れと anchor 切れを検出する。

このルートを守れば、人手の txt diff を 22 章本文に書き込まずに索引を更新できます。本ページ・cli-index.md ほかは原則 generator の出力で更新する設計です。

CI drift の対応¶

generator の出力と human commit の間に drift が出ることが頻繁にあります。代表的なドリフトと処理パターンは次のとおりです。

chapter-progress の行数差分: サブページに数行追記しただけで「⚠️ プレースホルダ」「✅ 完成」が遷移する。閾値は本文 100 行。意図しない変動は本文修正側で吸収する。
next-reads の HLD 候補リスト変動: 新規ページ追加で関連候補が増減する。CI が gen_next_reads.py --check で drift 検出するため、generator 出力をそのまま PR に含める。
glossary link の重複 / 抜け: inject_glossary_links.py の hash 表記 () と本文の不整合。再実行で正規化する。
coverage 数値の zone drift: verification status の昇格と reference 追加で数値が動く。22 章本文と reference/index の数字が乖離したら本章を引用元へ差し戻す。

drift を恒常的に減らすコツは「人手の編集と generator 出力を同じ PR で混ぜない」「generator 出力だけを含む chore/regenerate-* PR を分けて squash する」の二点です。

CI 側では run_all_checks.sh が drift 検出を担います。失敗が出たら本番ブランチでは generator を再回し、worktree ブランチでは「自分の編集が generator 出力を上書きしていないか」をまず確認してください。git diff main -- meta/index/ で json 側差分があるか見るのが最短ルートです。

drift をゼロにすることは目的ではありません。「drift が出たら復元手順が一行で書ける」「人手編集と generator 出力の境界がコミット単位で読める」ことのほうが本質です。

実運用では月一の Indexer 再回し PR と、機能 PR ごとの generator 再回しを分離する二段運用が安定しています。前者は数十ファイル / 後者は数ファイルの差分にとどまり、review コストが大きく下がります。

章の出口¶

索引そのものを読む → CLI 横断索引 / CONFIG_DB 横断索引 / YANG 横断索引
索引の品質を測る → 品質と gap
索引の実装を読む → 内部実装
索引が指す reference の本体 → reference/index.md