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