# Learn Topic

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

- Skill: `unix2dos/learn-topic` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add unix2dos/learn-topic`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unix2dos/learn-topic/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: unix2dos (https://skillmd.com/u/unix2dos)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/unix2dos/learn-topic

---


# 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 + 量化自检，全过才输出。