generate-flashcards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate Flashcards

生成闪卡

Generate two kinds of cards from lesson content — recall cards that lock in critical facts, and thinking cards that force genuine understanding. Half and half. That's it. Always plan first, use your tasks tool to organize the plan and track your progress.

从课程内容中生成两类卡片——记忆卡用来巩固核心知识点，思考卡用来检验真实理解程度，二者各占一半，就这么简单。生成前请先做好规划，使用任务工具组织规划并跟踪进度。

What Makes a Good Card

什么是好的卡片

Read this section first. Everything else is mechanics.

请先阅读本节内容，其他部分都是操作流程。

Recall Cards (half the deck)

记忆卡（占卡组的一半）

Follow the minimum information principle (one question, one answer). Keep questions concise but explicit (under 40 words). Ensure each card is self-contained and atomic (tests only one concept). Focus on key terms, formulas, and relationships. A student should be able to answer in under 5 seconds.

The test: Cover the back — can a student who read the lesson produce the answer from memory? If yes, the card works. If the card requires context not on the front, it fails.

Back length: Recall backs must be under 15 words. Just the fact — no explanation, no elaboration. If you need more words, you're explaining (that's a thinking card) or testing two things (split).

One question per card: If the front contains "and" joining two distinct questions, split it into two cards. "What is X and why does it matter?" = two cards.

Good recall card:

yaml

- 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 recall card (and why):

yaml

undefined

遵循最小信息原则（一个问题对应一个答案）。问题要简洁明确（不超过40个单词），确保每张卡片都是自包含、原子化的（仅测试单个概念）。重点覆盖核心术语、公式和关联关系，学生应能在5秒内给出答案。

测试标准：盖住答案面，读过课程的学生能否凭记忆给出答案？可以的话卡片就是合格的。如果卡片需要正面以外的上下文才能回答，就是不合格的。

答案长度要求：记忆卡的答案必须不超过15个单词，只放知识点本身，不要解释、不要展开。如果需要更多字数，说明你在做解释（那应该做成思考卡）或者同时测试了两个内容（拆分成两张卡）。

每张卡仅包含一个问题：如果正面用“and”连接了两个不同的问题，拆分成两张卡。比如“什么是X以及它为什么重要？”就属于两个问题，要拆成两张卡。

合格的记忆卡示例：

yaml

- 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"

不合格的记忆卡（附原因）：

yaml

undefined

BAD: Too vague — what kind of "pillars"? Not self-contained.

不合格：表述太模糊——什么类型的“pillars”？不满足自包含要求

front: "What are the three pillars?" back: "Agents, Infrastructure, Business Model"

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"

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."

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."

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)"

修正后答案: "AI employees (Digital FTEs)"

undefined

undefined

Thinking Cards (half the deck)

思考卡（占卡组的一半）

Focus on understanding, not just rote memorization. The question itself must be a Why or How question to encourage deeper thinking and force the student to reason, not just retrieve. These cards take 10-30 seconds to answer.

The test: Does answering this card require the student to think, not just remember? If a parrot could answer it, it's not a thinking card.

The reasoning-chain test: Read just the back. Does it contain a BECAUSE or THEREFORE — an actual causal chain? Or is it a fact someone could memorize from a bullet point? If there's no reasoning in the back, it's a disguised recall card. Reclassify or rewrite.

Back length: Thinking backs should be 20-40 words. Lead with the key insight, follow with one reasoning step. Over 40 words = you're testing multiple things or writing an essay.

Front variety: Vary thinking card formats across the deck. Use scenarios, comparisons, counterfactuals, and causal questions — not just "Why does the [source] argue that...". No more than 2 cards per deck may use the "Why does the [text/lesson/preface] argue/say/recommend..." template.

Good thinking card:

yaml

undefined

重点考察理解能力，而非死记硬背。问题本身必须是**Why（为什么）或How（如何）**类问题，引导深度思考，倒逼学生进行推理而非单纯检索记忆。这类问题需要10-30秒来作答。

测试标准：回答这张卡片是否需要学生思考，而非单纯回忆？如果鹦鹉都能回答，那它就不是思考卡。

推理链测试：只看答案，里面是否包含**BECAUSE（因为）或THEREFORE（因此）**这类实际的因果关系？还是说它是可以从要点里背下来的事实？如果答案里没有推理过程，那它就是伪装的记忆卡，需要重新分类或者重写。

答案长度要求：思考卡的答案应为20-40个单词，开头给出核心观点，后面跟一个推理步骤。超过40个单词说明你同时测试了多个内容，或者写得太像小作文了。

问题形式多样化：卡组里的思考卡要使用不同的形式，可以用场景题、比较题、反事实题、因果题，不要只用“为什么[资料/课程/前言]认为...”这种模板。每个卡组最多只能有2张卡使用“Why does the [text/lesson/preface] argue/say/recommend...”模板。

合格的思考卡示例：

yaml

undefined

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?"

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?

反事实题——如果去掉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 thinking card** (and why):

```yaml

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?"


**不合格的思考卡（附原因）**：

```yaml

BAD: This is just a recall card with "Why" stapled on.

不合格：只是加了个“Why”的记忆卡而已

front: "Why is SDD important?" back: "Because specs are the source of truth."

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."

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."

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: "..."

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..."

不合格：模板化——一个卡组里有6张卡都以“Why does the lesson argue...”开头

front: "Why does the lesson argue that open-source AI models are critical?"

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?"

修正后："Open-source AI models are available but governments still build proprietary systems. Why?"

undefined

undefined

The

why

Field

why

字段

Only on thinking cards. A single question, under 20 words, that pushes one level deeper — implications, mechanisms, or connections to other concepts. It must NOT repeat the front.

Good: Front asks "Why did X happen?" →

why

asks "How would you prevent X?" Bad: Front asks "Why did X happen?" →

why

asks "Can you explain why X happened?"

仅思考卡需要设置该字段，是一个不超过20个单词的问题，用来引导更深层次的思考：比如影响、机制、和其他概念的关联。绝对不能和正面的问题重复。

合格示例：正面问“为什么X会发生？” →

why

字段问“你会如何预防X发生？” 不合格示例：正面问“为什么X会发生？” →

why

字段问“你能解释为什么X会发生吗？”

Self-Contained Rule

自包含规则

Every card must make sense in isolation. A student reviewing cards 3 weeks later has forgotten the lesson structure. If your card front says "What is the third element?" — third element of what? Always anchor terms in their context.

每张卡片单独拿出来都要表意清晰。学生3周后复习卡片时已经忘记了课程结构，如果你的卡片正面写“第三个元素是什么？”——什么东西的第三个元素？永远要把术语放在对应的上下文里。

Card Generation Process

卡片生成流程

1. Find the Lesson

1. 找到课程文件

bash

undefined

bash

undefined

"ch N" or "chapter N" — substitute the chapter number:

"ch N" 或者 "chapter N" —— 替换成对应的章节号:

ls -d apps/learn-app/docs//NN-/

Bare lesson name:

直接通过课程名称查找:

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

undefined

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

undefined

2. Check for Existing Flashcards

2. 检查是否已有闪卡

bash

undefined

bash

undefined

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


- Exists + no regeneration requested → skip with notice
- Exists + regeneration requested → bump `deck.version`, regenerate
- Doesn't exist → generate fresh (version: 1)

ls "$(dirname /absolute/path/to/lesson.md)/$(basename /absolute/path/to/lesson.md .md).flashcards.yaml" 2>/dev/null


- 已有闪卡且没有重新生成的要求 → 提示后跳过
- 已有闪卡且要求重新生成 → 提升`deck.version`版本号，重新生成
- 没有闪卡 → 生成新卡组（版本号设为1）

3. Read the Lesson

3. 阅读课程内容

Read the full

.md

file. As you read, identify:

What's worth memorizing — key terms, frameworks, numbered lists, definitions that a student must know cold
What's worth understanding — causal mechanisms, tradeoffs, decision frameworks, "why X and not Y" questions

Prioritization guide (highest → lowest card-worthiness):

Definitions and named concepts (a student who can't define the terms can't think with them)
Frameworks and models (pillars, phases, layers — the structural scaffolding)
Numbered lists and enumerations (easy to half-remember, cards prevent that)
Causal claims and tradeoffs (why X beats Y, what breaks when Z fails)
Examples that embody a principle (concrete anchors for abstract ideas)

Skip: anecdotes, historical color, motivational asides, repeated explanations of the same point.

Card density: Aim for ~1 card per 150-200 words of prose content (don't count code blocks or configuration examples). Floor: 8 cards (thinner lessons still have core concepts). Ceiling: 25 cards (longer lessons — pick the most important, don't exhaustively card everything). If a lesson has fewer than 8 card-worthy concepts, generate fewer cards — never pad a deck with filler.

Enumeration rule: When a lesson is structured around a numbered list (e.g., "8 objections", "5 deployment stages", "4 monetization models"), each item deserves at least one card — either recall (name/define it) or thinking (test understanding of it). Don't summarize N items into 2 cards. A student who "sort of remembers 3 of the 8" has failed to learn the framework.

阅读完整的.md文件，阅读过程中识别以下内容：

值得记忆的内容 —— 核心术语、框架、编号列表、学生必须熟练掌握的定义
值得理解的内容 —— 因果机制、权衡取舍、决策框架、“为什么选X而不是Y”这类问题

优先级指南（适合做成卡片的程度从高到低）：

定义和命名概念（不能定义术语的学生没法用这些概念思考）
框架和模型（支柱、阶段、层级——知识的结构框架）
编号列表和枚举内容（很容易记不全，卡片可以避免这个问题）
因果论断和权衡取舍（为什么X比Y好，Z出问题会导致什么故障）
体现原则的示例（抽象概念的具象锚点）

跳过内容：轶事、历史背景、激励性的旁白、对同一个点的重复解释。

卡片密度：每150-200个单词的正文内容对应约1张卡片（代码块和配置示例不算在内）。下限：8张卡片（内容少的课程也有核心概念）。上限：25张卡片（长课程要选最重要的内容，不要把所有内容都做成卡片）。如果课程里值得做卡片的概念少于8个，就少生成几张，绝对不要用无意义的内容凑数。

枚举规则：如果课程是围绕编号列表组织的（比如“8个反对意见”、“5个部署阶段”、“4种盈利模式”），每个条目至少对应1张卡——要么是记忆卡（命名/定义），要么是思考卡（测试理解）。不要把N个条目总结成2张卡，那种“大概记得8个里的3个”的学生等于没学会这个框架。

3.5 Extract Concept List

3.5 提取概念列表

Before writing any cards, produce a numbered list of every card-worthy concept from the lesson. Tag each as a recall or thinking candidate:

R = recall candidate (definition, named framework, enumeration, key term)
T = thinking candidate (causal mechanism, tradeoff, decision, "why X and not Y")

Example:

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

Validation checks on the concept list:

Does every H2/H3 heading in the lesson have at least one concept?
Are any key terms defined in the lesson but missing from the list?
If the lesson introduces a numbered framework (e.g., "8 objections"), is each item represented?
Is the R/T split roughly balanced?

Only then proceed to card generation, working from this list. Every card you write must trace back to a concept on this list. If you generate a card that doesn't map to a listed concept, either add the concept to the list (it was genuinely missing) or cut the card (it's filler).

在写任何卡片之前，先把课程里所有适合做成卡片的概念列成编号列表，每个概念标记为记忆卡候选或者思考卡候选：

R = 记忆卡候选（定义、命名框架、枚举内容、核心术语）
T = 思考卡候选（因果机制、权衡取舍、决策、“为什么选X而不是Y”）

示例：

1. [R] SaaSpocalypse —— 定义和触发事件
2. [R] Agent Triangle —— 三种部署路径
3. [T] 为什么法律科技受到的冲击最大
4. [R] Digital FTE工时 vs 人类FTE工时
5. [T] 为什么跳过孵化阶段会失败
6. [R] 黄金数据集 —— 定义和阈值
7. [T] 为什么开源插件比专有插件威胁更大

概念列表校验项：

课程里的每个H2/H3标题都至少对应一个概念吗？
课程里定义的核心术语有没有遗漏在列表外的？
如果课程介绍了带编号的框架（比如“8个反对意见”），每个条目都在列表里体现了吗？
R/T的比例大致平衡吗？

确认没问题后再开始生成卡片，所有卡片都要基于这个列表生成。你写的每张卡都要能对应到列表里的某个概念，如果生成的卡片找不到对应的概念，要么把这个概念加到列表里（确实之前漏了），要么删掉这张卡（属于凑数内容）。

4. Generate Cards

4. 生成卡片

Work through your concept list from step 3.5. For each concept, commit to the card type BEFORE writing:

Read the concept and its R/T tag
Declare: "This is a RECALL card" or "This is a THINKING card"
Apply the corresponding rules below — no mixing
If you find yourself writing a recall front with a thinking-length back, STOP. Either trim the back to a fact (recall) or rewrite the front as a Why/How question (thinking). Never let type emerge implicitly from what you happened to write.

Apply the three learning science principles from

references/LEARNING-SCIENCE.md

: Minimum Information (one concept per card), Retrieval Practice (force recall, never hint at the answer), and Elaborative Interrogation (thinking cards push deeper with

why

Recall cards:

Direct explicit question (under 40 words), atomic answer (under 15 words)
Front must end with
```
?
```
Focus on key terms, formulas, and relationships
No
```
why
```
field
Difficulty:
```
basic
```
or
```
intermediate
```
Back = just the fact. No reasoning, no elaboration, no "because". If back needs explanation, it's a thinking card.

Thinking cards:

Focus on understanding, not just rote memorization
Front must be an explicit Why or How question
Always has
```
why
```
field (single question, under 20 words)
Difficulty:
```
intermediate
```
or
```
advanced
```
Back must contain a reasoning chain (BECAUSE/THEREFORE), not just a fact. 20-40 words.
Vary front formats: scenarios, counterfactuals, comparisons, causal chains. Max 2 per deck using "Why does the [source] argue...".

Mix them — alternate recall and thinking cards throughout the deck. Don't cluster all recall cards at the top.

按顺序处理3.5步得到的概念列表，处理每个概念时，写卡之前先确定卡片类型：

阅读概念和它的R/T标记
明确声明：“这是记忆卡”或者“这是思考卡”
应用对应的规则——不要混用类型
如果你发现自己写的记忆卡正面配了思考卡长度的答案，立刻停下。要么把答案精简成事实（记忆卡），要么把正面重写成为什么/如何类问题（思考卡）。绝对不要让卡片类型从你写的内容里隐式形成。

应用

references/LEARNING-SCIENCE.md

里的三个学习科学原则：最小信息（每张卡仅一个概念）、检索练习（倒逼回忆，不要给答案提示）、精细化提问（思考卡通过

why

字段引导更深层次思考）。

记忆卡规则：

直接明确的问题（不超过40个单词），原子化的答案（不超过15个单词）
正面必须以
```
?
```
结尾
重点覆盖核心术语、公式和关联关系
不需要
```
why
```
字段
难度：
```
basic
```
（基础）或
```
intermediate
```
（中级）
答案只放事实，不要推理、不要展开、不要出现“because”。如果答案需要解释，那它应该是思考卡。

思考卡规则：

重点考察理解能力，而非死记硬背
正面必须是明确的为什么或如何类问题
必须有
```
why
```
字段（单个问题，不超过20个单词）
难度：
```
intermediate
```
（中级）或
```
advanced
```
（高级）
答案必须包含推理链（BECAUSE/THEREFORE），不能只是事实，长度20-40个单词。
正面形式多样化：场景题、反事实题、比较题、因果链题。每个卡组最多2张卡使用“为什么[资料]认为...”模板。

混合排布：卡组里记忆卡和思考卡交替排列，不要把所有记忆卡都放在顶部。

5. Self-Check Before Writing

5. 写卡前自检

Read through your cards as if you're a student who read the lesson last month:

Does every front make sense without seeing the lesson? (self-contained)
Could a parrot answer this? If yes, it's recall — make sure it's marked that way
Are the thinking cards actually testing understanding, or just recall with extra words?
Read each thinking card back: does it contain a BECAUSE/THEREFORE reasoning chain, or just a memorizable fact?
Did I skip any concept that a student would be embarrassed not to know?
Is any card testing two things? Split it. (Check for "and" joining two questions.)
Does any back start with "Yes" or "No"? Rephrase. (The validator script rejects these.)
Are recall backs under 15 words? If not, trim to just the fact.
Are thinking backs under 40 words? If not, you're testing too many things.
Does every front end with
```
?
```
Do all thinking cards include a non-empty
```
why
```
field?
Do recall cards avoid
```
why
```
entirely?
Do thinking fronts explicitly contain
```
Why
```
or
```
How
```
?
Are recall/thinking counts roughly 50/50 (target band: 45%-55% each)?
Do no more than 2 thinking fronts use "Why does the [source] argue/say/recommend..."?
Difficulty distribution: basic 25-35%, intermediate 45-55%, advanced 15-25%? (If basic >40%, promote some cards.)
Every number, percentage, and proper noun on a card appears verbatim in the source lesson. If you inferred or calculated a figure, either verify it against the text or remove it.

假设你是上个月读过这门课的学生，通读你写的卡片：

所有正面不看课程也能看懂吗？（满足自包含要求）
鹦鹉能回答这张卡吗？如果可以，它就是记忆卡，确保标记正确
思考卡真的在测试理解能力，还是只是加了多余文字的记忆卡？
读每张思考卡的答案：里面有BECAUSE/THEREFORE推理链吗，还是只是可以背诵的事实？
有没有漏掉任何学生不知道会显得很丢人（应该掌握）的概念？
有没有卡片同时测试两个内容？有的话拆分。（检查有没有用“and”连接两个问题）
有没有答案以“Yes”或“No”开头？有的话重写。（校验脚本会拒绝这类答案）
记忆卡的答案都不超过15个单词吗？如果没有，精简到只保留事实。
思考卡的答案都不超过40个单词吗？如果没有，说明你测试的内容太多了。
所有正面都以
```
?
```
结尾吗？
所有思考卡都包含非空的
```
why
```
字段吗？
记忆卡完全没有
```
why
```
字段吗？
思考卡的正面明确包含“Why”或“How”吗？
记忆卡/思考卡的数量大致是50/50吗？（目标区间：各占45%-55%）
使用“Why does the [source] argue/say/recommend...”模板的思考卡不超过2张吗？
难度分布：基础25-35%，中级45-55%，高级15-25%吗？（如果基础占比超过40%，提升部分卡片的难度等级）
卡片上的所有数字、百分比、专有名词都和原课程内容完全一致吗？如果你推断或计算了某个数字，要么和原文核对确认，要么删掉。

5.5 Coverage Audit

5.5 覆盖度审核

After generating all cards, re-read the lesson's headings and key lists. Check each:

Every H2/H3 heading has at least one card
Every numbered list in the lesson (e.g., "eight objections", "three pillars", "four monetization models") has:
- One recall card that names/enumerates the items
- At least one thinking card that tests understanding of an individual item
If the lesson introduces N named concepts and your deck has fewer than N/2 cards, you're under-covering
Cross-reference against your concept list from step 3.5 — any uncarded concepts?

If a section is deliberately skipped (anecdote, motivational aside), note it in the report. Otherwise, add cards.

生成所有卡片后，重新阅读课程的标题和核心列表，检查每一项：

每个H2/H3标题都至少对应1张卡
课程里的每个编号列表（比如“8个反对意见”、“三个支柱”、“4种盈利模式”）都满足：
- 至少1张记忆卡用来命名/枚举条目
- 至少1张思考卡用来测试对单个条目的理解
如果课程介绍了N个命名概念，你的卡组卡片数量少于N/2的话，说明覆盖度不够
和3.5步的概念列表交叉核对——有没有没做成卡片的概念？

如果是故意跳过了某个部分（轶事、激励性旁白），在报告里注明，否则补充对应的卡片。

5.6 Type Purity Check

5.6 类型纯度检查

Run a focused pass on every card to catch hybrids:

For each thinking card, read ONLY the back:

Does it contain a BECAUSE, THEREFORE, or causal link?
Could someone memorize this back as a bullet point? If yes → reclassify as recall (trim back, remove
```
why
```
).

For each recall card, read ONLY the back:

Is it under 15 words?
Does it contain "because" or an explanation? If yes → reclassify as thinking (add
```
why
```
, rewrite front as Why/How).

If any card changes type, update its difficulty accordingly (recall defaults to basic/intermediate, thinking defaults to intermediate/advanced).

对每张卡做针对性检查，找出混合类型的卡片：

对每张思考卡，仅读答案：

里面包含BECAUSE、THEREFORE或者因果关联吗？
有人能把这个答案当成要点背下来吗？如果可以 → 重新分类为记忆卡（精简答案，移除
```
why
```
字段）。

对每张记忆卡，仅读答案：

长度在15个单词以内吗？
里面包含“because”或者解释内容吗？如果有 → 重新分类为思考卡（添加
```
why
```
字段，把正面重写成为什么/如何类问题）。

如果有卡片变更了类型，对应更新难度（记忆卡默认是基础/中级，思考卡默认是中级/高级）。

6. Write the YAML

6. 编写YAML

Write

<lesson-basename>.flashcards.yaml

adjacent to the

.md

file. Follow the schema in

references/YAML-SCHEMA.md

在.md文件的同级目录编写

<lesson-basename>.flashcards.yaml

文件，遵循

references/YAML-SCHEMA.md

里的 schema。

6.5 Mandatory Quality Gate (Do Not Skip)

6.5 强制质量门禁（不得跳过）

Before you finalize, enforce these constraints:

Card IDs must match
```
^{deck.id}-\d{3}$
```
exactly. Never shorten the prefix (for example
```
preface-001
```
is invalid if
```
deck.id
```
is
```
preface-agent-native
```
).
Every card
```
front
```
ends with
```
?
```
.
Every thinking card has a non-empty
```
why
```
field.
No recall card includes a
```
why
```
field.
Thinking card fronts explicitly include
```
Why
```
or
```
How
```
.
Recall/thinking balance is within 45%-55% each.
Recall fronts remain under 40 words.
No card back starts with
```
Yes
```
or
```
No
```
.
Recall backs under 15 words. Count them. If over, trim to just the fact.
Thinking backs 20-40 words. Lead with the insight, add one reasoning step.
No compound questions. If a front has "and" joining two questions, split into two cards.
Thinking front variety. No more than 2 cards per deck use "Why does the [source] argue/say/recommend..." — use scenarios, counterfactuals, and comparisons instead.
Difficulty distribution. basic: 25-35%, intermediate: 45-55%, advanced: 15-25%. If basic >40%, promote cards. If advanced = 0%, promote deepest thinking cards.

If any gate fails, revise cards and re-check before returning the final output.

最终定稿前，必须满足以下约束：

卡片ID必须完全匹配
```
^{deck.id}-\d{3}$
```
格式，绝对不要缩短前缀（比如如果
```
deck.id
```
是
```
preface-agent-native
```
，那
```
preface-001
```
就是无效ID）。
所有卡片的
```
front
```
都以
```
?
```
结尾。
所有思考卡都有非空的
```
why
```
字段。
记忆卡都没有
```
why
```
字段。
思考卡的正面明确包含“Why”或“How”。
记忆卡/思考卡的占比都在45%-55%区间内。
记忆卡正面不超过40个单词。
没有卡片的答案以
```
Yes
```
或
```
No
```
开头。
记忆卡答案不超过15个单词，逐词计数，超过的话精简到只保留事实。
思考卡答案长度为20-40个单词，开头放核心观点，加一个推理步骤。
没有复合问题，如果正面用“and”连接了两个问题，拆成两张卡。
思考卡正面形式多样化，每个卡组最多2张卡使用“Why does the [source] argue/say/recommend...”模板，尽量用场景题、反事实题、比较题。
难度分布：基础25-35%，中级45-55%，高级15-25%。如果基础占比超过40%，提升部分卡片的难度；如果没有高级卡片，把最深层的思考卡提升为高级。

如果任何门禁不满足，修改卡片后重新检查，再输出最终结果。

7. Heading Convention

7. 标题规范

When adding flashcards to a lesson

.md

file, use:

markdown

undefined

给课程.md文件添加闪卡时，使用以下格式：

markdown

undefined

Flashcards Study Aid

<Flashcards /> ```

Card ID Strategy (Prevents Collisions)

卡片ID策略（避免冲突）

Card IDs must be globally unique across all decks in the book. Use the full
deck.id
as the card prefix:

yaml

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

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

This prevents collisions when multiple lessons in the same chapter generate cards. The validator at

apps/learn-app/scripts/validate-flashcards.ts

checks global uniqueness across all decks.

Deck ID convention:

<section>-<lesson-slug>

in kebab-case.

preface-agent-native

ch01-factory-paradigm

ch05-reusable-skills

For lessons with numeric prefixes:
```
ch05-03-skills
```
(chapter 5, lesson 03)

卡片ID在全书所有卡组中必须全局唯一，使用**完整的

deck.id

**作为卡片前缀：

yaml

deck:
  id: "ch05-reusable-skills" # 全局唯一的卡组ID

cards:
  - id: "ch05-reusable-skills-001" # 完整卡组ID + 序号
  - id: "ch05-reusable-skills-002"

这样可以避免同一个章节下多个课程生成卡片时出现ID冲突，

apps/learn-app/scripts/validate-flashcards.ts

里的校验器会检查所有卡组的ID全局唯一性。

卡组ID规范：

<section>-<lesson-slug>

，使用短横线命名法。

示例：

preface-agent-native

、

ch01-factory-paradigm

、

ch05-reusable-skills

带数字前缀的课程：
```
ch05-03-skills
```
（第5章，第03课）

Difficulty

难度说明

```
basic
```
— Can you recall this fact? (definitions, identifications, lists)
```
intermediate
```
— Can you apply this? (scenarios, comparisons, causal reasoning)
```
advanced
```
— Can you evaluate or create? (critique, predict consequences, synthesize)

Target: 25-35% basic, 45-55% intermediate, 15-25% advanced. Count after generating all cards. If basic >40%, promote complex recall cards to intermediate. If advanced = 0%, promote the deepest thinking cards to advanced. Every deck should have at least 1-2 advanced cards.

```
basic
```
（基础）—— 你能回忆起这个知识点吗？（定义、识别、列表）
```
intermediate
```
（中级）—— 你能应用这个知识点吗？（场景、比较、因果推理）
```
advanced
```
（高级）—— 你能评估或创造吗？（批判、预测后果、综合）

目标分布：25-35%基础，45-55%中级，15-25%高级。生成所有卡片后统计占比，如果基础占比超过40%，把复杂的记忆卡提升为中级；如果没有高级卡片，把最深层的思考卡提升为高级，每个卡组至少要有1-2张高级卡片。

Chapter Mode

章节模式

When generating for an entire chapter:

```
ls <chapter-dir>/*.md
```
— discover lessons
Skip README.md, index.md, category.json
Generate for each lesson sequentially
Each lesson gets its own deck with its own
```
deck.id
```
— no shared IDs

为整个章节生成闪卡时：

执行
```
ls <chapter-dir>/*.md
```
—— 发现所有课程文件
跳过README.md、index.md、category.json
按顺序为每个课程生成闪卡
每个课程有自己独立的卡组和
```
deck.id
```
，不要共享ID

Cross-Deck Awareness

跨卡组感知

When generating for related lessons (same chapter, same part, or book-level pages like thesis/preface):

Check for existing
```
.flashcards.yaml
```
files in sibling directories
If a concept already has a card in a sibling deck, either skip it or card it from a distinctly different angle
Never duplicate the same concept with the same framing across decks

为关联课程生成闪卡时（同一章节、同一部分，或者 thesis/前言这类全书级页面）：

检查同级目录下是否已有.flashcards.yaml文件
如果某个概念在同级卡组里已经有对应的卡片，要么跳过这个概念，要么从完全不同的角度出题
绝对不要在不同卡组里用相同的出题框架考同一个概念

Common Mistakes

常见错误

What goes wrong	How to fix it
All cards feel the same	Check: is each card clearly recall OR thinking? Not a muddy mix.
Cards aren't self-contained	Add context to the front: "In the Agent Factory model, ..."
Thinking cards are just recall with "Why"	Read the back: does it have BECAUSE/THEREFORE reasoning? If not, it's recall.
Recall back is a paragraph	Under 15 words. Just the fact. No "because", no elaboration.
Thinking back is an essay	20-40 words. Key insight + one reasoning step. Split if longer.
Front has "X and Y?" compound question	Split into two cards. One concept per card, always.
All thinking fronts say "Why does the text..."	Max 2 per deck. Use scenarios, counterfactuals, comparisons instead.
50% basic difficulty	Target: 25-35% basic. Promote complex recall to intermediate.
0% advanced cards	Target: 15-25%. Promote deepest thinking cards.
`why` repeats the front	Push to a different dimension: implications, prevention, adjacent concepts
Too many cards about minor details	Would a student be embarrassed not to know this? If not, cut it.
ID uses shortened prefix (e.g. `preface-001` )	Card IDs must be `deck.id-NNN` (full prefix, no abbreviations).
YAML special chars break parsing	Quote strings with `: # " '`
Card back starts with "Yes"/"No"	Validator rejects these. Rephrase directly.
Same concept in two sibling decks	Skip or card from a different angle. Never duplicate.
Thinking card back is a memorizable list	Disguised recall. Read the back: is there BECAUSE/THEREFORE? If not, reclassify.
Recall back over 15 words	It's either a thinking card in disguise (add `why` , rewrite front) or too verbose (trim).
Skipped entire sections of a numbered framework	Enumeration rule: N items = N cards minimum. Don't summarize 8 things into 2 cards.
No concept list before generation	Always extract concepts first (step 3.5). Cards without a concept map drift.
Unverified numbers on cards	Every stat must appear verbatim in the source. Don't infer or calculate figures.

问题点	修复方案
所有卡片感觉都差不多	检查：每张卡是不是明确的记忆卡或思考卡？不要模糊混合。
卡片不满足自包含要求	给正面补充上下文：比如“In the Agent Factory model, ...”
思考卡只是加了“Why”的记忆卡	读答案：里面有BECAUSE/THEREFORE推理过程吗？没有的话就是记忆卡。
记忆卡答案是整段文字	控制在15个单词以内，只放事实，不要“because”，不要展开。
思考卡答案是小作文	控制在20-40个单词，核心观点+一个推理步骤，太长就拆分。
正面有“X and Y?”这类复合问题	拆成两张卡，永远保证每张卡只有一个概念。
所有思考卡正面都用“Why does the text...”开头	每个卡组最多2张这类卡片，多用场景题、反事实题、比较题。
基础难度占比50%	目标是25-35%基础，把复杂的记忆卡提升为中级。
没有高级卡片	目标是15-25%高级，把最深层的思考卡提升为高级。
`why` 字段和正面问题重复	切换到不同的维度：影响、预防、关联概念等。
太多关于次要细节的卡片	学生不知道这个内容会觉得丢人吗？不会的话就删掉。
ID用了缩短的前缀（比如 `preface-001` ）	卡片ID必须是 `deck.id-NNN` 格式（完整前缀，不要缩写）。
YAML特殊字符导致解析失败	包含 `: # " '` 的字符串要加引号。
卡片答案以“Yes”/“No”开头	校验器会拒绝这类内容，直接重写。
同一个概念出现在两个同级卡组里	要么跳过，要么从不同角度出题，绝对不要重复。
思考卡答案是可以背诵的列表	属于伪装的记忆卡，读答案：里面有BECAUSE/THEREFORE吗？没有的话重新分类。
记忆卡答案超过15个单词	要么是伪装的思考卡（加 `why` 字段，重写正面），要么太啰嗦（精简）。
跳过了编号框架的整个部分	枚举规则：N个条目最少对应N张卡，不要把8个内容总结成2张卡。
生成前没有做概念列表	永远先提取概念（第3.5步），没有概念映射的卡片会偏离主题。
卡片上的数字没有验证	所有统计数据必须和原文完全一致，不要推断或计算数字。

Report

报告

After generation, output:

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)

生成完成后输出以下内容：

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

参考资料

references/LEARNING-SCIENCE.md
— Cognitive science foundations (retrieval practice, minimum information, elaborative interrogation)
references/CARD-TYPES.md
— Card type examples and anti-patterns
references/YAML-SCHEMA.md
— Exact YAML schema, field constraints, escaping rules

references/LEARNING-SCIENCE.md
—— 认知科学基础（检索练习、最小信息、精细化提问）
references/CARD-TYPES.md
—— 卡片类型示例和反模式
references/YAML-SCHEMA.md
—— 精确的YAML schema、字段约束、转义规则

generate-flashcards

Original

Translation

Generate Flashcards

生成闪卡

What Makes a Good Card

什么是好的卡片

Recall Cards (half the deck)

记忆卡（占卡组的一半）

BAD: Too vague — what kind of "pillars"? Not self-contained.

不合格：表述太模糊——什么类型的“pillars”？不满足自包含要求

BAD: Tests recognition, not recall — the answer is in the question.

不合格：测试的是识别能力而非记忆能力——答案已经在问题里了

BAD: Tests two things at once — split into two cards.

不合格：同时测试两个内容——拆成两张卡

BAD: Back is a paragraph — just give the fact, not the explanation.

不合格：答案是整段文字——只放知识点，不要解释

FIXED: back: "AI employees (Digital FTEs)"

修正后答案: "AI employees (Digital FTEs)"

Thinking Cards (half the deck)

思考卡（占卡组的一半）

Scenario — student must reason about what's missing

场景题——学生需要推理缺失的部分

Counterfactual — what breaks if you remove X?

反事实题——如果去掉X会出现什么问题？

BAD: This is just a recall card with "Why" stapled on.

不合格：只是加了个“Why”的记忆卡而已

BAD: Disguised recall — the back is a memorizable before/after comparison, not reasoning.

不合格：伪装的记忆卡——答案是可以背诵的前后对比，没有推理过程

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?"

front: "Why does shifting from operator to supervisor require new skills, not just less work?"

BAD: Answer is too short — no reasoning shown.

不合格：答案太短——没有体现推理过程

BAD: Front is so long it becomes a reading exercise, not a thinking exercise.

不合格：问题太长，变成了阅读理解题，不是思考题

BAD: Formulaic — 6 cards in one deck all start with "Why does the lesson argue..."

不合格：模板化——一个卡组里有6张卡都以“Why does the lesson argue...”开头

FIXED: "Open-source AI models are available but governments still build proprietary systems. Why?"

修正后："Open-source AI models are available but governments still build proprietary systems. Why?"

The why Field

why字段

Self-Contained Rule

自包含规则

Card Generation Process

卡片生成流程

1. Find the Lesson

1. 找到课程文件

"ch N" or "chapter N" — substitute the chapter number:

"ch N" 或者 "chapter N" —— 替换成对应的章节号:

Bare lesson name:

直接通过课程名称查找:

2. Check for Existing Flashcards

2. 检查是否已有闪卡

Use absolute path — CWD may vary

使用绝对路径 —— 当前工作目录可能会变化

3. Read the Lesson

3. 阅读课程内容

3.5 Extract Concept List

3.5 提取概念列表

4. Generate Cards

4. 生成卡片

5. Self-Check Before Writing

5. 写卡前自检

5.5 Coverage Audit

5.5 覆盖度审核

5.6 Type Purity Check

5.6 类型纯度检查

6. Write the YAML

6. 编写YAML

6.5 Mandatory Quality Gate (Do Not Skip)

6.5 强制质量门禁（不得跳过）

7. Heading Convention

7. 标题规范

Flashcards Study Aid

Flashcards Study Aid

Card ID Strategy (Prevents Collisions)

卡片ID策略（避免冲突）

Difficulty

The
`why`
Field

`why`
字段