adamaiken89/learn-something

Learn Something Framework

対話型LLMセッションを通じて、科目を構造化されたカリキュラムに変換します。 CLIで学習：レッスンの読み込み、説明の復唱、MCQのドリル、スペースドリピート。

1. 教育学

3つの理論を融合：

理論	AIの役割	解決する問題
マーバ・コリンズ	ソクラテス式のチューター。厳格なQ&A、高い期待、無限の忍耐。	優れた教師が必要。AIは決して疲れない。
ファインマンテクニック	ギャップ検出器。学習者が簡潔に説明→AIが穴を見つける。	理解したつもり
望ましい困難	スペースドリピートのスケジューラー。FSRS想起＋インターリーブ練習。	受動的な再読

セッションフェーズ → 理論マッピング

フェーズ	理論	学習者	AI/CLI
読む	マーバ	レッスンを学習	明確なコンテンツを作成
説明する	ファインマン	概念を簡潔に説明	質問：「あなたはXと言ったが、Yについてはどう調和するのか？」と探る
ドリル	マーバ＋望ましい	MCQに回答し、正当化	採点、ディストラクターを説明
判断する	マーバ	批判し、意見を形成	ソクラテス式フォローアップ
復習する	望ましい	FSRSによるアクティブリコール	最適な間隔をスケジュール

時間予算

• 科目：最大40時間（13週間×週3時間）
• モジュール：1.5～3時間、科目あたり約15～20モジュール
• SRS復習：毎日約10～15分

2. コンテンツ構造

<topic>/
├── syllabus.yaml             # コース仕様
├── modules/
│   ├── NN-name/
│   │   ├── lesson.md         # コアコンテンツ＋演習
│   │   ├── quiz.yaml         # 8～10個のMCQ
│   │   └── cloze.yaml        # 8～10個の穴埋め問題
│   └── ...
└── srs/
    ├── deck.json             # FSRS-5カード
    └── stats.json            # 履歴

完全なテンプレートは templates/ にあります。主要なもの：syllabus.yaml（20モジュールのスケルトン）、module.md（レッスン構造）、quiz.yaml（4択MCQ形式）。

3. コンテンツ作成プロトコル

ワークフロー

1. スコープ（5分）：ドメイン、レベル、時間予算、言語、ユースケースを尋ねます。シラバスを提案します。
2. アウトライン段階：モジュールDAGと前提条件チェーンを確認します。時間予算をチェックします。
3. モジュールごと（10分）：learn.sh create-module <topic> NN-name を使用してモジュールを作成します。2桁のゼロパディングされた番号＋ケバブケース名（例：01-intro、02-core-concepts）。lesson.md + quiz.yaml を作成します。16の品質ルールをインラインで適用します。lesson.md は12,000文字以内にします。コンテンツがオーバーフローした場合は、追加のモジュールに分割し、シラバスを更新します。ユーザーがレビューして進めます。 3.5. 構文検証：learn.sh validate-content <topic> [module] を実行します。先に進む前に、すべてのMarkdown＋Mermaidエラーを修正します。
4. 公開前：content-verify.md を読み込みます。チェックリストを実行します。違反を修正します。
5. SRSのコンパイル（2分）：MCQを抽出→FSRS-5デッキ。
6. 累積クイズ：3～5モジュールごとに、ルートディレクトリに cumulative_quiz.yaml を生成します。8～10問の混合問題（穴埋め、MCQ、○×）。各問題に source_modules タグを付けます。回答はA～Dに分散させます。

コンテンツ原則

• CILO準拠：すべてのモジュールが1つ以上の学習目標に貢献します。無駄なものはありません。
• 言語：syllabus.yaml の言語（en/zh/yue）で記述します。
• 実践優先：抽象的な定義の前に具体的な例から始めます。
• ドメイン関連：学習者の業界のシナリオを使用します。
• 穴埋め削除：すべてのモジュールに3～5個の穴埋め空白（{term}）を設定します。学習者は先に進む前に穴を埋めます。読書中に想起を強制します。
• 次を予測：すべての因果連鎖に2～3個の予測ブロックを設定します。学習者は明らかにされる前に結果をコミットします。
• 誤り発見：すべてのモジュールに1～2個の「誤りを見つけよう」演習を設定します。エラー駆動学習が診断スキルを構築します。
• デュアルコーディング：すべての概念に図（Mermaid、アスキーアート、または構造化階層）を入れます。
• MCQ多様性：40％は想起、40％は応用、20％は多段階問題。
• ファインマンプロンプト：すべてのレッスンの最後に説明タスク＋AIギャップ調査を設定します。
• 望ましい困難：同じ概念をモジュール間で異なる角度からテストします。
• 時間予算：モジュール≤3時間。科目≤40時間。
• モジュールサイズ制限：各モジュールのlesson.mdは12,000文字以内。制限を超えた場合は、トピックをさらにモジュールに分割します。それに応じてシラバスのモジュール数を調整します。
• 段階的学習：前提条件に基づいて構築します。初期のモジュールは基礎的。
• スキップ許可：学習者が少ない入力を与えた場合？それでも常識的なデフォルトでコンテンツを生成します。ブロックしないでください。
• ソクラテス式を全体に：すべての主要概念の後には、学習者が立ち止まって考えるような質問を入れます。モジュールの最後だけでなく、各新しいアイデアの後にインラインで挿入します。質問→その直後に簡潔な回答/説明を入れ、学習者が自己チェックできるようにします。パターン：概念を述べる→「なぜ？」または「もし～なら？」と質問する→回答する。
• Mermaid図：分岐ロジック、ステートマシン、ワークフロー、因果連鎖を含む概念に対して：Mermaidフローチャート/シーケンス/ステート図を生成します。テーマは自動的に neutral を注入してダーク/ライトの互換性を確保します。style の塗りつぶしには落ち着いたアースカラーパレットを使用します。パレット：青 #5c7a99、緑 #5c8a6a、オレンジ #b8924a、赤 #b86a4a、紫 #7a5a8a、グレー #888。ストローク：塗りつぶしのより暗い色合いまたは #333 を使用します。例：style A fill:#5c7a99,stroke:#333。概念の説明の後、「考える」質問の前に配置します。
• モジュールマインドマップ：すべてのモジュールは、lesson.md の先頭（メタデータの後、学習目標の前）にMermaidマインドマップを入れます。知識の階層を示します：中心概念→主要トピック→サブ概念。mindmap 構文を使用します。最大3階層。
• 回答分布：MCQの解答キーはA/B/C/Dに分散させます。同じ回答文字が連続して2回以上続かないようにします。テンプレートではBを例として示しています。生成中にローテーションします。
• 累積クイズ：3～5モジュールごとに、ルートディレクトリに cumulative_quiz.yaml を生成します。8～10問の混合問題（穴埋め、MCQ、○×）。各問題に source_modules タグを付けます。回答はA～Dに分散させます。

コンテンツ品質ルール（16個）

#	ルール	何をすべきか	悪い例→良い例
1	慣例を説明する	慣例がなぜ存在するのかを述べ、単に何かを述べるだけではない	「価格は95と表示」→「95＝1,000ドル額面の95％。％慣例により、異なる額面の債券間で比較が可能になる」
2	暗黙の質問に答える	学習者がまだ尋ねていない1～3の質問を予測する	クーポンについて沈黙→「クーポンは変わるのか？固定利付債では変わらない。変動利付債（FRN）では定期的にリセットされる」
3	パーへの収束の直感	価格→満期時の額面は機械的であることを説明する	「価格がパーに収束するのは、時間が短縮され、残りのキャッシュフローの現在価値が元本に収束するからです。金利によって引き起こされるわけではありません」
4	因果連鎖を先に	数式の前に直感的なロジック	債券価格計算式に飛びつく→「新しい債券は6％を支払う。私の債券は4％を支払う。私の方が価値が低い→利回りが一致するまで価格が下がる」
5	実践的な文脈	すべての数値に現実的な意味を持たせる	「デュレーション7.5」→「1％の金利上昇→約7.5％の価格下落（小幅な動きのみ。大きな動きにはコンベクシティ調整が必要）」
6	「どのくらいの確率か」	正常頻度とまれな頻度を伝える	省略→「イールドカーブの逆転はまれ。それぞれの逆転は不況に先行する（約8か月）。完全に予測できるわけではない」
7	よくある誤解	初心者が持つ1～2の具体的なエラーを指摘する	「高いクーポン＝良い債券」→「違う。ディスカウント債には満期時の価格上昇（アクリューション）が組み込まれている」
8	ソクラテス式を全体に	すべての概念セクションに考える質問と即時の回答を埋め込む	学習者が受動的に読む→強制的に立ち止まり、処理する
9	具体例から始める	抽象的な定義の前に具体的な例	「金利スワップの定義」→「会社Aが変動金利を固定金利に交換する」
10	図解を強制する	関係性を示す図を常に含める	図なしで説明→「Mermaidフローチャート：新規発行→価格低下→利回り上昇」
11	エラー駆動学習	「誤りを見つける」演習を含める	概念だけ→「この計算のどこが間違っているか？」
12	ファインマンプロンプト	「10歳の子供に説明してください」	「説明してください」→「11歳のいとこに債券価格設定を説明してください。AIがギャップを探します」
13	アクティブリコール	事前に空白を埋める、結果を予測する	受動的に読む→「次の段落を読む前に、{因果}を埋めてください」
14	前置きの確認	一旦停止させて、その前にカバーされた内容を言い換えさせる	長い説明→「パラグラフを言い換えてください。キーワード：{用語1}、{用語2}」
15	複数の表現	同じ概念を異なる方法で提示する	一度だけ提示→「表形式、グラフ、コード例」
16	明確な区切り	概念セクションを視覚的に分離する	壁のようなテキスト→「### セクション区切り」＋「次の概念」

4. 学習プロトコル

毎日のワークフロー（推奨）

1. 復習（10～15分）：SRSデッキからアクティブリコールカード。learn.sh review <topic>
2. 新しいレッスン（30～45分）：フェーズを通じて：読む→説明→ドリル→判断。learn.sh study <topic> <module>
3. オプションの探索：興味がある場合に深掘り。

カスタマイズ

• 言語を変更：syllabus.yaml の lang を編集
• 時間予算を調整：シラバスの total_hours と weeks を変更
• 難易度を設定：「初心者」「中級」「上級」

5. 例：債券

bonds/
├── syllabus.yaml
├── modules/
│   ├── 01-time-value-of-money/
│   │   ├── lesson.md
│   │   ├── quiz.yaml
│   │   └── cloze.yaml
│   ├── 02-bond-pricing/
│   │   ├── lesson.md
│   │   ├── quiz.yaml
│   │   └── cloze.yaml
│   └── ...（全20モジュール）
└── srs/
    ├── deck.json
    └── stats.json

learn.sh start bonds を実行すると、CLI学習セッションが開始されます。

6. トラブルシューティング

問題	解決策
レッスンが長すぎる	トピックを複数のモジュールに分割。シラバスの modules を更新
クイズのバランスが悪い	MCQのカテゴリを確認：40％想起、40％応用、20％多段階
Mermaidがレンダリングされない	構文を確認。learn.sh validate-content <topic> [module] を実行
SRSが進捗を表示しない	deck.json のカード形式がFSRS-5と互換性があるか確認

貢献

コンテンツテンプレート、スクリプト、品質ルールに対するPRを歓迎します。 新しいルールを追加する前に既存の品質ルールを確認してください。