teach-me

技能：teach-me

内容

目的与上下文

• **目的：**按照固定的七步框架解释一件事，根据听众调整内容，并通过真实运行时证据验证“工作原理”这一步，然后清理 instrument。
• 触发条件（何时使用）：
  • 用户想深入理解某个具体事物：一个文件、一个函数、一项功能、一个子系统、一个概念或一条错误消息——“这个是怎么运行的”“给我解释一下”。
  • 用户想把这件事解释给某个具体听众——“用 ELI5 的方式讲”“该怎么跟老板说”“给设计师解释”“让我父母也能听懂”。
• **非目标：**不要用于理解整个陌生代码库（应使用 /onboard-codebase → wiki，或 /join-project → 快速只读了解）。teach-me 范围窄、讲解深入，不记录 wiki。

心智模型

听众 → 范围 + 来源 → 运行时观察（输入 → 哪一行的状态）→ 听众 · TL;DR + 类比 → 7 个部分 → 所以呢（根据听众调整深度）→ 清理 instrument。

输入和输出约定

	字段	必填？	含义
输入	要解释的事物	是	不明确 → 提出一个问题并附上建议
输入	听众	否	默认 engineer；未指定对象的“ELI5” → 5 岁儿童
输出	按输出框架组织的回答	是	包含所有部分，顺序正确
输出	图表	是	默认使用 Mermaid 内嵌图表；仅在用户同意时使用 HTML 讲解页
输出	用户代码已清理 instrument	有插入时必填	用 git diff 确认

规则与能力

• RULE-01 (MUST)：结构完整、顺序正确、不合并省略——听众 → TL;DR → 七个部分 → So what。缺少任何一个部分（包括“显而易见”或“不适用”的情况），都要明确说明缺少的原因，不能悄悄略过。
• RULE-02 (MUST)：听众改变的是表达方式，不是真相——可以删减细节，也可以为非技术人员大幅简化（传达 80% 的核心意思，胜过 100% 准确却让听众失去兴趣），但不能说错；大幅简化的地方要标注“（已简化）”。把证据压缩成一句话讲给非技术人员时，不能把结论说得比观察到的更绝对（看到一个案例，就说“一个案例”，不能说“总是”）；数字（修改次数、行数、文件数）要从 git/磁盘重新统计，不能估算。
• RULE-03 (MUST)：绝不居高临下——给 5 岁孩子解释时，要让他们觉得有趣，而不是觉得自己“被当成傻瓜”；给 manager 解释时，要让他们觉得自己有权做决定，而不是被当成什么都不懂。
• RULE-04 (MUST)：面向非技术人员时，不出现代码，包括反引号内容——不能使用代码块，也不能用 inline code 格式写文件或目录名（eval eli5 的教训：给 manager 写内容时，即使使用了 skill，也会因为用反引号写目录名而不合格）。
• RULE-05 (MUST)：用运行时证据，不要猜测：“工作原理”部分优先通过 DRIVE 运行真实代码。只有无法运行（缺少环境、需要 prod）时，才静态解释——并且明确说明“这是静态解释，尚未通过运行验证”。尚未观察到的运行时依赖 → 记入 [[150726-unknown-ledger]]，不要妄下结论。
• RULE-06 (MUST)：**临时插桩 → 清理干净：**为观察而加入的所有 print/breakpoint/debugger/console.log 都必须全部移除；结束前用 git diff 确认。
• RULE-07 (MUST)：**范围限于一项内容：**teach-me 不分析整个项目（那是 /onboard-codebase//join-project 的工作），也不编写 wiki。
• RULE-08 (MUST)：不新增 debugger——使用现有工具（pdb/debugpy · node --inspect · print/log · /run · /verify）。
• RULE-09 (MUST)：权衡与限制不能混为一谈——权衡是设计时有意做出的取舍；限制则是即使想突破也无法逾越的边界，通常会在实际使用中显现。
• RULE-10 (MUST)：系列内容涉及多个对象时，按覆盖范围计数，不按文章数量计数——当 teach-me 被重复调用以为整个 app 构建一组课程（或用户询问“够了吗”）时，不要报“N 篇”并暗示已全部覆盖：运行 skill surface-coverage（surface-coverage.py scan + check），并报告“N/M 个表面项已覆盖”，同时列出尚无课程的项（GH#191）。
• 能力：阅读代码/文档；使用现有 debugger/log 在本地运行代码；临时添加插桩（结束前移除）；不编写 wiki。

失败边界

• 无法运行（缺少环境、需要 prod）→ 静态解释，并明确说明尚未通过运行验证；尚未观察到的结论 → 记入 unknown-ledger。
• 范围不明确 → 用一句话 clarify。
• 要求理解整个项目 → cancelled，转到 /onboard-codebase//join-project。
• git diff 中仍有插桩 → 尚未完成。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出条件	失败/下一步
W01	判断	问题	确定受众	一个群体 + 他们关心的事	未说明 → 工程师
W02	判断	需要解释的内容	确定范围 + 阅读正确类型的来源	理解目的	不清楚 → 提问
W03	执行	代码/小案例	使用具体输入 DRIVE 运行时 + 临时插桩	至少一项运行时观察	无法运行 → B01
W04	判断	观察结果 + 受众	按输出框架生成内容，深度参照表格	所有模块齐全	—
W05	确定性	已插桩的代码	移除插桩，git diff	diff 干净	仍有残留 → 继续移除

各步骤详情（W01–W05 的事实依据）：

1. 确定受众 — 阅读问题，并归入下方“受众”表中的一个群体。未说明 → 默认 提问者 = 工程师（teach-me 是面向开发者的 skill）；仅出现“ELI5”/“像对 5 岁孩子解释”且未提及其他人时 → 5 岁孩子。→ 当确定一个群体 + 他们关心的事时完成。
2. 确定范围 + 阅读来源 — 用户明确指出需要解释的内容；不清楚 → 结合上下文给出提示并提一个问题。阅读正确类型的来源：代码 → 阅读代码，先理解目的再看语法；概念 → 拆解核心组成部分；错误消息 → 查找根本原因，不要复述表面文字；文档 → 提炼对受众真正重要的要点。
3. DRIVE 运行时（如果能运行）— 使用一个具体输入运行，临时添加插桩/断点，观察实际状态。若要在用户代码中插入插桩，应在副本上操作，或在第 5 步将其移除。→ 当至少有一项具体的运行时观察（输入 → 某行代码处的状态）时完成。无法运行 → 记录“静态解释”（见 Rules）。
4. 按“输出框架”生成内容 — 受众说明行 → TL;DR + 类比 → 按正确顺序排列的七个部分 → So what；每部分的深度参照“按受众划分的深度”表。→ 当所有模块齐全，且没有任何部分被留空或草草并入其他部分时完成。
5. 清理插桩 — 移除所有临时插入的 print/breakpoint/debugger；通过 git diff 确认用户代码已恢复干净。→ 当 diff 中不再有临时插桩时完成。

分支

ID	类型	条件	行为	跳过/失败	汇合
B01	恢复	无法运行代码（缺少环境，需要 prod）	进行静态解释，并明确写出“这是静态解释，尚未通过运行验证”	声称已观察到结果 → 欠下 unknown-ledger	W04
B02	用户可选	用户想要保留/分享/需要美观的图示	按 /docs-site-macos 制作 HTML 说明页，调用 /diagram 绘制图示	用户不同意 → 使用内联 mermaid	W05
B03	有条件必需	受众不具备技术背景	不使用代码块，不使用反引号；将证据压缩成一句话	—	W05

验证与停止

可检查：模块齐全且顺序正确；面向非技术受众时不使用代码/反引号；git diff 中没有插桩。需要人工判断：类比是否适合受众，语气是否居高临下。修改 skill 时，使用 eval A/B 重新测量（见 Reference — Eval）。

示例

• 正例：“给我解释一下 wiki-sync.py --check” → 工程师；用真实 repo 运行，print 退出代码 + 文件列表 ⇐ → 观察到“退出码为 3，有 2 个页面标记为 drift” → TL;DR + 七个部分，包含流程图 + 时序图 → 移除 print，git diff 干净。
• 边界/失败：“告诉老板为什么报告页面很慢”，但只有 prod 日志，无法在本地运行 → 进行静态解释并明确说明，不使用代码块/反引号，约 700 字，以建议收尾；只看到一个案例时，不要断言“总是”如此。

参考 — 你可以使用工具来验证，而不只是阅读

“它是如何运行的”必须通过真实运行时验证，不能从静态阅读中推测。在 Claude Code 环境中可用的工具：

• Python：python3 -m pdb <file>，或临时使用 breakpoint()，或使用 debugpy。更省事的方法：在关注的位置插入 print(...)/logging，然后运行。
• Node/JS：node --inspect、console.trace()、临时使用 debugger;，或在关注的位置使用 console.log。
• **概念/工具（git、HTTP、SQL……）：**在临时目录中搭建最小案例，然后实际运行（例如，执行 git init，创建两个都修改同一行的分支 → 合并 → 亲眼看到真实冲突）。
• 任何情况：内置的 /run（运行真实应用）和 /verify（驱动流程并观察行为）。使用具体输入运行，并观察具体代码行上的真实状态。

“这个函数肯定会返回 X”是猜测。“我使用输入 Y 运行，在第 Z 行设置断点，观察到状态为 W”是事实。始终优先采用事实——对所有受众都是如此。受众只会改变证据的呈现方式，不会改变必须提供证据这一要求。

参考 — 受众 — 他们关心什么、用什么来类比、适合什么语气

群体	他们关心什么	类比来源	语气
工程师（默认）	如何运行、架构、权衡、维护	他们已知的事物：“像哈希表，但是……”、熟悉的模式	准确、简洁，使用正确术语（缺少术语会让他们觉得不受尊重）
其他领域的同事	对他们的工作有什么影响、需要了解什么才能协作	共同工作、团队流程	务实，说明“这会给你带来什么变化”
经理	影响、风险、时间、成本、团队能力	业务成果、人员、预算	先讲影响，尽可能量化，最后明确需要做出的决定
总监	战略、投资回报率、竞争优势	全局、资源分配	着眼全局，简短
产品经理	用户价值、优先级、范围	用户故事、做什么／不做什么	围绕功能和用户展开
设计师	体验、交互流程、无障碍性	用户看到的屏幕和操作	围绕用户看到和点击的内容展开
本科生／研究生	理论与应用；研究生：细微差别、边缘情况、深层影响	所学课程的基础知识	学术化；术语附带简短背景说明
初高中生（≈12–17 岁）	清晰的因果关系、循序渐进	手机、社交媒体、游戏、学校生活	稍微轻松，不要“刻意装年轻”
约 10 岁儿童／五年级学生	基本因果关系	学校、体育、团队作业、电子游戏	像一位受学生喜爱的老师
5 岁儿童（使用“ELI5”时）	一个容易记住的观点	玩具、动物、糖果、游乐场、绘本	活泼、热情，句子很短
父母／年长者	理解内容，同时不觉得自己受轻视	他们正在使用的技术、家务	尊重、清晰、耐心
配偶／伴侣、朋友	容易跟上的故事	日常事务、共同经历、流行文化	温暖、聊天式，可以幽默

参考 — 输出框架（固定 — 顺序必须正确，不得省略任何部分）

Người nghe: <nhóm> — <điều họ quan tâm>
TL;DR: <MỘT câu "nó là gì"> + <MỘT phép so sánh với thứ người nghe đã biết>
    ↓
1. Tên gọi → 2. Nguồn gốc → 3. Lý do tồn tại → 4. Cơ chế hoạt động
→ 5. Trade-off → 6. Giới hạn → 7. Vị trí trong toàn bộ hệ thống
    ↓
So what: <điều này có nghĩa gì với CHÍNH người nghe — quyết định, hành động, hay điều cần nhớ>

七个部分串成一个故事：它叫什么 → 从何而来 → 为什么需要它 → 它如何运行 → 为了得到它要付出什么 → 它不能做什么 → 它在更大的全局中处于什么位置。TL;DR + 开场类比（让受众立即知道在谈什么）；So what 收尾（让受众知道可以带走什么）。目的始终先于机制——不知道它存在的目的之前，没有人关心语法。

七个标题对所有受众都保持不变（方便用户自行检查框架）；面向非技术受众时，可以增加通俗副标题，例如“5. Trade-off — 得到了什么，失去了什么”。

1. 名称

准确名称（代码／文档中使用的正式名称）、常见同义名称／术语；如果名称容易引起误解（与本质不符），也要在此处明确说明。

2. 起源

它从何而来——哪个 commit/PR/决策将它引入，借鉴了哪些思路（现成的库／论文／模式，还是自行设计），最初是什么情况催生了这项需求。如果有真实证据（git log、文件的 Origin、ADR），就引用；不要猜测。

3. 存在的理由

它解决什么问题；没有它会怎样——哪些事情会变得更难、出错或必须手动完成。必须能回答这个问题：“去掉它，谁最先头疼？”

4. 工作机制（+ 系统图和代码图）

它如何运行，分两个层面：

• 系统层面——主要组件、谁调用谁、数据流向何处、进程／服务／操作系统的边界。图示：方框 + 流向箭头。
• 代码层面——具体执行路径：哪个函数调用哪个函数、状态在哪里变化、使用已测试输入时会走哪个分支。图示：调用流程／时序图。

必须通过真实运行结果提供证据——锚定具体观察（第 Z 行、状态 W），不要像文档那样泛泛描述。

5. 权衡

为了得到这个，需要牺牲什么——选择这个方案会失去什么（例如用性能换简单、用灵活性换安全性）。如果知道曾考虑或放弃过其他方案，请明确说明放弃的原因。

6. 局限

它做不到什么，或者在哪些方面表现不佳——规模上限、未覆盖的边界情况、会导致它失效的条件。与“权衡”不同：“权衡”是“设计时有意作出的取舍”，“局限”是“无论愿不愿意，它的边界就到此为止”。

7. 在整个系统中的位置（+ 流程概览图）

它在整体图景中连接到哪里——谁调用它（上游），它调用或影响什么（下游），它位于哪一层。最后用一张端到端流程概览图收尾：输入 → 各个环节 → 输出。

参考 — 根据听众调整深度（七部分始终齐全——只调整深度）

听众	步骤 4 工作机制	步骤 5–6 的表达方式	图示	代码／术语	长度
工程师、同事、研究生	两个层面都讲清楚；引用可观察到的行和状态	性能、可维护性、边界情况	流程图 + 时序图	引用真实代码；术语准确	深入，但不啰嗦
经理、总监、PM	只讲系统层面；将运行证据概括成一句话（“已运行测试：X → Y”）	成本、风险、时间、团队投入	一张方框—箭头图	不要用代码块，不要用反引号——文件名用普通文字书写	简短——读完约需 2 分钟（≈ 500 个英文单词 ≈ 700 个越南语单词，不计图示）以建议收尾
设计师	用户可见的流程	体验、无障碍性	屏幕流程	不写代码；可以使用 UI 术语	适中
大学生、中学生	逐步说明因果关系；简化代码层面	用例子说明“选 A 就会失去 B”	一张简单图示	使用术语时，首次出现就立即定义	适中
儿童、父母、伴侣、朋友	讲成带有比喻的故事	用日常语言说明“得到什么、失去什么”	可选，非常简单	不用术语，不展示原始日志；不得不用时，立即解释	简短；面向儿童时越短越好

语言调整

• 非技术听众（儿童、非技术人士、家人）：不要用术语；一句话只表达一个意思；多用具体说法，少用抽象说法（例如“服务器像服务员”比“服务器处理客户端—服务器通信”更好）；用“你”或“孩子”拉近距离。
• 技术听众（工程师、研究生）：使用准确术语；把篇幅集中在值得关注的部分——权衡、边界情况、设计决策；联系他们已熟悉的内容进行比较；简洁，并尊重他们已有的知识。
• 商业听众（经理、总监、PM）：先讲影响和结果；可以量化时就量化；除非有人询问，否则省略实现细节；将结论表述为决策建议（“这意味着我们应该……”）。

参考 — 示例 — 同一件事，三类听众（仅开头 + So what）

需要解释的内容：database index。

• 5 岁儿童 — TL;DR：「Index 就像一本超大书的目录，能帮电脑快速找到正确的页面，不用一页页翻。」· So what：「有了目录，宝贝的游戏就能更快打开啦！」
• Manager — TL;DR：「Index 是一种能快速查找数据的结构，类似书的目录；代价是每次写入数据都会慢一点，还会多占一些空间。」· So what：「报告页面变慢是因为订单表缺少 index；添加 index 大约需要半天工作量，风险较低——建议在本次 sprint 中完成。」
• Engineer — TL;DR：「B-tree index 将 O(n) 的全表扫描查找变为 O(log n)，类似有序 hash map，但代价是每次 INSERT/UPDATE 都必须更新树。」· So what：「检查慢查询的 EXPLAIN：如果筛选列上出现 Seq Scan，可以考虑添加 index，但添加前要先测量 write amplification。」

参考 — 图示 — 两种路径

• 默认：内联 mermaid — mermaid 块（结构用 flowchart，按时间顺序的流程用 sequenceDiagram）。快速、可读作文本。
• 可选：HTML 讲解页 — 用户想要保留／分享／需要真正精美的图示时 → 按照 /docs-site-macos 渲染一个页面（glass、明暗切换、打印全路径、适合 13″ 的紧凑字号）；图示调用 /diagram。基于 [[design-foundation]]，不要另造新主题。生成文件前先询问用户，不要强加。

参考 — Eval — 修改 skill 后必须重新测量（如果仓库有 harness/scripts/wikieval.py）

参照 eli5：每个用例 = 一个 prompt + 4–5 条可验证的断言，在同一个 prompt 上运行旧版和新版 skill，然后比较通过率。

• Goldens：fdk/wiki/sources/evals/teach-me-*.md — 三个用例覆盖三类听众（engineer · manager · 5 岁儿童）；包含确定性断言（七个部分的顺序、不给 manager 提供代码、给儿童提供类比等）+ rubric 供评审者使用。
• 运行 A/B：每个 skill 版本由一个独立 Agent 针对每个 prompt 作答 → 汇总到 harness/evals/teach-me-ab-<ddmmyy>-<old|new>.json（将 golden-id 映射到回答）→ python3 harness/scripts/wikieval.py --outputs <file>。新版的通过率不得低于旧版。

起源

• 根据用户 2026-07-16 的需求提炼（teach-me：2 个层级 + 三类听众 + 总结，每个部分都有图示；skill 知道如何使用 breakpoint/debugger）。Grounded-runtime 借鉴了内置 /verify 的理念。
• 更新于 2026-08-01（Rhein 通过 /fdk 提供反馈）： 将「四部分」框架改为固定七步框架——名称 → 起源 → 存在的理由 → 工作原理 → 权衡 → 局限 → 在系统中的位置。由运行时驱动的内容 + 两个图示合并到第 4 步；总结流程的图示合并到第 7 步。
• 更新于 2026-09-11（从 dreambigou/eli5 @ a766623，MIT 吸收）： 增加确定听众的步骤（包含 12 类年龄／教育程度／角色／关系的表格，由 eli5 的四张表合并而成）、开篇和结尾框架 TL;DR + 类比 → … → So what（源自「what → analogy → details → so what」）、按听众划分的七部分深度表、三类听众的措辞调整、同一内容对应三类听众的示例、「不居高临下／简化但不能说错／不对非技术人员使用反引号」规则，以及 A/B eval 循环（eli5 的 run-evals.py --a/--b → 复用 wikieval.py + goldens，而不是复制 runner）。与 eli5 的不同之处：默认听众是 engineer（而非 5 岁儿童），七步保持不变，且所有听众都必须有运行时证据。
  • 首次 A/B（3 个用例，每个版本由独立 Agent 作答，outputs 位于 harness/evals/teach-me-ab-110926-{old,new}.json）：旧版的确定性断言为 8/13 → 新版 13/13；4 项盲评标准下，旧版为 6/12 → 新版 9/12。Manager 用例在新版中仍未通过，因为篇幅过长（约 718 个越南语词），且有一句证据陈述超出了观察结果所支持的范围 → 增加按越南语词数计算的长度阈值 + 证据精简规则（这两条规则增加后尚未重新测量）。
• 通过 /propose 吸收 → 160726-teach-me-skill，任务 T-260716-01。
• Commit： (verify-before-commit điền)