四つの整合の原則
どんなテーマを学ぶにも、四つの成果物が同じ知識ポイントのセットを軸に整合していなければなりません：コース（解説）、問題（演習）、フラッシュカード（記憶アンカー）、間違えた問題の徹底解説（誤答ポイントの深掘り）。これらはリポジトリ内の独立した四つのファイルで、どれか一つを編集しても残りの三つは自動では動きません——整合を欠いてもエラーは出ず、目に見えない学習の穴が残るだけです：学んでいない内容の問題に直面する、学び終えても演習する問題がない、覚えるべき概念にカードがない。
四つの成果物はそれぞれ何か
Section titled “四つの成果物はそれぞれ何か”| # | 成果物 | ファイルの場所 | 何をするものか |
|---|---|---|---|
| 1 | コース | examples/<theme>/lessons/*.html |
概念を体系的に説き、メンタルモデルを作る |
| 2 | 問題 | examples/<theme>/questions.json |
演習で検証し、採点して間違えた問題を収集 |
| 3 | フラッシュカード | examples/<theme>/flashcards.json |
核心概念を間隔反復の記憶アンカーに |
| 4 | 徹底解説 | examples/<theme>/study/wrong-questions/cluster-*.html |
高頻度の誤答ポイントを深く展開 |
四つの成果物は孤立しておらず、同じ出題ポイントのセットを軸に連携します：コースが一つの概念を説き、問題がその概念を問い、フラッシュカードがその概念の定着を助け、徹底解説はあなたが間違えたときにその概念の混同しやすい境界を深掘りします。
なぜ整合が必須なのか（実際に踏んだ二つの穴）
Section titled “なぜ整合が必須なのか（実際に踏んだ二つの穴）”この原則は現実の失敗から来ています。理論上の潔癖ではありません。
穴 1：問題があるのにコースが説いていない（問題 → コース の穴）
Section titled “穴 1：問題があるのにコースが説いていない（問題 → コース の穴）”あるとき問題バンクに「半加算器」を問う問題が 20 問ありましたが、対応するコースではこの概念がまったく説明されていませんでした。こんな問題に当たっても、何を問われているのかさっぱり分かりません。
- 根本原因：問題がモジュールごとに機械的に分類され、コースがカバーしているかの確認がなかったこと。
- 修正：コースに欠けた概念の説明を補い、自動検証を追加（下記）。
穴 2：コースで説いたのに問題がない（コース → 問題 の穴）
Section titled “穴 2：コースで説いたのに問題がない（コース → 問題 の穴）”コースが一つの核心手法を重点的に説いたのに、関連する問題が追いついていませんでした——学び終えても演習がなく、問題を解く人は学んでいないという状態です。
- 根本原因：問題の分類タグがコース内容に沿って分割されていなかったこと。
- 修正：問題の
topic分類（と任意のdayスケジュールタグ）をコースに合わせ、双方向検証を追加。
三つの方向の整合検証
Section titled “三つの方向の整合検証”整合は双方向に照合し、さらにフラッシュカード被覆の層を加えます。
方向 1：問題 → コース（問題が問う出題ポイントを、コースは必ず説く）
Section titled “方向 1：問題 → コース（問題が問う出題ポイントを、コースは必ず説く）”問題文から高頻度の出題ポイント語（3 回以上出現する概念）を抽出し、コース HTML の被覆度（空白を除去した原文でのヒット回数）を一つずつ確認します：
- 3 回以上：✓ 被覆
- 1〜2 回：△ 軽く触れる程度。補講が必要
- 0 回：✗ 未説明。必ず補う
方向 2：コース → 問題（コースが説く出題ポイントを、問題は必ず演習する）
Section titled “方向 2：コース → 問題（コースが説く出題ポイントを、問題は必ず演習する）”コース HTML から核心概念を抽出し、問題バンクに対応する演習があるかを確認します：
- コースが重点的に説き、問題バンクに該当問題が 0 問 → 演習不足。出題ポイントごとに問題を補う
- 関連問題が別の分類に散らばっている → 問題の
topic（またはdayタグ）を調整し、学習と演習が同じ分類の中で完結するようにする
方向 3：フラッシュカード被覆
Section titled “方向 3：フラッシュカード被覆”コースの核心概念（3 回以上の出題ポイント語）は、それぞれ 1 枚以上のフラッシュカードで被覆されているべきです（カードの front / back でのヒット）：
- コースが説いた概念にカードがない → 記憶アンカーの欠落
- カードが扱う概念をコースが触れていない → カードが浮いている。コースを補うか、カードを削るか
いつ検証を走らせるか
Section titled “いつ検証を走らせるか”どれか一つの成果物を変更した後は必ず走らせます：
- 新しいコースを生成した後——コースはどの出題ポイントをカバーしたか？その出題ポイントに問題はあるか？フラッシュカードは被覆しているか？
- 問題の topic / day 分類を変えた後——再分類はコースと問題の乖離を生みうる。
- flashcards.json を変えた後——カードの追加・削除は、コースとの乖離を生みうる。
- grill CLI で一括の徹底解説を生成した後——間違えた問題の出題ポイントは必ず対応するコースまで追跡できること（間違えた問題 → コース の逆方向検証）。
dev-intro サンプルの四つの整合
Section titled “dev-intro サンプルの四つの整合”examples/dev-intro/ を開くと、四つの整合の完全なサンプルが見られます：
| 知識ポイント | コース | 問題 | フラッシュカード | 徹底解説 |
|---|---|---|---|---|
| git の三つの領域 | lessons/git-basics.html §1-2 |
GIT-006 | FC-DEV-01 | — |
| git のコミットと取り消し | lessons/git-basics.html §4 |
GIT-007 | FC-DEV-03 | study/wrong-questions/cluster-01-git-提交与撤销操作.html |
| chmod の権限 | lessons/linux-basics.html §3-4 |
LNX-002 | FC-DEV-02 | study/wrong-questions/cluster-02-linux-权限与路径.html |
相対パス .. |
lessons/linux-basics.html §2 |
LNX-003 | — | — |
すべての知識ポイントが四つの成果物すべてに被覆される必要はありませんが、高頻度の誤答ポイントは四成果物がすべて揃っていなければなりません（git のコミットと取り消しのように）——これが grill CLI の中心的な出力シナリオです。
bidirectional-check.ja.md—— 自動検証スクリプト。上の二つの方向を Python コードにしたものmethodology.ja.md—— 完全な方法論フレームワークai-cli-guide.ja.md—— teach / grill CLI で整合したコンテンツを生成する方法