glossary-generator

用語集ジェネレーター

バージョン： 1.0

学習グラフの概念リストから、ISO 11179 準拠の定義を備えた包括的な用語集を生成します。

トークン効率に関する警告

このスキルは大容量のファイル（2,000 行以上）を生成します。予算に限りのある教師ユーザーにとって、実行時間よりもトークンコストのほうがはるかに重要です。

デフォルトの方法：シリアルの Task エージェントを 1 つ使用する。すべての定義を一時ファイルに直接書き込みます。次の理由から、これは最もトークン効率の高い方法です。

• システムプロンプト／ツールの説明にかかるオーバーヘッドが 1 回だけ（約 12K トークン）
• 調整や組み立てのオーバーヘッドがない
• 350 項目の用語集を約 31K トークンで完成させた実績があります（2026-03-14 のベンチマーク）

測定済みのトークンコスト（350 項目のベンチマーク、2026-03-14）

コンポーネント	トークン数	備考
エージェントのオーバーヘッド（システムプロンプト＋ツール）	約 12K	シリアルでは 1 回、並列では 4 回発生
定義の生成（350 項目）	約 19K	不可避の LLM 処理
組み立て（Python スクリプト）	約 700	ごく簡単なプログラミング作業
合計（シリアル）	約 31K

1 項目あたりのトークン数：約 88（合計）、限界コスト約 54（一度限りのオーバーヘッドを差し引いた後）。

限界コストは次のように計算します：（30,788 − 12,000）/ 350 = 約 54 トークン／項目。 これを使って、任意の規模の用語集のコストを見積もれます。

用語集の規模	推定合計トークン数
100 項目	約 17K（オーバーヘッド 12K ＋生成 5.4K）
200 項目	約 23K
350 項目	約 31K（測定値）
500 項目	約 39K

並列実行を絶対に使用してはならない理由

並列エージェントはそれぞれ、約 12K のシステムプロンプトのオーバーヘッドを全額負担します。 用語集の生成では、定義は完全に独立しており、コストを正当化する速度向上の利点はありません。シリアルエージェントは 1 回の Write 呼び出しで全項目を書き込み、約 6 分で完了します。これは十分に許容できる時間です。

方法	エージェントのオーバーヘッド	生成	組み立て	合計	無駄
シリアルエージェント 1 つ（推奨）	約 12K（1 回）	約 19K	約 700	約 31K	—
並列エージェント 4 つ＋スクリプト	約 48K（4 回）	約 19K	約 700	約 68K	＋37K（119%）
並列エージェント 4 つ＋手動の Edit	約 48K（4 回）	約 19K	約 200K	約 267K	＋236K（761%）

並列実行では、品質上の利点がないままトークンコストが2 倍以上になります。 Claude Pro プラン（5 時間あたり約 200K トークンの予算）を利用する教師の場合、シリアル方式では予算の約 16% を使うのに対し、並列では 34%、手動で組み立てると 100% 以上を使います。

用語集の生成に並列エージェントを絶対に使用しないでください。トークンの無駄を正当化できません。

必ずシリアル方式を使用してください。並列方式を選択肢として提示しないでください。

組み立ての手順（並べ替えと最終ファイルの書き込み）では、必ず Python スクリプトを使用してください。Edit／Write ツール呼び出しで用語集の内容を手動で出力してはなりません。 詳細な振り返りについては logs/glossary-generation-very-inefficient.md を参照してください。

目的

このスキルは、学習グラフの概念ラベルを適切な形式の用語集定義に変換することで、インテリジェントな教科書の用語集作成を自動化します。各定義は ISO 11179 のメタデータレジストリ標準に従い、正確で簡潔、他と明確に区別され、循環的でなく、ビジネスルールを含まないものとします。このスキルにより、用語の一貫性を確保し、相互参照を検証し、関連する例を添えた項目をアルファベット順に作成します。

簡潔な定義の後に、その用語が教科書で重要な理由の説明や、その用語の使用例を加えることもできます。

このスキルを使用するタイミング

Learning Graph スキルが完了し、概念リストが確定した後にこのスキルを使用してください。/docs 領域内のすべての Markdown コンテンツをスキャンして、一般的な高校生にはわかりにくい可能性のある単語や表現を探すこともできます。

用語集の作成には、Learning Graph の概念列挙フェーズで作成された、完全でレビュー済みの概念リストが必要です。具体的には、次の場合にこのスキルを実行してください。

• 概念リストのファイルが存在する（通常は docs/learning-graph/02-concept-list-v1.md）
• 概念リストがレビューされ、承認されている
• 学習成果が明確に示されたコース説明が存在する
• 教科書の用語集を作成または更新する準備ができている

ワークフロー

ステップ 1：入力の品質を検証する

定義を生成する前に、概念リストの品質を評価します。

1. 概念リストのファイルを読み込む（通常は docs/learning-graph/02-concept-list-v1.md）
2. 概念ラベルの重複を確認する（目標：重複なし）
3. タイトルケースの書式を確認する（目標：95％以上が準拠）
4. 長さの制約を確認する（目標：98％以上が32文字未満）
5. 概念が明確かどうかを評価する（曖昧な用語がないこと）

品質スコアを算出します（1～100）。

• 90～100：すべての概念が重複せず、書式と長さが適切
• 70～89：ほとんどの概念が基準を満たし、書式に軽微な問題がある
• 50～69：概念の重複や書式の不統一が一部ある
• 50未満：手動レビューが必要な重大な問題がある

ユーザーへの確認が必要な場合：

• スコアが70未満の場合：「概念リストに品質上の問題があります。用語集を生成する前に、レビューして整理しますか？」
• 重複が見つかった場合：「重複する概念が[N]件見つかりました。重複を自動的に削除しますか？それともレビューしますか？」
• 書式の問題がある場合：「書式に問題のある概念が[N]件見つかりました。自動修正しますか？」

ステップ 2：コースの背景情報を読む

コース説明ファイル（docs/course-description.md）と、/docs/**/*.md 内のその他すべての Markdown ファイルを読み、次の内容を把握します。

• 対象読者（例の複雑さを適切に調整するため）
• コースの目標（用語を統一するため）
• 前提条件（背景知識の想定を確認するため）
• 学習成果（概念の使用状況を把握するため）

ステップ 3：単一の逐次実行エージェントを使用して定義を生成する

デフォルトの方法（最もトークン効率が高い）： 定義をすべて生成し、単一の一時ファイルに直接書き込む Task エージェントを1つ起動します。

Task agent prompt:
"Generate ISO 11179-compliant glossary definitions for the following [N] terms.
Write ALL entries as markdown (#### headers with definitions, examples, and
discussion) to the file /tmp/glossary-raw.md using the Write tool.
Each entry uses #### for the term header. Do not return the content in your
response — just confirm the file was written and report the term count.

[Paste the full term list here]

[Paste course description context here for audience level]"

単一のエージェントが、すべての定義を1つのファイルに書き込みます。これにより、システムプロンプトのオーバーヘッドが一度（約12Kトークン）のみとなり、調整コストも発生しません。350語の用語集で約31Kトークン（合計で1語あたり約88トークン、限界コストは1語あたり約54トークン）で実証済みです。

用語集の生成に並列エージェントを使用しないでください。 並列実行を決して使用してはいけない理由については、上記の「トークン効率に関する警告」セクションを参照してください。品質向上がないまま、トークンコストが2倍以上になります。

リスト内の各概念について、ISO 11179 規格に準拠した定義を作成します。

正確さ（25ポイント）： 概念の意味を正確に捉える

• コースの文脈に即して概念を具体的に定義する
• 対象読者に適した用語を使う
• 定義がコースでの概念の使われ方と一致するようにする

簡潔さ（25ポイント）： 定義を短く保つ（目標：20～50語）

• 不要な単語や説明を避ける
• 要点をすばやく示す
• 明確で直接的な表現を使う

独自性（25ポイント）： 各定義を固有のものにし、区別できるようにする

• 他の情報源から定義をコピーしない
• どの2つの定義も似すぎないようにする
• 関連する概念との違いが明確になるようにする

非循環性（25ポイント）： 循環依存を避ける

• 定義内で未定義の用語を参照しない
• 循環する依存関係を作らない（AがBに依存し、BがAに依存する状態）
• 定義には、より簡単で基本的な用語を使う

形式の例：

「Learning Graph」という概念の場合：

#### Learning Graph

A directed graph of concepts that reflects the order that concepts should be learned to master a new concept.

Learning graphs are the foundational data structure use for intelligent textbooks.  They are used to guide
intelligent agents and recommend learning paths for students.

**Example:** In a programming course, the learning graph shows that "Variables" must be understood before "Functions," which must be understood before "Recursion."

ステップ 4：例を追加する（用語の 60～80％）

ほとんどの概念に、関連する例を含めます（目標：60～80％）。

• "例："で始めます（コロンの後に改行しません）
• コースの分野に即した具体例を示します
• 例は簡潔にします（1～2文）
• 混乱を招かず、概念の理解に役立つ例にします

ステップ 5：相互参照を追加する

適切な箇所で、関連用語を参照します。

• 関連する概念には「関連項目：」を使用します
• 対照的な概念には「対比：」を使用します
• 相互参照先の用語がすべて用語集に存在することを確認します
• 各用語の相互参照は1～3件にします

ステップ 6：Python スクリプトを使用して用語集ファイルを組み立てる

重要：Edit／Write ツールの呼び出しで用語集を手動で組み立てないでください。 アルファベット順への並べ替えやファイルの統合は、簡単なプログラミング作業です。LLM にテキストを生成させて手作業で行うと、実際に費用がかかるトークンを100,000個以上無駄にします。

必須の方法： Bash ツールを使用して Python スクリプトを作成・実行し、次の処理を行います。

1. エージェントの出力ファイル（直列処理の場合は /tmp/glossary-raw.md、並列処理の場合は /tmp/glossary-part-*.md）を読み込みます
2. #### ヘッダーで分割して項目を解析します
3. sorted()を使用し、大文字と小文字を区別せずに項目をアルファベット順に並べ替えます
4. 最終的な docs/glossary.md を一度の処理で書き出します

参考スクリプト（必要に応じてパスを調整してください）：

#!/usr/bin/env python3
"""Merge glossary parts into a single sorted glossary."""
import glob, os, re

entries = {}

# Support both serial (single file) and parallel (multiple files)
if os.path.exists('/tmp/glossary-raw.md'):
    sources = ['/tmp/glossary-raw.md']
else:
    sources = sorted(glob.glob('/tmp/glossary-part-*.md'))

for path in sources:
    with open(path) as f:
        content = f.read()
    for block in re.split(r'\n(?=#### )', content):
        block = block.strip()
        m = re.match(r'#### (.+)', block)
        if m:
            entries[m.group(1).strip()] = block

sorted_terms = sorted(entries.keys(), key=lambda t: t.lower())

with open('docs/glossary.md', 'w') as out:
    out.write('# Glossary of Terms\n\n')
    for term in sorted_terms:
        out.write(entries[term] + '\n\n')

print(f"Wrote {len(sorted_terms)} terms to docs/glossary.md")

Bash ツールで python3 /tmp/assemble_glossary.py を実行します。 合計コスト：約500トークン（スクリプト）＋約200トークン（出力）＝約700トークン （Edit 呼び出しで手作業をした場合は200,000トークン以上になります）。

次のことは絶対にしないでください：

• Write または Edit ツールで用語集の項目を直接書き込む
• サブエージェントの出力を Edit ツールの old_string／new_string パラメーターにコピー＆ペーストする
• 項目をアルファベット順に並べて手動で出力する
• Edit 呼び出しで用語集ファイルにセクションを一つずつ追加する

組み立て後のファイルの書式ルール：

• 用語集の用語にはレベル4の見出し（####）のみ使用できます。 用語集内で ## のセクション見出し、### の小見出し、その他のレベルの見出しは使用しないでください。ファイル内で唯一の # 見出しはページタイトル（# Glossary of Terms）です。それ以外はすべて #### にします。
• 用語は大文字と小文字を区別せず、アルファベット順のみで並べます。カテゴリ、分野、トピックごとにまとめないでください。 用語集はフラットなアルファベット順のリストです。区切り線、カテゴリ見出し、テーマ別のグループ分けは設けません。整理の基準はアルファベット順のみです。
• 用語集には --- を含めないでください。不要です。
• 例には「例：」を使用します（太字、コロン付き）。
• 項目間の間隔を統一します（項目間は空行1行）。

ステップ 7：品質レポートを作成する

docs/learning-graph/glossary-quality-report.md を作成し、次の内容を記載します。

ISO 11179 メタデータレジストリ適合性指標：

各定義を5つの基準で評価します（各25点）。

1. 精度：意味を正確に捉えているか
2. 簡潔さ：簡潔か（20～50語）
3. 識別性：独自性があり、他と区別できるか
4. 非循環性：循環依存がないか
5. ビジネスルールの非拘束性：特定のポリシーやルールに依存していないか

全体的な品質指標：

• 定義の平均語数：[X]語
• 4つの基準すべてを満たす定義：[X]％
• 見つかった循環定義：[X]
• 例のカバー率：[X]％
• 相互参照：[X]件、うち無効なもの：[X]件

可読性：

• Flesch-Kincaid の学年レベル：[X]
• 対象読者に適しているか：はい／いいえ

推奨事項：

• 70／100点未満の定義を列挙します
• 修正が必要な循環依存を特定します
• 例が必要な概念を提案します
• 無効な相互参照があれば記載します

ステップ 8：出力を検証する

最終検証を行います。

1. アルファベット順になっていることを確認します（100% の遵守が必須です）
2. すべての相互参照が既存の用語を指していることを確認します
3. 入力リストのすべての概念が含まれていることを確認します
4. Markdown の構文が正しくレンダリングされることを確認します
5. 循環定義がないことを確認します

成功基準：

• 総合品質スコアが 85/100 を超えている
• 循環定義が 0 件である
• アルファベット順の遵守率が 100% である
• 概念リストのすべての用語が含まれている
• Markdown が mkdocs で正しくレンダリングされる

ステップ 9：ナビゲーションを更新する（任意）

mkdocs.yml の nav: に - Glossary: glossary.md がまだない場合は、$BK_HOME/skills/book-installer/references/mkdocs-nav-editing.md に記載されている標準のナビゲーション編集ルールに従い、License/Contact の前の末尾付近に追加します。

ステップ 10：相互参照インデックスを生成する（任意）

セマンティック検索用に docs/learning-graph/glossary-cross-ref.json を作成します。

{
  "terms": [
    {
      "term": "Learning Graph",
      "related_terms": ["Concept Dependency", "Directed Acyclic Graph"],
      "contrasts_with": ["Linear Curriculum"],
      "category": "Educational Technology"
    }
  ]
}

この JSON ファイルにより、将来的に次のような機能を利用できます。

• 用語集全体のセマンティック検索
• 概念の関係性の可視化
• 関連用語の自動提案

品質スコアの基準

以下の評価基準を使って、各定義を採点します（1〜100 点）。

85〜100：優秀

• ISO 11179 の 4 つの基準をすべて満たす（各 20 点以上）
• 適切な長さ（20〜50 語）
• 関連する例を含む
• 明確で曖昧さのない表現
• 循環依存がない

70〜84：良好

• ISO の基準を 3〜4 つ満たす
• 許容できる長さ（15〜60 語）
• 例がない場合がある
• おおむね明確
• 深刻な問題がない

55〜69：許容範囲

• ISO の基準を 2〜3 つ満たす
• 長さに問題がある（短すぎる、または長すぎる）
• 有用な場合でも例がない
• 多少曖昧
• 軽微な循環参照がある

55 未満：要修正

• 複数の ISO 基準を満たしていない
• 長さに重大な問題がある
• 分かりにくい、または循環している
• 文脈が不足している
• 全面的な書き直しが必要

よくある落とし穴と回避策

循環定義：

• 悪い例：「Learning Graph は、学習を示すグラフです。」
• 良い例：「概念を学ぶべき順序を示す、有向グラフです。」

曖昧すぎる定義：

• 悪い例：「教育で使われるものです。」
• 良い例：「概念間の前提関係を示す有向グラフです。」

長すぎる定義：

• 悪い例：「learning graph は、特定の学習成果を達成するために学生が習得すべきさまざまな概念要素の階層的かつ連続的な関係を表すため、教育テクノロジーやインストラクショナルデザインの分野で一般的に使われる、特殊なタイプの有向非巡回グラフ構造です。」
• 良い例：「新しい概念を習得するために学ぶべき概念の順序を示す有向グラフです。」

業務ルール：

• 悪い例：「学生は、依存する概念に進む前に前提条件を完了する必要があります。」
• 良い例：「概念間の前提関係を示す有向グラフです。」

未定義の用語：

• 悪い例：「DAG 構造を使用します」（DAG が用語集にない場合）
• 良い例：「有向非巡回グラフ構造を使用します」

出力ファイルの概要

必須：

1. docs/glossary.md — ISO 11179 に準拠した定義を含む、アルファベット順の用語集

推奨：

2. docs/learning-graph/glossary-quality-report.md — 品質評価と推奨事項

任意：

3. docs/learning-graph/glossary-cross-ref.json — セマンティック検索用の JSON マッピング
4. 用語集へのリンクがない場合の mkdocs.yml ナビゲーションの更新

セッション例

ユーザー：「概念リストから用語集を作成してください」

Claude（このスキルを使用）：

1. 概念リストのファイルと docs/course-description.md を読み込みます（約5Kトークン）
2. 品質を検証します（重複や書式を確認、約1Kトークン）
3. すべての定義を /tmp/glossary-raw.md に書き込む、1つの直列タスクエージェントを起動します（約19Kトークン）
4. Python の組み立てスクリプトを /tmp/assemble_glossary.py に作成します（約500トークン）
5. Bash 経由でスクリプトを実行します。スクリプトは解析、並べ替えを行い、docs/glossary.md に書き込みます（約200トークン）
6. grep -c "^####" docs/glossary.md で用語数を確認します（約100トークン）
7. 必要に応じて mkdocs.yml のナビゲーションを更新します（約500トークン）
8. 「350語を含む用語集を作成しました。70%の用語に例を追加しました」と報告します。

測定結果（2026-03-14）： 350語を生成し、合計約31Kトークンでまとめました。 1語あたり約88トークン（エージェントのオーバーヘッドを差し引くと約54トークン）で、 これが可能な限り最も効率的な方法です。

重要： サブエージェントはテキストを生成します（LLM による作業は避けられません）。組み立ては プログラミング作業です。Edit ツールではなく sorted() を使用してください。並列エージェントは絶対に使用しないでください。