faq-generator

FAQ ジェネレーター

バージョン： 1.0

教科書のコンテンツから、カテゴリ分けされた包括的な FAQ と、チャットボット向けの JSON エクスポートを生成します。FAQ をファイル docs/faq.md に配置してください。セッションの結果を logs/faq.md に記録してください。

目的

このスキルは、コースのコンテンツ、学習グラフ、用語集の用語を分析して、関連する質問と回答を生成することで、学習用教科書の FAQ 作成を自動化します。質問をカテゴリと難易度別に整理し、ブルームのタキソノミーに基づく認知レベルの分布を確保します。また、ソースコンテンツへのリンク付きの回答を提供し、RAG システムとの統合に対応した構造化 JSON データをエクスポートします。

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

次の成果物がそろった後に、このスキルを使用してください。

1. 品質スコアが 70 を超えるコースの説明が確定している
2. 学習グラフが作成されている
3. 用語集が生成されている
4. 章のコンテンツが少なくとも 30％執筆されている

これらの前提条件が満たされていれば、FAQ ジェネレーターが有意義で関連性の高い質問を作成するための十分なコンテキストを確保できます。次の場合に、このスキルを実行してください。

• 新しい教科書の初期 FAQ を作成する
• コンテンツを大幅に追加した後に FAQ を更新する
• チャットボットや AI アシスタントとの統合に向けてコンテンツを準備する
• 既存コンテンツの知識のギャップを特定する

Markdown の書式設定

1. FAQ のタイトルには Markdown の見出しレベル 1（#）を使用します
2. 各カテゴリには Markdown の見出しレベル 2（##）を使用します
3. 個々の質問には Markdown の見出しレベル 3（###）を使用します
4. 回答は本文に記載します

スキルの参照セクションにある faq-template.md をテンプレートとして使用してください。

重要なルール：アンカーリンクは禁止

!!! warning "アンカーリンクは絶対に使用しないでください" すべてのリンクはファイルのみを参照し、# アンカーフラグメントを含めないでください。

アンカーリンク（`file.md#section-name`）は、次の理由で頻繁に機能しなくなります。

- コンテンツの編集時にセクション見出しが変わる
- アンカーでは大文字と小文字、および空白が区別される
- MkDocs によるアンカーの自動生成は予測できない
- アンカーが壊れるとビルド警告が発生し、ユーザーを混乱させる

✅ **正しい例：** `[オームの法則を参照](chapters/02-ohms-law/index.md)`

❌ **誤った例：** `[オームの法則を参照](chapters/02-ohms-law/index.md#series-circuits)`

ワークフロー

ステップ 1：コンテンツの完成度を評価する

FAQ を生成できるか判断するため、コンテンツの完成度スコア（1～100）を計算します。

必須の入力：

1. docs/course-description.md を読みます

   • 確認項目：タイトル、対象読者、前提条件、学習成果
   • ブルームのタキソノミーに基づく学習成果が含まれていることを確認します
   • スコア：完全であれば 25 点

2. docs/learning-graph/03-concept-dependencies.csv を読みます

   • DAG 構造を検証します（循環がないこと）
   • 概念と依存関係の数を数えます
   • スコア：適切に接続された有効な DAG であれば 25 点

3. docs/glossary.md を読みます

   • 用語数を数えます（50 以上＝良好、100 以上＝優良）
   • スコア：100 以上は 15 点、50～99 は 10 点、50 未満は 5 点

4. すべての docs/**/*.md ファイルをスキャンします

   • 総単語数を計算します
   • 目標：包括的な FAQ には 10,000 語以上
   • スコア：10,000 語以上は 20 点、5,000～10,000 語は 15 点、5,000 語未満は 10 点

5. 概念のカバー率を計算します

   • 学習グラフの概念のうち、関連する章のコンテンツがあるものは何％ですか？
   • スコア：80％以上は 15 点、60～79％は 10 点、60％未満は 5 点

コンテンツ完成度スコアの範囲：

• 90～100：すべての入力がそろっており、品質も高い
• 70～89：主要な入力はそろっているが、一部のコンテンツに不足がある
• 50～69：任意の入力が欠けている、または単語数が少ない
• 50 未満：重要な入力が欠けている

ユーザーへの確認条件：

• スコアが 60 未満：「FAQ 生成に利用できるコンテンツが限られています。基本的な FAQ を作成しますか、それともコンテンツが増えるまで待ちますか？」
• 用語集がない：「用語集が見つかりません。FAQ をそのまま生成しますか（技術的な質問は限られます）。それとも、先に用語集を作成しますか？」
• 単語数が少ない：「コンテンツは [N] 語しか見つかりませんでした。FAQ の品質が限られる可能性があります。続行しますか？」

ユーザーがスコア 60 未満での続行に同意した場合は、FAQ を生成します。ただし、コンテンツが限られていることについて、品質レポートに免責事項を記載してください。

ステップ 2：質問候補となる内容を分析する

すべてのコンテンツソースを読み、よくある質問のパターンを特定します。

コースの説明から：

• 「このコースでは何を学びますか？」（対象範囲）
• 「このコースはどのような人を対象としていますか？」（対象者）
• 「何を学べますか？」（学習成果）
• 「事前に何を知っておく必要がありますか？」（前提条件）

学習グラフから：

• 「[概念] とは何ですか？」（定義に関する質問）
• 「[概念 A] は [概念 B] とどのように関連していますか？」（関係性に関する質問）
• 「[概念] を学ぶ前に、何を知っておく必要がありますか？」（前提条件に関する質問）
• 「[概念] の次に学ぶのは何ですか？」（学習の進行に関する質問）

用語集から：

• 「[用語] はどういう意味ですか？」（用語に関する質問）
• 「[用語 A] と [用語 B] の違いは何ですか？」（比較に関する質問）
• 「[用語] の例を挙げてもらえますか？」（応用に関する質問）

章の内容から：

• 繰り返し取り上げられるテーマやトピックを特定する
• 学習者が苦労する可能性のある分野（複雑な概念）を記録する
• 記載されている場合は、よくある誤解を抽出する
• 実践的な応用例を見つける

既存の FAQ（ある場合）から：

• docs/faq.md が存在する場合は、内容を確認する
• 手動で編集された質問を保持する
• 新たに生成した質問と統合する
• 重複を削除し、競合する場合は手動で作成されたバージョンを残す

ステップ 3：質問のカテゴリーを作成する

学習の進行に沿った標準的なカテゴリーを 6 つ作成します。各ブルームのタキソノミーレベルに応じた質問の書き方（質問の書き出し、回答の特徴、よくある間違い）の詳しいガイダンスは、標準リファレンスの $BK_HOME/skills/chapter-content-generator/references/blooms-taxonomy.md を参照してください。

1. 学習を始めるための質問（10～15 問）

目標とするブルームのレベル：記憶 60％、理解 40％

• コースの概要と目標
• 前提条件と準備
• 教科書の使い方
• ナビゲーションと構成
• 必要な学習時間と難易度

2. 中核概念に関する質問（20～30 問）

目標とするブルームのレベル：記憶 20％、理解 40％、応用 30％、分析 10％

• 学習グラフの重要な概念（中心性の高いノードを優先）
• 基本原則
• 概念間の関係と依存関係
• 概念がどのように積み重なっていくか

3. 技術的な詳細に関する質問（15～25 問）

目標とするブルームのレベル：記憶 30％、理解 40％、応用 20％、分析 10％

• 用語集の用語
• 定義と説明
• 技術的な比較
• 仕様の詳細

4. よくある課題（10～15 問）

目標とするブルームのレベル：記憶 10％、理解 30％、応用 40％、分析 20％

• より詳しい説明が必要な難しい概念
• よくある誤解
• トラブルシューティングのシナリオ
• エラーの解決

5. ベストプラクティスに関する質問（10～15 問）

目標とするブルームのレベル：理解 10％、応用 40％、分析 30％、評価 15％、創造 5％

• 概念を効果的に応用する方法
• 推奨されるアプローチ
• 特定の手法を使う場面
• 実社会での応用

6. 発展的なトピック（5～10 問）

目標とするブルームのレベル：応用 10％、分析 30％、評価 30％、創造 30％

• 複雑な統合
• エッジケース
• パフォーマンスの最適化
• 今後の展望

ステップ 4：質問と回答を生成する

各カテゴリについて、以下のガイドラインに従って質問を生成します。

質問の形式：

• レベル 2 の見出し（##）を使用します
• 実際の質問として記述します（? で終わります）
• 具体的で検索しやすい質問にします
• 用語集の用語を使用します
• 質問は簡潔にします（5〜15 語）

回答の形式：

• 各質問にレベル 3 の Markdown 見出し（###）を使用します
• 完結した、単独で意味が通じる回答を記述します
• 回答の 40% に例を含めます
• 関連セクションへのリンクを含めます（目標：60% 以上にリンク）
• 目標の長さ：100〜300 語
• 明確で直接的な表現を使用します
• 質問に十分に答えます

ブルームの分類法に関するガイドライン：

**記憶：**事実、用語、基本概念を想起します

• 「[概念] とは何ですか？」
• 「[用語] は何を意味しますか？」
• 「[システム] の構成要素は何ですか？」

**理解：**考え方や概念を説明します

• 「[概念] はどのように機能しますか？」
• 「[概念] が重要なのはなぜですか？」
• 「[A] と [B] の違いは何ですか？」

**応用：**新しい状況で情報を活用します

• 「[タスク] はどのように実行しますか？」
• 「どのような場合に [手法] を使用すべきですか？」
• 「実践における [概念] の例は何ですか？」

**分析：**考え方どうしのつながりを導き出します

• 「[A] と [B] にはどのような関係がありますか？」
• 「[概念] は [別の概念] とどのように関連していますか？」
• 「[問題] の根本的な原因は何ですか？」

**評価：**判断や立場を根拠をもって示します

• 「[状況] ではどの方法が最適ですか？」
• 「[手法] のトレードオフは何ですか？」
• 「[A] と [B] をどのように選べばよいですか？」

**創造：**新しい、または独自の成果物を作ります

• 「要件を満たす [システム] はどのように設計できますか？」
• 「[概念] を組み合わせる最善の方法は何ですか？」
• 「[手法] を [新しいコンテキスト] にどのように適用できますか？」

回答品質チェックリスト：

• タイトル、カテゴリ、質問に正しい Markdown 見出しを使用している
• 質問に直接答えている
• 用語集の用語を一貫して使用している
• 概念が抽象的な場合は例を含めている（目標 40%）
• 関連する章ファイルにリンクしている（目標 60%）— アンカーフラグメントは使用しない
• 適切な長さである（100〜300 語）
• 対象読者にとって明確で理解しやすい
• 教科書の内容に基づいて正確である
• 用語集で定義されていない専門用語を使用していない
• # アンカー付きリンクが一切ない（必須要件）

ステップ 5：FAQ ファイルを作成する

適切な構造で docs/faq.md を生成します。

# [Course Name] FAQ

## Getting Started Questions

### What is this course about?

[Answer with overview, linking to course description]

### Who is this course for?

[Answer describing target audience]

[Continue with 10-15 Getting Started questions...]

## Core Concepts

### What is a [Key Concept]?

[Answer with definition and example, linking to chapter]

[Continue with 20-30 Core Concepts questions...]

## Technical Detail Questions

[Continue with terminology and technical questions...]

## Common Challenge Questions

[Continue with troubleshooting questions...]

## Best Practice Questions

[Continue with application questions...]

## Advanced Topic Questions

[Continue with advanced questions...]

書式要件：

• タイトルにはレベル 1 の見出しを使用します
• カテゴリ名にはレベル 2 の見出しを使用します
• 質問にはレベル 3 の見出しを使用します
• 回答には本文テキストを使用します
• 章ファイルへの Markdown リンクを使用します：[テキスト](path.md) — アンカーリンクは絶対に使用しないでください
• 強調には太字を使用します：**重要な用語**
• コードにはコードブロックを使用します：` language
• 一貫した空白を保ちます

重要：アンカーリンクを使用しないこと

リンクにアンカーフラグメント（#section-name）を絶対に追加しないでください。アンカーは次の理由で頻繁に機能しなくなります。

• 編集中にセクション見出しが変更される
• アンカーは大文字と小文字、および空白の違いを区別する
• MkDocs のアンカー生成は予測できない
• アンカー切れはビルド警告を引き起こし、ユーザーを混乱させる

✅ 正しい例： [オームの法則](chapters/02-ohms-law/index.md) ❌ 誤った例： [オームの法則](chapters/02-ohms-law/index.md#series-circuits)

章ファイルのみをリンクしてください。ページ内の移動はユーザー自身が行えます。

ステップ 6：チャットボット学習用 JSON を生成する

RAG 統合のために docs/learning-graph/faq-chatbot-training.json を作成します。

{
  "faq_version": "1.0",
  "generated_date": "YYYY-MM-DD",
  "source_textbook": "Course Name",
  "total_questions": 87,
  "questions": [
    {
      "id": "faq-001",
      "category": "Getting Started",
      "question": "What is this course about?",
      "answer": "Full answer text here...",
      "bloom_level": "Understand",
      "difficulty": "easy",
      "concepts": ["Course Overview", "Learning Objectives"],
      "keywords": ["course", "overview", "objectives", "goals"],
      "source_links": [
        "docs/course-description.md",
        "docs/index.md"
      ],
      "has_example": false,
      "word_count": 142
    },
    {
      "id": "faq-002",
      "category": "Core Concepts",
      "question": "What is a Learning Graph?",
      "answer": "A Learning Graph is...",
      "bloom_level": "Understand",
      "difficulty": "medium",
      "concepts": ["Learning Graph", "Concept Dependency"],
      "keywords": ["learning graph", "dependencies", "prerequisites"],
      "source_links": [
        "docs/concepts/learning-graph.md",
        "docs/glossary.md"
      ],
      "has_example": true,
      "word_count": 218
    }
  ]
}

JSON スキーマの要件：

• 各質問に一意の ID がある（faq-001、faq-002 など）
• カテゴリは標準の 6 カテゴリのいずれかと一致する
• ブルームレベルは 6 段階の分類法に基づく
• 難易度：easy、medium、hard
• 概念のリストは学習グラフから取得する
• 検索を最適化するためのキーワード
• 元のコンテンツへのソースリンク
• 例の有無を示すブール値フラグ
• 回答の語数

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

docs/learning-graph/faq-quality-report.md を作成します。

# FAQ Quality Report

Generated: YYYY-MM-DD

## Overall Statistics

- **Total Questions:** 87
- **Overall Quality Score:** 82/100
- **Content Completeness Score:** 78/100
- **Concept Coverage:** 73% (145/198 concepts)

## Category Breakdown

### Getting Started
- Questions: 12
- Avg Bloom's Level: Remember/Understand
- Avg Word Count: 156

[Continue for all categories...]

## Bloom's Taxonomy Distribution

Actual vs Target:

| Level | Actual | Target | Deviation |
|-------|--------|--------|-----------|
| Remember | 18% | 20% | -2% ✓ |
| Understand | 32% | 30% | +2% ✓ |
| Apply | 24% | 25% | -1% ✓ |
| Analyze | 16% | 15% | +1% ✓ |
| Evaluate | 7% | 7% | 0% ✓ |
| Create | 3% | 3% | 0% ✓ |

Overall Bloom's Score: 25/25 (excellent distribution)

## Answer Quality Analysis

- **Examples:** 38/87 (44%) - Target: 40%+ ✓
- **Links:** 54/87 (62%) - Target: 60%+ ✓
- **Avg Length:** 187 words - Target: 100-300 ✓
- **Complete Answers:** 87/87 (100%) ✓

Answer Quality Score: 24/25

## Concept Coverage

**Covered (145 concepts):** [list]

**Not Covered (53 concepts):**
- [Concept 1] - Priority: High (high centrality in learning graph)
- [Concept 2] - Priority: Medium
- [Concept 3] - Priority: Low

Coverage Score: 22/30 (73% coverage)

## Organization Quality

- Logical categorization: ✓
- Progressive difficulty: ✓
- No duplicates: ✓
- Clear questions: ✓

Organization Score: 20/20

## Overall Quality Score: 82/100

- Coverage: 22/30
- Bloom's Distribution: 25/25
- Answer Quality: 24/25
- Organization: 20/20

## Recommendations

### High Priority
1. Add questions for high-centrality concepts: [list top 10]
2. Slightly increase Remember-level questions (+2%)

### Medium Priority
1. Add examples to 3 more answers (to reach 47%)
2. Link 5 more answers to source content

### Low Priority
1. Consider adding 2-3 more Advanced Topics questions
2. Review question phrasing for searchability

## Suggested Additional Questions

Based on concept gaps, consider adding:

1. "What is [Uncovered Concept 1]?" (Core Concepts)
2. "How does [Uncovered Concept 2] work?" (Technical Details)
[Continue with top 10 suggestions...]

ステップ 8：カバレッジギャップレポートを生成する

docs/learning-graph/faq-coverage-gaps.md を作成します。

# FAQ Coverage Gaps

Concepts from learning graph not covered in FAQ.

## Critical Gaps (High Priority)

High-centrality concepts (many dependencies) without FAQ coverage:

1. **[Concept Name]**
   - Centrality: High (12 dependencies)
   - Category: Core Concepts
   - Suggested Question: "What is [Concept] and why is it important?"

[Continue for all high-priority gaps...]

## Medium Priority Gaps

Moderate-centrality concepts without FAQ coverage:

[Continue...]

## Low Priority Gaps

Leaf nodes or advanced concepts without FAQ coverage:

[Continue...]

## Recommendations

1. Add questions for all critical gaps (15 concepts)
2. Consider adding questions for medium priority (23 concepts)
3. Low priority can be addressed in future updates (15 concepts)

ステップ 9：出力品質を検証する

包括的な検証を実施します。

1. 重複チェック：

• すべての質問を確認し、重複がないか調べます
• 類似度が 80％を超える類似質問がないか確認します
• 重複が見つかった場合は報告します

2. リンクの検証：

• 回答からすべての Markdown リンクを抽出します
• # アンカーフラグメントを含むリンクはすべて却下します。これらは削除する必要があります
• 各リンク先のファイルが存在するか確認します
• 壊れたリンクを報告します
• リンク先はファイルのみとします（例：chapters/01-intro/index.md）。アンカーは付けないでください

3. ブルームの分類の分布：

• すべての質問における実際の分布を算出します
• 目標分布と比較します
• 乖離に基づいて評価します（±10％は許容範囲）

4. 読解レベル：

• 回答の Flesch-Kincaid 学年レベルを算出します
• 対象読者に適切か確認します
• 難しすぎる、または簡単すぎる回答にフラグを付けます

5. 回答の完全性：

• 各回答が質問に対応しているか確認します
• 不完全な回答や部分的な回答がないか確認します
• 適切な文脈が示されているか確認します

6. 技術的な正確性：

• 用語を用語集と照合します
• 章の内容との一貫性を確認します
• 矛盾や誤りにフラグを付けます

成功基準：

• 総合品質スコアが 75／100 を超えている
• 40 問以上を生成している
• 概念のカバレッジが 60％以上である
• ブルームの分類がバランスよく分布している（±15％以内）
• すべての回答に出典が記載されている
• チャットボットの JSON がスキーマに適合している
• 質問に重複がない
• すべての内部リンクが有効である（ファイルが存在する）
• アンカーリンクが一切ない。リンクに # フラグメントを含めない

ステップ 10：mkdocs.yml のナビゲーションセクションを更新する（任意）

nav: に - FAQ: faq.md がまだない場合は、末尾近く（用語集の隣）に追加し、品質レポート（faq-quality-report.md、faq-coverage-gaps.md）があれば Learning Graph: の下に追加します。正規のナビゲーション編集ルールについては、$BK_HOME/skills/book-installer/references/mkdocs-nav-editing.md に従ってください。

品質スコアの基準

この評価基準を使用して、FAQ の総合品質スコア（1～100）を算出します。

カバレッジ（30 点）：

• 概念のカバレッジが 80％以上：30 点
• 70～79％：25 点
• 60～69％：20 点
• 50～59％：15 点
• 50％未満：10 点

ブルームの分類の分布（25 点）：

各レベルの目標値との乖離を算出し、絶対偏差の合計を求めます。

• 乖離の合計が 0～10％：25 点
• 乖離の合計が 11～20％：20 点
• 乖離の合計が 21～30％：15 点
• 乖離の合計が 30％を超える：10 点

回答の品質（25 点）：

• 例：40％以上＝7 点、30～39％＝5 点、30％未満＝3 点
• リンク：60％以上＝7 点、50～59％＝5 点、50％未満＝3 点
• 長さ：平均 100～300 語＝6 点、許容範囲内＝4 点
• 完全性：100％＝5 点、95～99％＝4 点、95％未満＝2 点

構成（20 点）：

• 論理的な分類：5 点
• 難易度の段階的な構成：5 点
• 重複なし：5 点
• 質問が明確：5 点

避けるべきよくある落とし穴

質問の重複：

• 異なるカテゴリーで同じ質問をしないでください
• 関連する概念については、質問の言い回しを変えてください
• 類似する質問は、1 つの包括的な回答にまとめてください

不完全な回答：

• 質問への回答を途中で終わらせないでください
• 要約なしに「詳細は第 X 章を参照」としないでください
• 必ず、それ単独で理解できる文脈を示してください

リンクの不足：

• 回答から出典コンテンツへのリンクを忘れずに付けてください
• 章のファイルにのみリンクし、アンカーフラグメント（#section-name）は絶対に使用しないでください
• 確定する前に、すべてのリンク先にファイルが存在することを確認してください

壊れたアンカーリンク：

• file.md#section-name のようなアンカーリンクは絶対に使用しないでください
• ヘッダーが編集、改名、再構成されると、アンカーは機能しなくなります
• 章またはページのファイルのみをリンク先にしてください：file.md
• これは厳守事項であり、例外はありません

質問の表現が不適切：

• 「どのように動作しますか？」のような曖昧な質問は避けてください
• 用語集にある具体的な用語を使用してください
• 検索しやすい質問にしてください

ブルームの分類の偏り：

• 「記憶する」「理解する」に偏りすぎないでください
• 高次の思考を必要とする質問を含めてください
• 6 つのレベルすべてをバランスよく取り入れてください

出力ファイルの概要

必須：

1. docs/faq.md - カテゴリ別の質問と回答を含むFAQ

推奨：

2. docs/learning-graph/faq-quality-report.md - 品質指標と推奨事項
3. docs/learning-graph/faq-chatbot-training.json - RAG システム用の構造化データ

任意：

4. docs/learning-graph/faq-coverage-gaps.md - FAQでカバーされていない概念
5. FAQへのリンクがない場合は、mkdocs.yml のナビゲーションを更新

セッション例

ユーザー：「教科書のFAQを作成して」

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

1. コンテンツの完全性を評価します（スコア：78/100）
2. コースの説明、学習グラフ、用語集、各章を読み込みます
3. 質問の候補を特定します
4. 6つのカテゴリにわたる87個の質問を作成します
5. 例を44％、リンクを62％含む回答を作成します
6. チャットボットのトレーニング用JSONをエクスポートします
7. 品質レポートを作成します（スコア：82/100）
8. カバレッジの不足箇所に関するレポートを作成します（未カバーの概念：53個）
9. 次のように報告します：「73％の概念をカバーする87個の質問を含むFAQを作成しました。全体的な品質：82/100。38個の例と54個のリンクを追加しました。推奨事項については品質レポートをご覧ください。」