Skip to content

概念管理ガイド（Concept Management）

KB Gardener(kb-gardener) packageにおける、概念レジストリ（docs/registry/concepts.yaml）のメンテナンス手順と仕組み。

概念体系の基本設計（SKOS プロパティ、階層、ライフサイクル）は README.md の「KB 管理の概念」を参照。

概要

概念管理には 2 つの経路がある:

  1. パイプライン経由 — kb-gardener pipeline の plan ステップで、ドキュメント分類時に既存概念で表現できないトピックがあれば concept_proposals として新概念を提案。続く concept-apply ステップで concepts.yaml に追加
  2. レビュー経路 — concept-review + concept-review-apply で、タクソノミー全体を LLM がレビューし、統合・廃止・新規追加・リタグを提案
┌──── パイプライン経路 ──────────────────────────────────────────┐
│ inventory → lint → plan → apply → concept-apply → verify     │
│                      │                    │                    │
│              concept_proposals を    concepts.yaml に          │
│              plan.json に出力       新概念を追加               │
└──────────────────────────────────────────────────────────────┘
                                            │
                   docs/registry/concepts.yaml
                                            │
┌──── レビュー経路 ────────────────────────────────────────────┐
│ concept-review → concept-review-apply                       │
│                                                              │
│ タクソノミー全体を LLM がレビューし                            │
│ merge / deprecate / add / retag を適用                       │
└──────────────────────────────────────────────────────────────┘
                                            │
                                            ▼
                              concept-viz → registry/index.md

concepts と tags の同期

frontmatter の concepts（ID リスト）と tags（prefLabel リスト）は常に 1:1 対応する。

# concepts.yaml
- id: "infrastructure-management"
  prefLabel: "Infrastructure Management"

# → ページ frontmatter
concepts: [infrastructure-management]
tags: [Infrastructure Management]

すべての自動操作（pipeline apply、concept-review-apply）が両方を同時に更新する。手動で frontmatter を編集する場合も、必ず concepts と tags の両方を揃えること。

レビューワークフロー

1. concept-review — タクソノミーレビュー

kb-gardener concept-review [-v] [--sample-size N]

LLM がドキュメントをサンプリングし、タクソノミーの改善提案を生成する。

処理の流れ:

  1. concepts.yaml をコンパクト形式（pipe-delimited）に変換
  2. 全ドキュメントからセクション別にサンプリング（under-tagged ページ優先）
  3. 概念の使用統計（上位 20 + orphan 一覧）を集計
  4. Claude API に送信し、構造化出力を取得
  5. .kb-gardener/concept_review.json に保存

サンプリング戦略:

  • セクション（meetings, platform, packages, standards, ops/runbooks, inbox）ごとに --sample-size（デフォルト 10）ページ
  • 各セクションで半数は概念数が少ないページ、残りはランダム
  • body preview は先頭 200 文字に制限（トークン節約）

出力（concept_review.json）:

フィールド 内容
new_concepts[] 新規追加すべき概念（ID, label, broader, related, definition, category, confidence）
deprecations[] 廃止すべき概念（ID, reason, replaced_by, confidence）
merges[] 統合すべき概念（source_ids, target_id, confidence）
retags[] サンプルページのリタグ提案（path, add/remove_concepts, confidence）
summary レビュー総括

各提案に confidence（0.0〜1.0）が付与される。

2. concept-review-apply — 提案の適用

# まず dry-run で確認
kb-gardener concept-review-apply --dry-run --min-confidence 0.85 -v

# 適用
kb-gardener concept-review-apply --min-confidence 0.85 -v

適用順序:

# 操作 内容
1 merge ソース概念を deprecated にし、全ドキュメントの参照をターゲットに書き換え
2 deprecate 概念を deprecated にし、replaced_by があればドキュメント参照を書き換え
3 add 新概念を concepts.yaml に追加
4 retag サンプルページの concepts/tags を追加・削除
5 viz concept-viz を自動実行し registry/index.md を再生成

--min-confidence で信頼度の低い提案をスキップできる。推奨値は 0.85。

参照の書き換え:

merge/deprecate 時は docs/ 配下の全 .md ファイルの frontmatter を走査し、concepts と tags の両方を自動的に書き換える。

3. concept-viz — 可視化の再生成

kb-gardener concept-viz

concepts.yaml から docs/registry/index.md を再生成する。LLM は使わない。

生成内容:

  • 概念階層ツリー — broader に基づくマークダウンネストリスト。related はインラインで (→ ...) 表記
  • 概念一覧テーブル — 全概念（deprecated 含む）の一覧

ツリーには active 概念のみ表示。テーブルには deprecated も含めて全概念を表示する。

手動での概念管理

概念の追加

docs/registry/concepts.yaml に直接エントリを追加する:

- id: "new-concept"
  prefLabel: "New Concept"
  altLabel:
    - "新しい概念"
  broader: "parent-concept"   # null ならトップレベル
  related:
    - "related-concept-a"
  definition: "Brief description of the concept."

追加後:

kb-gardener concept-viz   # index.md を再生成
kb-gardener lint          # 参照整合性を確認（DANGLING_BROADER 等）

概念の廃止

- id: "old-concept"
  status: "deprecated"
  replaced_by: "new-concept"   # 後継がない場合は null

廃止後、ドキュメント側の参照を手動で更新するか、次回の lint → plan → apply で自動修正される（DEPRECATED_CONCEPT 警告）。

概念の統合

2 つの概念を統合する場合は concept-review-apply の merge 機能を使うか、手動で:

  1. ソース概念を deprecated + replaced_by: target-id に変更
  2. ソース概念を参照しているページの frontmatter を更新（concepts + tags 両方）
  3. concept-viz で index.md を再生成

トークン管理

concept-review は Claude API を呼び出すため、プロンプトサイズに注意が必要。

最適化:

  • concepts.yaml は pipe-delimited 形式に圧縮（YAML のまま送ると 3〜4 倍のトークン消費）
  • body preview は 200 文字に制限
  • 使用統計は上位 20 概念 + orphan 一覧のみ

実行時にトークン数が表示される:

Prompt: 12,893 tokens (127 concepts, 52/91 pages sampled)

概念数が増えた場合は --sample-size を下げてトークンを節約できる。

ファイル一覧

ファイル 役割
docs/registry/concepts.yaml 概念定義（SKOS サブセット）
docs/registry/index.md 概念ツリー + 一覧テーブル（concept-viz が生成）
.kb-gardener/concept_review.json レビュー提案（concept-review が生成）
src/kb_gardener/steps/concept_viz_step.py ツリー + テーブル生成
src/kb_gardener/steps/concept_review_step.py LLM レビュー
src/kb_gardener/steps/concept_review_apply_step.py 提案適用
src/kb_gardener/steps/concept_apply_step.py パイプライン経由の概念追加