generate-flashcards

生成闪卡

根据课程内容生成两种卡片——用于巩固关键事实的回忆卡，以及促使真正理解的思考卡。各占一半。仅此而已。务必先制定计划，使用你的任务工具整理计划并跟踪进度。

优质卡片的特点

先阅读本节。其余内容都是操作细则。

回忆卡（占卡片总数的一半）

遵循最少信息原则（一个问题，一个答案）。问题要简洁明确（少于 40 个词）。确保每张卡片都能独立使用，且只考查一个概念。重点关注关键术语、公式和关系。学生应能在 5 秒内作答。

检验方法：遮住卡片背面——读过课程内容的学生能否凭记忆给出答案？如果可以，这张卡就合格。如果卡片正面没有提供作答所需的背景信息，就不合格。

答案长度：回忆卡的答案必须少于 15 个词。只给出事实——不解释、不展开。如果需要更多词，那就是在解释（这属于思考卡），或者在考查两件事（应拆分）。

每张卡片只问一个问题：如果正面用“和”连接了两个不同的问题，就拆成两张卡片。“X 是什么，为什么它很重要？”＝两个问题。

优质回忆卡：

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

思考卡（占卡片总数的一半）

重点关注理解，而非死记硬背。问题本身必须是一个为什么或如何问题，以鼓励深入思考并促使学生进行推理，而不是单纯回忆。这类卡片需要 10-30 秒作答。

检验方法：回答这张卡片是否需要学生_思考_，而不只是_记忆_？如果鹦鹉也能作答，那它就不是思考卡。

推理链检验：只读答案。里面是否包含因为或因此——也就是一条真正的因果链？还是一个可以从要点中直接记住的事实？如果答案里没有推理，那它就是伪装成思考卡的回忆卡。请重新分类或改写。

答案长度：思考卡的答案应为 20-40 个词。先给出关键见解，再补充一个推理步骤。超过 40 个词＝考查了多件事或写成了一篇文章。

正面形式多样化：在整套卡片中变换思考卡的形式。使用情境、比较、反事实和因果问题——不要总是问“为什么 [来源] 认为……”。每套卡片最多 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 周后复习卡片时，早已忘记课程结构。如果卡片正面写着“第三个要素是什么？”——是哪里的第三个要素？务必将术语放在其上下文中。

卡片生成流程

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 文件。阅读时，找出：

• 值得记忆的内容——学生必须熟记的关键术语、框架、编号列表和定义
• 值得理解的内容——因果机制、权衡、决策框架，以及“为什么选 X 而不是 Y”这类问题

优先级指南（从高到低，衡量内容是否值得制卡）：

1. 定义和命名概念（学生若无法定义这些术语，就无法运用它们进行思考）
2. 框架和模型（支柱、阶段、层级——结构性骨架）
3. 编号列表和枚举（容易记得不完整，卡片可以避免这一点）
4. 因果论断和权衡（为什么 X 优于 Y，以及 Z 失效时会出现什么问题）
5. 体现某项原则的示例（为抽象概念提供具体锚点）

跳过：轶事、历史背景、励志旁白，以及对同一要点的重复解释。

卡片密度：每 150–200 个散文词目标约制作 1 张卡片（不计代码块或配置示例）。至少制作 8 张卡片（内容较少的课程也有核心概念）。最多制作 25 张卡片（较长的课程应挑选最重要的内容，不必面面俱到）。如果课程中值得制卡的概念少于 8 个，就制作更少的卡片——绝不要用填充内容凑数。

枚举规则：如果课程围绕编号列表展开（例如“8 条异议”“5 个部署阶段”“4 种变现模式”），每个条目都至少需要一张卡片——用于回忆（命名／定义）或思考（检验对该条目的理解）。不要把 N 个条目概括成 2 张卡片。学生若“只记得 8 项中的 3 项”，就说明没有掌握这个框架。

3.5 提取概念列表

编写任何卡片之前，先列出课程中所有值得制卡的概念，并为每个概念标注其候选类型：

• R = 回忆类候选（定义、命名框架、枚举、关键术语）
• T = 思考类候选（因果机制、权衡、决策、“为什么选 X 而不是 Y”）

示例：

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 标题是否至少对应一个概念？
• 课程中定义的关键术语是否有遗漏？
• 如果课程介绍了编号框架（例如“8 条异议”），是否涵盖了每个条目？
• R/T 的比例是否大致均衡？

只有完成以上步骤后，才能开始生成卡片，并以此列表为依据。 编写的每张卡片都必须对应列表中的一个概念。如果生成的卡片无法对应任何已列出的概念，要么将该概念补充到列表中（说明确实有所遗漏），要么删掉这张卡片（因为它是填充内容）。

4. 生成卡片

按照步骤 3.5 中的概念列表逐一处理。对于每个概念，先确定卡片类型，再开始编写：

1. 阅读概念及其 R/T 标签
2. 声明：“这是一张回忆卡”或“这是一张思考卡”
3. 应用下方对应的规则——不要混用
4. 如果你发现自己写出的回忆卡正面配上了思考卡长度的背面，立即停止。要么将背面精简为一个事实（回忆卡），要么将正面改写成 Why/How 问题（思考卡）。不要让卡片类型由你恰好写下的内容来决定。

应用 references/LEARNING-SCIENCE.md 中的三项学习科学原则：最小信息量（每张卡只包含一个概念）、检索练习（促使回忆，绝不暗示答案）和精细化追问（思考卡通过 why 深入追问）。

回忆卡：

• 直接明确的问题（少于 40 个词），原子化答案（少于 15 个词）
• 正面必须以 ? 结尾
• 聚焦关键术语、公式和关系
• 不包含 why 字段
• 难度：basic 或 intermediate
• 背面 = 仅包含事实。不解释、不展开、不使用“因为”。如果背面需要解释，那就是思考卡。

思考卡：

• 聚焦于理解，而非死记硬背
• 正面必须是明确的 Why 或 How 问题
• 必须包含 why 字段（单个问题，少于 20 个词）
• 难度：intermediate 或 advanced
• 背面必须包含推理链（BECAUSE/THEREFORE），而不只是事实。20-40 个词。
• 变换正面形式：情景、反事实、比较、因果链。每套卡片中使用 “Why does the [source] argue...” 的卡片最多 2 张。

交替编排——在整套卡片中交替使用回忆卡和思考卡。不要把所有回忆卡都集中在前面。

5. 编写前自检

像一个上个月读过这节课的学生一样，通读卡片：

• 每张卡的正面是否无需查看课程内容也能理解？（自成一体）
• 鹦鹉学舌也能答对吗？如果能，这就是回忆卡——确保标注正确。
• 思考卡是否真的在考查理解，还是只是在回忆卡上增加了些文字？
• 逐一阅读每张思考卡的背面：是否包含 BECAUSE/THEREFORE 推理链，还是只有可死记硬背的事实？
• 是否漏掉了任何学生不知道会觉得难为情的概念？
• 是否有卡片考查了两件事？拆分它。（检查是否用 “and” 连接了两个问题。）
• 是否有背面以 “Yes” 或 “No” 开头？改写。（验证脚本会拒绝这种写法。）
• 回忆卡背面是否都少于 15 个词？如果不是，精简到只剩事实。
• 思考卡背面是否都少于 40 个词？如果不是，说明考查的内容太多。
• 每张卡的正面是否都以 ? 结尾？
• 所有思考卡是否都包含非空的 why 字段？
• 回忆卡是否完全不包含 why？
• 思考卡正面是否明确包含 Why 或 How？
• 回忆卡和思考卡的数量是否大致各占 50%（目标范围：各占 45%-55%）？
• 使用 “Why does the [source] argue/say/recommend...” 的思考卡正面是否不超过 2 张？
• 难度分布是否为：basic 占 25-35%，intermediate 占 45-55%，advanced 占 15-25%？（如果 basic 超过 40%，就提升部分卡片的难度。）
• 卡片上的每个数字、百分比和专有名词是否都在源课程中原样出现？如果数字是推断或计算得出的，请对照文本核实，或将其删除。

5.5 覆盖范围审查

生成所有卡片后，重新阅读课程的标题和关键列表。逐项检查：

• 每个 H2/H3 标题至少对应一张卡片
• 课程中的每个编号列表（例如“八项异议”“三个支柱”“四种变现模式”）都有：
  • 一张列出或枚举这些项目的回忆卡片
  • 至少一张考查对单个项目理解的思考卡片
• 如果课程引入了 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 个词。**开头先给出洞见，再补充一个推理步骤。
11. **不得有复合问题。**如果正面用“and”连接两个问题，请拆成两张卡片。
12. **思考卡片正面应有多样性。**每副卡组中，使用“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"

这样可以避免同一章中的多个课程生成卡片时发生冲突。验证器 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。每副卡组至少应有 1-2 张 advanced 卡片。

章节模式

为整个章节生成卡片时：

1. ls <chapter-dir>/*.md — 查找课程
2. 跳过 README.md、index.md、category.json
3. 按顺序为每节课程生成卡片
4. 每节课程都有自己的卡组和 deck.id，不得共享 ID

跨卡组关联

为相关课程（同一章节、同一部分，或论文／前言等书籍级页面）生成卡片时：

1. 检查同级目录中是否已有 .flashcards.yaml 文件
2. 如果某个概念已出现在同级卡组中，要么跳过，要么从明显不同的角度制卡
3. 不得在不同卡组中用相同的切入方式重复相同概念

常见错误

问题	修正方法
所有卡片都感觉一样	检查：每张卡片是否明确属于回忆型或思考型？不要混杂不清。
卡片无法独立理解	在正面补充背景：“在 Agent Factory 模型中，……”
思考型卡片只是加了“为什么”的回忆题	查看背面：是否有“因为／因此”的推理？如果没有，就是回忆型。
回忆型卡片的背面是一段话	少于 15 个词。只写事实。不要写“因为”，也不要展开说明。
思考型卡片的背面像一篇作文	20–40 个词。写出关键洞见和一个推理步骤。更长的话就拆分。
正面包含“X 和 Y？”这样的复合问题	拆成两张卡片。每张卡片只考一个概念。
所有思考型卡片的正面都写着“文本为什么……”	每个卡组最多 2 张。改用情境、反事实和比较等方式。
基础难度卡片占 50%	目标：25–35%。将复杂的回忆型卡片提升为中级难度。
没有高级卡片	目标：15–25%。将最深入的思考型卡片提升为高级难度。
why 只是重复正面内容	转向不同维度：影响、预防措施、相关概念
关于次要细节的卡片太多	学生不知道这点会觉得难为情吗？如果不会，就删掉。
ID 使用缩短的前缀（例如 preface-001）	卡片 ID 必须为 deck.id-NNN（使用完整前缀，不得缩写）。
YAML 特殊字符导致解析失败	为包含 : # " ' 的字符串加引号
卡片背面以“Yes”或“No”开头	验证器会拒绝。请直接改写。
相同概念出现在两个同级卡组中	跳过，或从不同角度制卡。绝不重复。
思考型卡片的背面是可供记忆的列表	这是伪装成思考题的回忆题。查看背面：是否有“因为／因此”？如果没有，就重新分类。
回忆型卡片的背面超过 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 架构、字段限制和转义规则