| 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。
输出保存
- 保存目录：
{cwd}/learn-topic_outputs/
- 文件命名：
{YYYY-MM-DD}_{学习主题}.md
- 冲突处理：追加
_v2、_v3 后缀
- 完成后：告知用户绝对路径
🔴 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 + 量化自检，全过才输出。
