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 フォーマット統一

```json

{

  "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: 現状分析



```python

# 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: 難易度調整



```python

# 現状カウント

counts = {"基本": 0, "標準": 0, "応用": 0}



# 目標: 30:50:20

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



# 差分を計算し調整

```



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



```python

# 連番割り当て

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 使用方法



```bash

# スクリプト実行

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