learn-topic

name	learn-topic
version	4.2
description	Only invoke when explicitly requested via "学习"、"讲解"、"teach me"、"@learn-topic". Do NOT auto-trigger.

learn-topic

一句话定位

按 5 步认知爬升结构讲一个新主题，让读者在 7-10 分钟内达到 Bloom Apply 层级（能在新场景应用该知识，不只是理解）。

学习科学锚定（详见 references/methodology.md）：CLT 的 worked example 梯度 + UbD 倒推设计 + Make It Stick 检索练习 + Productive Failure 的"先猜后看" + 4C/ID 的 authentic task 原则。

---

📂 加载策略（按需读，不要全加载）

何时读	读哪个
第一次用，或写得不顺	references/example.md（沉没成本完整带旁注样例）
写每一步前需要详细模板	references/templates.md
想知道某个规则的"为什么"	references/methodology.md
红旗触发但拿不准要不要修	references/self-checks.md

⚠️ 禁用 @ 链接——会强制加载烧 context。让 Claude 按需读。

---

受众默认

跨领域成熟读者：在自己领域是高手，但对该主题陌生。

• ✅ 类比可从读者已熟悉的另一领域借
• ✅ 每段允许 ≤1 个未定义新术语
• ❌ 不假设读者懂该主题任何专有词汇
• ❌ 不从"什么是 HTTP"级别的前置知识开始

---

输出结构：5 步认知爬升

1. Hook + 终点告知 (120-300 字)
2. 演示 I-do          (400-700 字) 
3. 拆解               (300-600 字)
4. 半练 We-do         (300-500 字)
5. 独挑 You-do + 自检 (300-500 字)

主体总量：1500-2600 字
附录区  ：0-500 字（条件触发）

第 1 步：Hook + 终点告知（120-300 字）

• 第 1 句必须命名具体主角（给名字 + 真实场景），禁止"假设有一个..."、"你有没有遇到过..."（无主角问句）
• 首句场景必含痛点数字三件套：(1) 真实公司类型/团队规模/机构（如"80 人 SaaS 创业公司"、"三甲医院体检中心"）+ (2) 真实痛点数字（如"3 万用户"、"0.1% 患病率"、"999 元一口价"）+ (3) 真实角色职责（如"CRM 产品 PM"、"在线教育后端"）。三者缺一即重写——没有数字的"小李做小程序"是假主角。个人理财/健康类话题可放宽公司类型为"个人画像"（年龄+职业+月收入），但数字必须够具体
• 终点用动作动词："读完 X 分钟，你将能 [识别/选对/设计/判断]" —— 禁用"理解/掌握"
• 中间可有 1-2 句"桥接"连接痛点和终点

第 2 步：演示 I-do（400-700 字）

• 开头加 30 秒 PF 预测题（"先猜一下：你会选 a/b/c/d？"），激活先验
• 立单一类比（按主题类型分流：技术→程序员词汇 / 抽象→幼儿园式 / 通用→生活场景）—— 第 3-5 步必须复用，禁换比喻
• 完整 worked example：让主角逐步求解，每个决策点解释"为什么这步选 X 不选 Y"
• Worked example 必过 4 条选取标准（典型性 / 决策密度 / 可压缩 / 真实性）—— 详见 templates.md
• 类比撑不动时走 escape hatch（用最小代码代替 + 显式声明）—— 详见 templates.md
• 时序型主题（OAuth/TCP 等）在此处嵌 sequenceDiagram

第 3 步：拆解（300-600 字）

• 严格反向：所有抽象必须从第 2 步演示反推，禁引入新案例
• 每条规则必须有"边界"——什么时候不适用
• 边界至少 1 条用类比关键词重述（复用第 2 步立的类比，不是纯领域术语）。反例："纯前端 SPA 没后端会撞墙"——是术语；正例："纯前端 SPA 等于酒店没保险柜，client_secret 无处藏，要换 PKCE"——把边界翻译回类比，读者才能用类比预测新边界
• 类比破点自觉：第 3 步必须有至少 1 句明示类比在哪里失效或被简化。例："酒店房卡比喻在跨平台 SSO 时会变复杂——federated identity 不是连锁酒店那么干净" / "雪球比喻在风险层面失效——真实投资会突然缩水一半，雪球不会"。如果类比真的 1:1 干净（罕见），明确写一句"本章类比无明显破点"。沉默 = 不算——没有 explicit 声明视为缺失
• 易混对比（条件触发，否定通过制，详见 templates.md）

第 4 步：半练 We-do（300-500 字）

• 复用主角，新场景——降低认知负荷
• 问题与答案之间必须视觉分隔：💡 先想 30 秒 + --- 分隔线 + "答案" 标题
• 答案块必须含经验法则句（迁移到独挑的桥梁）

第 5 步：独挑 You-do + 自检（300-500 字）

• 必须切换到"你"——验证迁移
• 1 闭合（有标答）+ 1 开放（给思考方向）
• 同样用 💡 先想 1-2 分钟 + --- 分隔线 + "问题 N 参考答案" 标题

---

末尾附录区（条件触发，不需要的完全不写）

附录	触发条件
A 全景图（mermaid）	多角色时序 / 状态机 / ≥5 节点 ≥7 边 / 历史脉络（4 选 1）
B 术语速查表	主题含 ≥5 新术语
C 5W2H 速查	复合方法论（如 OAuth 流、限流体系）

不触发就完全不写标题，不留空段。详细规则见 references/templates.md。

---

输出保存

1. 保存目录：{cwd}/learn-topic_outputs/
2. 文件命名：{YYYY-MM-DD}_{学习主题}.md
3. 冲突处理：追加 _v2、_v3 后缀
4. 完成后：告知用户绝对路径

---

🔴 Red Flags - 见到就停手重写

🚩 红旗	修复
第 1 步终点用"理解/掌握"而不是"能 [动作]"	改成动作动词
第 1 句不是"小张做..."这种命名主角，而是"假设/你有没有..."	命名真主角
第 1 句缺痛点数字三件套（公司类型/痛点数字/角色职责）任一项	把缺失项补齐——"小李做小程序"是假主角
第 2 步没有 30 秒 PF 预测题	在 worked example 之前插入
第 2 步某步没回答"为什么这步选 X 不选 Y"	example 缺决策密度，重选
第 2 步 example 是"假设有一个..."而非真职业/真场景	违反 authenticity，重选
第 3 步引入了第 2 步没出现过的新案例	严格反向，删
第 3 步所有边界都是纯术语描述（"流量平稳时"、"内部服务调用时"），无 1 条用第 2 步类比关键词	至少把 1 条边界翻译回类比，让边界条件可视化
第 3 步从头到尾用类比，无 1 句明示"类比在 X 处失效"	加一句类比破点声明（沉默不算，必须 explicit）
第 4/5 步答案没和问题视觉分隔（缺 💡 先想 + ---）	加上分隔三件套（提示+分隔线+答案标题）
第 4 步答案块没"经验法则"句	加上
第 5 步还在用小张/老李	切换到"你"
类比中途换了	全文一个比喻，重写
第 4/5 步答案区没显式出现类比关键词（隐含/延伸不算）	加 1 句把类比关键词写进答案
出图但没过 4 条触发门槛	删图，改用表格
文档里出现"自检通过"等元注释	全删

任一命中：停 → 修 → 重跑红旗。

详细原理（每个红旗为什么是错）见 references/self-checks.md。

---

📐 量化自检

□ 第 1 步：120-300 字
□ 第 2 步：400-700 字（建议 ≤ 600，决策步骤 ≤ 4 时不要逼近 700）
□ 第 3 步：300-600 字
□ 第 4 步：300-500 字
□ 第 5 步：300-500 字（建议 ≤ 450，给迁移题留余地）
□ 主体总量目标区间 **1500-2200**（硬上限 2600）。超过 2200 必须证明每节都已压缩过——否则找字数最大那节砍
□ 类比关键词在第 3/4/5 步答案区各**显式**出现 ≥1 次（隐含/延伸不算，必须 grep 得到）
□ Worked example 过 4 条筛选（典型/决策/可压缩/真实）
□ 不需要的附录完全没出现

---

风格

• 句长档位：扫读区（表格/bullet）≤25 字；叙事区（演示/拆解/解释）≤40 字。超必拆。
• 每步 ≥1 处轻松元素：自嘲 / 反问 / 具象比喻（防教科书化）
• Emoji：仅警告（⚠️❌✅）和提示（💡💬💭🚩）
• 单代码块 ≤15 行

---

闭环

不通过 = 已修，不是只标记。修完重跑 Red Flags + 量化自检，全过才输出。