generate-flashcards

フラッシュカードを生成する

レッスンの内容から2種類のカードを生成します。重要な事実を定着させる想起カードと、本質的な理解を促す思考カードです。半分ずつにします。それだけです。必ず最初に計画を立て、タスクツールを使って計画を整理し、進捗を記録してください。

優れたカードの条件

まずこのセクションを読んでください。それ以外はすべて作業上の手順です。

想起カード（デッキの半分）

最小情報の原則（1つの質問、1つの答え）に従ってください。質問は簡潔でありながら明確にし、40語未満にしてください。各カードは単体で意味が通じ、1つの概念だけを確かめるものにしてください。重要な用語、数式、関係性に重点を置きます。学生が5秒以内に答えられるようにしてください。

テスト：裏面を隠した状態で、レッスンを読んだ学生が記憶だけを頼りに答えられますか？答えられるなら、そのカードは適切です。表面にない文脈がないと答えられない場合、そのカードは不適切です。

裏面の長さ：想起カードの裏面は15語未満にしてください。事実だけを書き、説明や補足は加えません。語数が増える場合は、説明（つまり思考カード）になっているか、2つの事項を確認しているので、カードを分けてください。

カード1枚につき質問は1つ：表面に、異なる2つの質問をつなぐ「and」が含まれている場合は、2枚のカードに分けてください。「Xとは何か、そしてなぜ重要なのか？」は、2つの質問です。

優れた想起カード：

- id: "preface-agent-native-001"
  front: "In the Agent Factory model, what are the three pillars?"
  back: "1. AI Agents\n2. Cloud Infrastructure\n3. Business Model"
  tags: ["agent-factory", "pillars"]
  difficulty: "basic"

不適切な想起カード（その理由）：

# BAD: Too vague — what kind of "pillars"? Not self-contained.
- front: "What are the three pillars?"
  back: "Agents, Infrastructure, Business Model"

# BAD: Tests recognition, not recall — the answer is in the question.
- front: "Is SDD the methodology where specs are the source of truth?"
  back: "Yes"

# BAD: Tests two things at once — split into two cards.
- front: "What is SDD and what is MCP?"
  back: "SDD is spec-driven development. MCP is model context protocol."

# BAD: Back is a paragraph — just give the fact, not the explanation.
- front: "In the Agent Factory era, what do companies manufacture?"
  back: "AI employees — role-based systems that compose tools, spawn
    specialist agents, and deliver outcomes at scale."
# FIXED: back: "AI employees (Digital FTEs)"

思考カード（デッキの半分）

丸暗記ではなく、理解に重点を置いてください。より深く考えるよう促し、単に答えを思い出すのではなく、推論を求めるために、質問そのものを**Why（なぜ）またはHow（どのように）**の質問にしてください。これらのカードへの回答には10～30秒かかります。

テスト：このカードに答えるには、学生はただ思い出すのではなく、考える必要がありますか？オウムでも答えられるなら、思考カードではありません。

推論の連鎖テスト：裏面だけを読んでください。実際の因果関係を示す**BECAUSE（なぜなら）またはTHEREFORE（したがって）**が含まれていますか？それとも、箇条書きから暗記できる事実でしょうか？裏面に推論がなければ、それは想起カードを装ったものです。分類し直すか、書き直してください。

裏面の長さ：思考カードの裏面は20～40語にしてください。重要な洞察から始め、推論を1段階続けます。40語を超える場合は、複数の事項を確認しているか、エッセイを書いています。

表面の多様性：デッキ全体で思考カードの形式に変化をつけてください。シナリオ、比較、反実仮想、因果関係を問う質問を使い、「[source]はなぜ……と主張しているのか」だけにしないでください。「[text/lesson/preface]はなぜ……と主張する／述べる／推奨するのか」という形式のカードは、デッキ全体で2枚までにしてください。

優れた思考カード：

# Scenario — student must reason about what's missing
- id: "preface-agent-native-002"
  front: "A startup builds great AI agents with solid cloud infrastructure, but revenue stalls. Why?"
  back: "Technology without a business model doesn't generate revenue. The Agent Factory requires all three pillars — agents, infrastructure, AND a model for selling verified outcomes."
  tags: ["agent-factory", "business-model"]
  difficulty: "intermediate"
  why: "What's the difference between selling outcomes and selling software subscriptions?"

# Counterfactual — what breaks if you remove X?
- id: "ch01-example-002"
  front: "What would happen if a company deployed Custom Agents without any Incubation phase first?"
  back: "They'd over-engineer solutions to the wrong problem. Without exploration, requirements are guesses — the resulting agent is brittle and must be rebuilt."
  tags: ["agent-maturity-model", "anti-patterns"]
  difficulty: "advanced"
  why: "How would you recognize premature specialization in a real project?"

不適切な思考カード（その理由）：

# BAD: This is just a recall card with "Why" stapled on.
- front: "Why is SDD important?"
  back: "Because specs are the source of truth."

# BAD: Disguised recall — the back is a memorizable before/after comparison, not reasoning.
- front: "How does the human role change from the SaaS era to the Agent Factory era?"
  back: "From operator to supervisor and verifier."
# FIXED: Make it a recall card, or rewrite to require actual reasoning:
#   front: "Why does shifting from operator to supervisor require new skills, not just less work?"

# BAD: Answer is too short — no reasoning shown.
- front: "A company's AI agents keep failing in production. What's the likely cause?"
  back: "No evaluation."

# BAD: Front is so long it becomes a reading exercise, not a thinking exercise.
- front:
    "Given that a company has deployed agents using Claude Code with MCP integration
    and their specs follow the SDD methodology but they haven't implemented golden
    dataset evaluation and their shadow mode period was only 2 weeks..."
  back: "..."

# BAD: Formulaic — 6 cards in one deck all start with "Why does the lesson argue..."
- front: "Why does the lesson argue that open-source AI models are critical?"
# FIXED: "Open-source AI models are available but governments still build proprietary systems. Why?"

why フィールド

思考カードのみで使用します。20語未満の単一の質問で、含意、仕組み、他の概念とのつながりなど、もう一段深く考えさせるものにしてください。表面の質問を繰り返してはいけません。

良い例：表面が「なぜXが起きたのか？」と尋ねる場合 → why は「Xをどうすれば防げますか？」 悪い例：表面が「なぜXが起きたのか？」と尋ねる場合 → why は「Xが起きた理由を説明できますか？」

自己完結のルール

すべてのカードは、単独で意味が通じる必要があります。3週間後にカードを復習する学生は、レッスンの構成を忘れています。カードの表面に「3番目の要素は何ですか？」と書かれている場合、何の3番目の要素でしょうか？用語が何を指すのか、必ず文脈の中で明示してください。

カード生成の手順

1. レッスンを見つける

# "ch N" or "chapter N" — substitute the chapter number:
ls -d apps/learn-app/docs/*/NN-*/

# Bare lesson name:
find apps/learn-app/docs -name "*lesson-slug*" -name "*.md"

2. 既存のフラッシュカードを確認する

# Use absolute path — CWD may vary
ls "$(dirname /absolute/path/to/lesson.md)/$(basename /absolute/path/to/lesson.md .md).flashcards.yaml" 2>/dev/null

• 既存のカードがあり、再生成の指示がない → 通知してスキップ
• 既存のカードがあり、再生成の指示がある → deck.version を上げて再生成
• 既存のカードがない → 新規生成（バージョン：1）

3. レッスンを読む

.md ファイル全体を読みます。読みながら、次の点を特定してください。

• 暗記する価値がある内容 — 学生が確実に覚えておくべき重要な用語、フレームワーク、番号付きリスト、定義
• 理解する価値がある内容 — 因果関係の仕組み、トレードオフ、意思決定のフレームワーク、「なぜ Y ではなく X なのか」という問い

優先順位の目安（カードにする価値が高い順）：

1. 定義と名称のある概念（用語を定義できなければ、それを使って考えることはできません）
2. フレームワークとモデル（柱、段階、階層など、構造を支える枠組み）
3. 番号付きリストと列挙（うろ覚えになりやすいため、カードで防ぎます）
4. 因果関係の主張とトレードオフ（なぜ X が Y より優れているのか、Z が失敗すると何が起きるのか）
5. 原則を具体化する例（抽象的な考え方を支える具体的な手がかり）

除外する内容：逸話、歴史的な背景、意欲を高める余談、同じ要点を繰り返し説明している箇所。

カードの密度：散文の内容 150～200 語につき、カード約 1 枚を目安にしてください（コードブロックや設定例は数えません）。最低 8 枚とします（内容が少ないレッスンにも中核となる概念はあります）。上限は 25 枚です（長いレッスンでは、すべてを網羅するのではなく、最も重要な内容を選んでください）。カードにする価値のある概念が 8 個未満のレッスンでは、カードを水増しせず、必要な枚数だけ作成してください。

列挙のルール：レッスンが番号付きリスト（例：「8 つの反論」「5 つのデプロイ段階」「4 つの収益化モデル」）を中心に構成されている場合、各項目につき少なくとも 1 枚のカードを作成してください。カードの形式は、想起（名称を答える／定義する）または思考（理解を確かめる）のいずれでもかまいません。N 個の項目を 2 枚のカードにまとめないでください。8 項目のうち 3 項目をなんとなく覚えているだけでは、そのフレームワークを習得したとはいえません。

3.5 概念リストを作成する

カードを作成する前に、レッスン内のカードにする価値がある概念をすべて番号付きリストにしてください。それぞれに、想起候補または思考候補のタグを付けます。

• R = 想起候補（定義、名称のあるフレームワーク、列挙、重要用語）
• T = 思考候補（因果関係の仕組み、トレードオフ、意思決定、「なぜ Y ではなく X なのか」）

例：

1. [R] SaaSpocalypse — definition and trigger event
2. [R] Agent Triangle — three deployment paths
3. [T] Why legal tech got hit hardest
4. [R] Digital FTE hours vs Human FTE hours
5. [T] Why skipping Incubator stage fails
6. [R] Golden Dataset — definition and threshold
7. [T] Why open-source plugins were more threatening than proprietary ones

概念リストの検証項目：

• レッスン内のすべての H2／H3 見出しに、少なくとも 1 つの概念がありますか？
• レッスン内で定義されている重要用語が、リストから漏れていませんか？
• レッスンで番号付きのフレームワーク（例：「8 つの反論」）が紹介されている場合、各項目がリストに含まれていますか？
• R／T の割合はおおむね均衡していますか？

確認してから、概念リストに基づいてカードを作成してください。 作成するすべてのカードは、リスト内の概念に対応していなければなりません。リストにない概念に基づくカードを作成した場合は、その概念をリストに追加する（実際に漏れていた場合）か、カードを削除する（水増しにあたる場合）かのいずれかを行ってください。

4. カードを作成する

ステップ3.5のコンセプトリストに沿って作業します。各コンセプトについて、書き始める前にカードの種類を決めてください。

1. コンセプトとR/Tタグを確認します
2. 宣言します：「これは想起カードです」または「これは思考カードです」
3. 以下の該当するルールを適用します。混在させないでください
4. 想起カードの表面に対して、思考カードのような長さの裏面を書いていることに気づいたら、止めてください。裏面を事実だけに絞る（想起）か、表面を「なぜ／どのように」の質問に書き換えてください。書いた内容からカードの種類が暗黙に決まることのないようにしてください。

references/LEARNING-SCIENCE.md にある学習科学の3つの原則を適用します。最小限の情報（カード1枚につきコンセプト1つ）、検索練習（答えを思い出させるようなヒントを与えず、想起を促す）、精緻化質問（思考カードでは「なぜ」を使って、より深く考えさせる）。

想起カード：

• 直接的で明確な質問（40語未満）、簡潔な回答（15語未満）
• 表面は ? で終わる必要があります
• 重要な用語、公式、関係性に焦点を当てます
• why フィールドは不要です
• 難易度：basic または intermediate
• 裏面は事実だけにします。理由付け、詳しい説明、「なぜなら」は不要です。裏面に説明が必要なら、それは思考カードです。

思考カード：

• 丸暗記ではなく、理解に焦点を当てます
• 表面は明示的な**「なぜ」または「どのように」の質問**にする必要があります
• why フィールドは必須です（質問1つ、20語未満）
• 難易度：intermediate または advanced
• 裏面には事実だけでなく、推論の連鎖（なぜなら／したがって）を含める必要があります。20～40語です。
• 表面の形式に変化をつけます：シナリオ、反実仮想、比較、因果関係の連鎖。「なぜ[出典]は……と主張するのか」という形式は、デッキ全体で最大2枚です。

両方を混ぜてください — デッキ全体で想起カードと思考カードを交互に配置します。想起カードを冒頭にまとめないでください。

5. 作成前のセルフチェック

先月レッスンを読んだ学生になったつもりで、カードを確認します。

• レッスンを見なくても、すべての表面の質問が理解できますか？（自己完結している）
• オウム返しでも答えられますか？ そうなら想起カードです。正しくその種類として指定されていることを確認してください
• 思考カードは本当に理解度を測っていますか？ それとも、言葉を足しただけの想起カードですか？
• 思考カードの裏面を1枚ずつ確認します。「なぜなら／したがって」という推論の連鎖が含まれていますか？ それとも、暗記できる事実だけですか？
• 学生が知らないと恥ずかしいと思うようなコンセプトを飛ばしていませんか？
• 1枚のカードで2つのことを問うていませんか？ 分割してください。（2つの質問を「and」で結んでいないか確認します。）
• 裏面が「はい」または「いいえ」で始まるカードはありませんか？ 言い換えてください。（バリデータースクリプトで拒否されます。）
• 想起カードの裏面は15語未満ですか？ そうでなければ、事実だけに絞ってください。
• 思考カードの裏面は40語未満ですか？ そうでなければ、一度に多くのことを問うています。
• すべての表面が ? で終わっていますか？
• すべての思考カードに、空でない why フィールドが含まれていますか？
• 想起カードに why が含まれていませんか？
• 思考カードの表面に「なぜ」または「どのように」が明示されていますか？
• 想起カードと思考カードの枚数はおよそ50/50ですか（目標範囲：各45～55%）？
• 「なぜ[出典]は……と主張／述べ／推奨するのか」という形式の思考カードの表面は、2枚以下ですか？
• 難易度の分布は適切ですか：basic 25～35%、intermediate 45～55%、advanced 15～25%ですか？（basicが40%を超える場合は、一部のカードの難易度を上げてください。）
• カードに含まれるすべての数字、割合、固有名詞は、元のレッスンに一字一句そのまま記載されていますか。数値を推測または計算した場合は、文章と照合するか、その数値を削除してください。

5.5 網羅性の監査

すべてのカードを生成したら、レッスンの見出しと重要なリストを読み直し、それぞれを確認します。

• すべての H2/H3 見出しに少なくとも 1 枚のカードがある
• レッスン内のすべての番号付きリスト（例：「8 つの反論」「3 つの柱」「4 つの収益化モデル」）に、次のカードがある
  • 項目を挙げる、1 枚の想起カード
  • 個々の項目の理解を確認する、少なくとも 1 枚の思考カード
• レッスンで N 個の名前付き概念を紹介しているのに、デッキのカードが N/2 枚未満なら、網羅性が不足しています
• 手順 3.5 の概念リストと照合します。カード化されていない概念はありませんか？

セクションを意図的に省略した場合（逸話、動機付けを目的とした補足など）は、レポートにその旨を記載します。それ以外の場合は、カードを追加します。

5.6 種類の純度チェック

すべてのカードを重点的に確認し、複合型になっていないかを見極めます。

思考カードごとに、裏面だけを読みます。

1. BECAUSE、THEREFORE、または因果関係を示す表現が含まれていますか？
2. 裏面の内容を箇条書きとして暗記できそうですか？ できそうなら → 想起カードに分類し直します（裏面を短くして、why を削除します）。

想起カードごとに、裏面だけを読みます。

1. 15 語未満ですか？
2. 「because」または説明が含まれていますか？ 含まれている場合 → 思考カードに分類し直します（why を追加し、表面を Why/How で始まる形に書き換えます）。

カードの種類を変更した場合は、それに応じて難易度も更新します（想起カードの既定値は basic/intermediate、思考カードの既定値は intermediate/advanced です）。

6. YAML の作成

.md ファイルと同じ場所に <lesson-basename>.flashcards.yaml を作成します。references/YAML-SCHEMA.md のスキーマに従います。

6.5 必須の品質ゲート（省略不可）

最終確定の前に、次の制約を必ず適用します。

1. カード ID は、^{deck.id}-\d{3}$ に厳密に一致する必要があります。プレフィックスを短縮してはいけません（たとえば、deck.id が preface-agent-native の場合、preface-001 は無効です）。
2. すべてのカードの front は ? で終わる必要があります。
3. すべての思考カードに、空でない why フィールドが必要です。
4. 想起カードに why フィールドを含めてはいけません。
5. 思考カードの表面には Why または How を明示的に含める必要があります。
6. 想起カードと思考カードの割合は、それぞれ 45%-55% の範囲内である必要があります。
7. 想起カードの表面は 40 語未満にしてください。
8. どのカードの裏面も Yes または No で始めてはいけません。
9. 想起カードの裏面は 15 語未満にします。 語数を数えてください。超える場合は、事実だけに絞って短くします。
10. 思考カードの裏面は 20-40 語にします。 要点から始め、推論を 1 段階加えます。
11. 複合的な質問は禁止です。 表面で「and」によって 2 つの質問が結び付けられている場合は、2 枚のカードに分けます。
12. 思考カードの表面に変化を持たせます。 1 つのデッキで「Why does the [source] argue/say/recommend...」を使うカードは 2 枚までにします。状況設定、反実仮想、比較を使ってください。
13. 難易度の分布。 basic：25-35%、intermediate：45-55%、advanced：15-25%。basic が 40% を超える場合は、カードの難易度を上げます。advanced が 0% の場合は、最も難しい思考カードの難易度を上げます。

いずれかのゲートを通過できない場合は、カードを修正してから再確認し、最終出力を返してください。

7. 見出しの規約

レッスンの .md ファイルにフラッシュカードを追加する場合は、次の形式を使用します。

## Flashcards Study Aid

<Flashcards />

カード ID の方針（重複防止）

カード ID は、書籍内のすべてのデッキで一意である必要があります。カードのプレフィックスには、完全な deck.id を使用します。

deck:
  id: "ch05-reusable-skills" # Globally unique deck ID

cards:
  - id: "ch05-reusable-skills-001" # Full deck ID + sequence
  - id: "ch05-reusable-skills-002"

これにより、同じ章の複数のレッスンでカードを生成しても、ID が重複しません。apps/learn-app/scripts/validate-flashcards.ts のバリデーターが、すべてのデッキにわたる一意性を確認します。

デッキ ID の規約：kebab-case で <section>-<lesson-slug> の形式にします。

• preface-agent-native、ch01-factory-paradigm、ch05-reusable-skills
• 数字のプレフィックスがあるレッスンの場合：ch05-03-skills（第 5 章、レッスン 03）

難易度

• basic — この事実を思い出せますか？（定義、識別、リスト）
• intermediate — これを応用できますか？（状況設定、比較、因果推論）
• advanced — 評価したり、新たに作り出したりできますか？（批評、結果の予測、統合）

目標：basic は 25-35%、intermediate は 45-55%、advanced は 15-25% です。すべてのカードを生成した後に数えます。basic が 40% を超える場合は、複雑な想起カードの難易度を intermediate に上げます。advanced が 0% の場合は、最も難しい思考カードの難易度を advanced に上げます。すべてのデッキに、advanced のカードを少なくとも 1～2 枚含めてください。

チャプターモード

チャプター全体を対象に生成する場合：

1. ls <chapter-dir>/*.md — レッスンを確認します
2. README.md、index.md、category.json はスキップします
3. 各レッスンを順番に生成します
4. 各レッスンには、それぞれ独自の deck.id を持つデッキを割り当てます。ID は共有しません

デッキ間の考慮事項

関連するレッスン（同じチャプター、同じパート、または論文・序文などの書籍レベルのページ）を対象に生成する場合：

1. 兄弟ディレクトリに既存の .flashcards.yaml ファイルがないか確認します
2. ある概念のカードが兄弟デッキにすでにある場合は、スキップするか、明確に異なる視点からカードにするかを選びます
3. デッキ間で、同じ概念を同じ切り口で重複させないでください

よくある間違い

問題	解決方法
すべてのカードが同じように感じられる	各カードが、想起問題か思考問題のどちらかに明確に分かれているか確認します。曖昧に混在させません。
カードが単独で意味をなさない	表面に文脈を加えます。「Agent Factory モデルでは、……」のようにします
思考問題が「なぜ」を付けただけの想起問題になっている	裏面を確認します。「BECAUSE／THEREFORE」に相当する推論が含まれていますか？なければ想起問題です
想起問題の裏面が段落になっている	15 語未満にします。事実だけを書きます。「because」や詳しい説明は加えません
思考問題の裏面がエッセイになっている	20～40 語にします。重要な洞察と推論を 1 つに絞ります。長すぎる場合は分割します
表面に「X と Y？」という複合的な質問がある	2 枚のカードに分割します。カード 1 枚につき概念 1 つが原則です
すべての思考問題の表面が「本文ではなぜ……」になっている	デッキあたり最大 2 枚にします。代わりにシナリオ、反実仮想、比較を使います
基本難易度が 50% を占めている	目標は 25～35% です。複雑な想起問題は中級に引き上げます
上級カードが 0%	目標は 15～25% です。最も深い思考問題を上級に引き上げます
why が表面の内容を繰り返している	異なる側面に踏み込みます。影響、防止策、関連する概念などを扱います
重要度の低い詳細に関するカードが多すぎる	これを知らないと学生が恥ずかしい思いをするでしょうか？そうでなければ削除します
ID に短縮したプレフィックス（例：preface-001）を使っている	カード ID は deck.id-NNN 形式でなければなりません（プレフィックスは完全な形で、省略しません）
YAML の特殊文字で解析に失敗する	: # " ' を含む文字列は引用符で囲みます
カードの裏面が「Yes」／「No」で始まっている	バリデーターで拒否されます。直接的な言い回しに修正します
兄弟デッキで同じ概念を扱っている	スキップするか、異なる視点からカードにします。重複させないでください
思考問題の裏面が暗記できるリストになっている	見せかけの想起問題です。裏面を確認します。「BECAUSE／THEREFORE」に相当する推論が含まれていますか？なければ分類し直します
想起問題の裏面が 15 語を超えている	見せかけの思考問題（why を追加して表面を書き直す）か、冗長な内容（削る）のどちらかです
番号付きフレームワークのセクション全体をスキップしている	列挙ルール：項目が N 個なら、カードは最低 N 枚必要です。8 項目を 2 枚に要約しないでください
生成前に概念リストを作成していない	必ず先に概念を抽出します（ステップ 3.5）。概念マップなしでカードを作ると、内容がぶれてしまいます
カードの数値を検証していない	すべての統計値は、ソースにそのまま記載されていなければなりません。数値を推測したり計算したりしないでください

レポート

生成後、次を出力します：

Generated: <path>
Cards: <count> total (recall: N, thinking: N)
Why fields: N
Ratios: recall=<0.00>, thinking=<0.00>, thinking-fronts-with-why/how=<0.00>
ID format: PASS/FAIL (`deck.id-NNN`)
Fronts end with '?': PASS/FAIL
Recall backs ≤15 words: PASS/FAIL (longest: N words, card: <id>)
Thinking backs 20-40 words: PASS/FAIL (shortest: N, longest: N, violators: <ids>)
Compound questions: PASS/FAIL (N found)
"Why does the [source]..." fronts: N (max 2)
Difficulty: basic: N (NN%), intermediate: N (NN%), advanced: N (NN%)
Factual verification: PASS/FAIL (unverified figures: <ids>)
Type purity: PASS/FAIL (hybrids reclassified: N)
Coverage: N concepts extracted, N carded, N skipped (list skipped sections if any)

参考資料

• references/LEARNING-SCIENCE.md — 認知科学の基礎（検索練習、最小情報、精緻化質問）
• references/CARD-TYPES.md — カードタイプの例とアンチパターン
• references/YAML-SCHEMA.md — YAML スキーマの詳細、フィールド制約、エスケープ規則