docs/question_quality_guide.md

QuestionDatabase 高品質化ガイドライン

国語・数学の高品質化経験に基づく標準手順

---

1. 概要

1.1 目的

• 問題データの品質向上（重複削除、フォーマット統一、難易度調整）
• 各ジャンルの高品質な問題セットを作成
• LLMを活用した効率的な編集作業
• Gemini APIによる学術的整合性チェック

1.2 対象ファイル

knowledge/v1.8.1/
├── jp/JP01-JP06.json   (国語: 6ファイル)
├── math/MA01-MA10.json (数学: 10ファイル)
├── sci/SC01-SC10.json  (理科: 10ファイル)
└── soc/SO01-SO10.json  (社会: 10ファイル)

---

2. 品質基準

2.1 問題数

• 目標: 各ファイル100問
• 不足分は対応する教材（knowledge/*.md）から新規作成

2.2 難易度分布（3:5:2）

難易度	割合	問題数	基準
基本	30%	30問	小学校レベル、日常的な内容
標準	50%	50問	中学校レベル、応用的な理解が必要
応用	20%	20問	高校レベル以上、発展的な内容

2.3 フォーマット統一

{
  "answer_id": "xx_001",
  "answer": "解答（ふりがな）",
  "question_hint": "「〇〇___」の漢字",
  "difficulty": "基本|標準|応用",
  "source_context": "完全な文（マークダウンなし）"
}

フィールド規則

フィールド	規則
answer_id	{category}_{3桁連番} (例: jp_001, ma_001)
answer	解答文字列（ふりがなは括弧内に）
question_hint	穴埋め形式「〇〇___」、末尾に「の漢字」等の指示
difficulty	基本/標準/応用 の3択
source_context	完全な文、マークダウン記号なし

---

3. 高品質化手順

Phase 1: 現状分析

# 1. 問題数確認
len(questions)

# 2. 重複確認（解答の正規化）
def normalize(answer):
    # ふりがな除去して比較
    return re.sub(r'[（(][^)）]+[)）]', '', answer)

# 3. フォーマット不整合確認
# - question_hint形式
# - マークダウン残存
# - source_context切れ

Phase 2: 重複統合

1. 同一解答の問題をグループ化
2. 最良のquestion_hintを選定
3. 1問に統合、残りを削除

選定基準:

• 文脈が明確
• 穴埋め位置が適切
• source_contextが完全

Phase 3: 新規問題作成

1. 対応する教材（knowledge/*.md）を参照
2. 教材から問題素材を抽出
3. フォーマットに従って問題化

優先素材:

• 同訓異字・同音異義語（国語）
• 公式・定理の応用（数学）
• 実験・観察の考察（理科）
• 年号・人物・地理（社会）

Phase 4: 難易度調整

# 現状カウント
counts = {"基本": 0, "標準": 0, "応用": 0}

# 目標: 30:50:20
target = {"基本": 30, "標準": 50, "応用": 20}

# 差分を計算し調整

Phase 5: ID再割り当て・保存

# 連番割り当て
for i, q in enumerate(questions, 1):
    q["answer_id"] = f"{prefix}_{i:03d}"

# JSON保存
with open(path, 'w', encoding='utf-8') as f:
    json.dump(questions, f, ensure_ascii=False, indent=2)

---

4. 品質チェックリスト

必須チェック

• 問題数 = 100問
• 重複なし（100ユニーク解答）
• answer_id連番（xx_001〜xx_100）
• 難易度分布: 30:50:20
• JSON構文正常

フォーマットチェック

• question_hint: 「〇〇___」形式
• answer: 適切な形式
• source_context: マークダウンなし
• 全フィールド存在

内容チェック

• 問題として成立している
• 解答が一意に定まる
• 難易度が適切

---

5. カテゴリ別注意点

国語（JP01-JP06）

カテゴリ	内容	教材
JP01	漢字の読み書き	japanese.md
JP02	語彙・慣用句	japanese.md
JP03	文法	japanese.md
JP04	敬語	japanese.md
JP05	文学史	japanese.md
JP06	作文・表現	japanese.md

注意: 同訓異字・同音異義語は文脈で区別できるようにする

数学（MA01-MA10）

カテゴリ	内容	問題数
MA01	四則演算・計算の基礎	40問
MA02	単位換算・速さ	40問
MA03	円周率・面積	40問
MA04	比例・割合	40問
MA05	濃度・食塩水	40問
MA06	方程式	40問
MA07	図形・体積	40問
MA08	時間計算	40問
MA09	旅人算・追いかけ算	40問
MA10	応用問題・複合問題	40問

重要（中学受験向け）:

• ★ 方程式（xを使った式）は絶対に使わない ★
• 特殊算による解法（つるかめ算、旅人算、仕事算、ニュートン算など）
• 計算の工夫（分配法則、逆算、比の利用）
• 線分図、面積図、ダイヤグラムによる解法
• 和差算、消去算、比と割合の考え方

理科（SC01-SC10）

注意: 単位は正確に記述

社会（SO01-SO10）

注意: 年号・人名の表記を統一

---

6. JP01高品質化の実績

Before

• 問題数: 103問
• ユニーク解答: 39種類（重複率62%）
• フォーマット: 3パターン混在
• マークダウン残存あり

After

• 問題数: 100問
• ユニーク解答: 100種類（重複0%）
• フォーマット: 統一済み
• 難易度: 30:50:20

作業内容

1. 103問 → 29問に統合（重複削除）
2. japanese.mdから71問新規作成
3. 難易度を3:5:2に調整
4. フォーマット統一・マークダウン除去

---

7. Gemini API添削

7.1 目的

• SUBAGENT高品質化後の学術的整合性チェック
• source_context、answer、question_hintの整合性確保
• 教科固有のルール適用（数学の方程式排除など）

7.2 使用方法

# スクリプト実行
GEMINI_API_KEY=xxxxx python scripts/review_math_with_gemini.py knowledge/v1.8.1/math/MA01.json

7.3 添削スクリプト

ファイル	説明
scripts/review_math_with_gemini.py	数学用Gemini添削スクリプト

7.4 添削基準

共通基準:

• answerが学術的に正確か
• question_hintが問題として適切か
• source_contextが解法・背景として正しいか

数学固有基準:

• 方程式（x=〜）を使わない
• 特殊算・計算の工夫で解法を説明
• 中学受験向けの難易度設定

7.5 使用モデル

モデル	用途
gemini-3-pro-preview	高精度な添削（推奨）

7.6 注意事項

• APIレート制限に注意（30秒間隔推奨）
• 1ファイル（40問）= 1回のAPI呼び出し
• レスポンスがemptyの場合は再試行

---

8. 参照ファイル

ファイル	用途
knowledge/japanese.md	国語問題の素材
knowledge/science.md	理科問題の素材
knowledge/social.md	社会問題の素材
knowledge/v1.8.1/**/*.json	編集対象ファイル

---

最終更新: 2025-12-23