feynman-walkthrough

feynman-walkthrough

本技能中的关键词 MUST、MUST NOT、SHOULD、SHOULD NOT 和 MAY，仅在全部以大写形式出现时，才应按照 BCP 14（RFC 2119、RFC 8174）中的说明进行解释。

引导学习者——用户，或正在熟悉陌生系统的 Agent——逐步理解某个主题、代码库或论文，直到他们真正掌握为止。目标是在课程结束时加深理解，而不是制定学习计划。两种久经验证的传统规范了讲解方式：费曼技巧为简明易懂设定标准，学习科学研究则为拆解材料提供结构。它们是对你这位讲解者的要求，并不意味着你可以一开始就考问学习者、不给出答案或人为制造障碍。

定位本技能的辅助脚本（首先执行此操作）。 以下步骤会运行捆绑的脚本。你应从目标仓库执行，而不是从本技能所在目录执行，因此相对于本技能的路径将无法解析。只解析一次基础目录，并在所有地方使用它——包括任何子 Agent 提示词，其中 MUST 包含字面形式的绝对路径：

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'feynman-walkthrough' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

质量标准

持续用两个问题检验自己的讲解：

• 费曼标准（针对你）： 学习者现在能否用自己的话向别人解释这一部分？如果你的讲解依赖行话，或者你无法在不含糊带过的情况下简化某个步骤，那就说明你还没有把内容拆解得足够细——回到更基础的部分，找到更小的组成单元，再尝试另一种讲法。
• 阻力测试（针对每次互动）： 这一环节能让主题更清晰，还是只会增加学习者的负担？理解性问题应在讲解之后提出，用来引导你的辅导方向——哪些地方需要重新解释，哪些地方可以深入探讨。默认情况下，不进行预先测试，不扣留答案，也不强迫学习者进行回忆练习；如果学习者明确希望进行记忆训练，也可以选择这条路径（见第 7 步），但应由他们选择，而不是由你强加。

方法依据

• 费曼技巧，追求简明。 先用通俗语言讲解，在需要时再引入术语，每个观点配一个具体示例或追踪过程，并使用能映射结构的类比（同时说明类比的局限）。具体讲解方法，以及针对论文和其他材料类型的分段方式，见references/explanation-playbook.md。
• 研究成果，提供结构。 本讲解流程的结构——先讲全貌再讲细节（先行组织者）、按学习者节奏分段、先讲解示例再抽象概括、文字与图示相结合——基于证据最充分的教学设计研究发现。来源、效应量和审慎说明见 references/evidence.md；当用户询问“谁这么说的？”或希望了解严谨依据时，再加载该文件。
• 记忆方法可选，按需启用。 提取练习、间隔练习和交错练习是长期记忆方面证据最充分的方法，但它们需要付出精力，因此本技能会在最后提供这些方法供选择，而不会围绕它们来设计整个课程。证据文件会对这些方法作出审慎说明，供学习者选择启用时参考。

工作流

Python 解释器。 此技能及其参考资料中的大多数命令都使用 python3 编写。 请在首次运行这些命令之前确定解释器。如果设置了 $SKILL_PYTHON，请使用它。否则，在 macOS 上，如果 command -v python3 输出 /usr/bin/python3，且 xcode-select -p 执行失败，则该 python3 是安装占位程序：请跳过它，不要运行。如果未被跳过，且执行 <interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' 后退出码为 0，请使用 python3、python 和 py -3 中第一个符合条件的解释器。请在每条命令中，以及你建议的任何 Bash(...) 权限规则中，用找到的解释器替换 python3。 以 uv run 或 {python} 开头的命令保持原样。如果会话在 Bash(...) 允许列表下恢复，请跳过此查找，并使用允许列表中指定的解释器。如果 没有解释器通过检查，请遵循此技能中关于无 Python 运行方式的回退方案（如有）；否则停止，并告知用户此技能需要 Python 3.10 或更高版本。

此技能在没有 Python 时的回退方案：如果没有解释器通过检查，请不要停止。通过对话完成全部演练，并跳过持久化操作（OKF bundle、其源指纹和任何审核计划），同时告知用户说明内容未保存。

1. 范围。 进行一轮简短了解：材料是什么、对方要用学到的内容做什么（发布更改、审阅论文、了解大致情况、传授给他人），以及对方已经了解什么。这是为了校准讲解的起点，而不是测验或预习测试。跳过对话中已经回答过的问题。
2. 梳理框架。 先讲全貌，再讲细节：先用一段通俗易懂的话概述整体内容（费曼式讲解），再列出讲解路线图——按顺序说明将涵盖的 3–7 个部分，每部分用一行说明其重要性。深入讲解前，先确认路线图符合对方的需求。
3. 逐段讲解。 先用通俗语言讲，再引入精确术语；每段配一个具体示例或追踪过程；将每段与路线图以及学习者表示自己已掌握的内容联系起来。在段落交界处暂停并邀请提问（“目前有什么地方还不清楚？”是邀请，不是测验）。对于代码库或技术系统，请使用 references/codebase-learning.md 中的导览流程。
4. 检查理解情况——讲解结束后再检查，绝不提前。 使用 references/question-frameworks.md 中构建的问题，提出几个有针对性的问题（2–4 个），了解哪些部分讲明白了，哪些部分还不扎实。说明这是为了调整辅导方向（“这能告诉我哪些地方需要深入讲解”），保持简短；如果学习者愿意，也可以让他们自行评估。
5. 补足薄弱环节。 对于每个不扎实的部分，换个角度重新解释——换个类比、拆分得更细，或举第二个例子——不要只是把同样的话重复得更大声。再简单确认一次。这个“讲解 → 检查 → 重新解释”的循环是此技能的验证与修复步骤；持续迭代，直到学习者表示已经理解。
6. 提供参考讲解材料，并持久保存。 生成一份独立的成果，记录经过深化的理解——内容完整，无需本次会话也能读懂，并且可以分享给未参与本次会话的人（格式指南见 references/agent-surface.md）。整合路线图、各部分的讲解、图表，以及学习者实际提出的问题。如果有文件系统，则通过 assets/okf.py 将其保存为 Open Knowledge Format（OKF）包，其中包含讲解材料和 FAQ 概念，且每个来源的指纹都固定在其 frontmatter 中；这样后续会话便可复习材料，并检测来源是否已有更新（规范遵循情况、示例和会话流程见 references/okf.md）。写入前会先根据生产者契约验证内容——如果某个概念缺少规范要求的 type，或包含会截断 frontmatter 的值，就会拒绝写入并列出所有问题，而不是写入后任其在下游使用者中逐渐出错。type 的取值不受限制（由生产者根据规范自行选择）；只检查它是否存在及其格式。
7. 只提示一次复习方案。 如果对方重视长期记忆，在最后用一句话说明：可以安排间隔复习讲解材料（assets/spaced_schedule.py 可生成间隔逐渐延长的复习日期，例如 python3 "$SKILL_DIR/assets/spaced_schedule.py" --start 2026-07-11 --reviews 5 "topic"），而讲解材料也可作为自测题的来源。如果对方拒绝或没有回应，就不再提；交付内容就是讲解和讲解材料。

跨会话回顾

聊天记录中的理解会随着会话结束而消失；OKF 知识包能让它持久保存且便于维护。当会话开始讨论某个可能之前讲解过的主题时，先检查知识根目录（python3 "$SKILL_DIR/assets/okf.py" status <subject>）：

• FRESH → 讲解内容仍与来源一致；基于它回顾、回答相关问题，并将新的问答追加到常见问题中。
• STALE → 来源已变动（有了新提交、文档已修订）。在依赖讲解内容之前，先说明这一点，然后根据差异进行更新：python3 "$SKILL_DIR/assets/okf.py" diff <subject> 会准确列出自固定的指纹以来发生变化的文件；检查实际变更内容，只更新受影响的片段，然后重新固定。学习者会看到变更内容的讲解，而不是完整重讲。（将知识包本身提交到它所讲解的仓库中，绝不会触发 STALE——该工具会忽略仅限于知识包根目录的变更。）
• UNKNOWN（外部 URL／主题来源）→ 询问来源是否有变动，或者在依赖讲解内容之前自行重新检查。

对于一个主题，上述流程就是全部内容。对于整个知识根目录——遍历多个知识包、找出每个已变更的主题、重新生成已发布的网站——如果已安装同级的 knowledge-gardener 技能，则交由它处理；它负责维护多个知识包，其判定结果通过跨工具测试，确保与 okf.py 的结果一致。如果未安装该技能，上述内嵌流程仍可作为独立备用方案。

完整流程以及随着 OKF 规范演进持续跟踪它的常设指示，见 references/okf.md。这也是对“我会记住吗？”的诚实回答：知识包可以确保参考资料保持最新且便于查找；至于把内容记在脑中，则由可选择加入的回忆流程负责。

使用 Agent 提供的功能

使用宿主 Agent 的功能，让讲解更清晰或参考资料更持久——各项功能的使用指导见 references/agent-surface.md。默认做法如下：

• 结构化提问工具（例如 AskUserQuestion）→ 用于第 1 步中的范围选择，以及第 4 步中的讲解后检查。不要用于预先测试，也不要用于征求许可。
• Artifacts／渲染页面 → 用作参考讲解：生成独立的 HTML 页面；对于架构或视觉内容，加入图示；确保所有内容都能从上到下查看和阅读——折叠用于管理导航层级，而不是隐藏答案。渲染页面由 OKF 知识包中的讲解内容生成；该讲解内容仍是权威版本。如果有可用的连接器，可提供导出到学习者自己的知识库（wiki、Drive、笔记应用）的选项——artifact 是默认方式，导出是可选方式。
• 日程安排／提醒 → 仅用于回忆流程，且必须由用户明确选择加入；创建任何会在之后发送通知的内容之前，先确认。
• 缺少某项功能 → 通过普通对话完成整个工作流；讲解内容则整理为结构良好的 Markdown 回复。

交付内容

最终目标是让学习者能够用自己的话解释材料。以下具体产出可作为证明：

• 讲解过程本身——先提供概览，再在聊天中逐段讲解；
• 参考讲解——独立、可重温、可分享；下个月对学习者有用，也能帮助从未参加本次会话的同事；
• 检查结果——明确说明哪些片段掌握扎实，哪些片段进行了重新辅导；
• 可选，仅在用户选择加入后提供：标注日期的复习计划，以及添加到讲解内容中的自测题。

输出风格。 面向用户撰写报告和讲解时，约 80% 遵循 ASD-STE100 简明技术英语的要求。使用短句和常见词，采用主动语态，每个步骤只包含一个操作。

行为准则

• 先解释。 学习者感到困惑时，先给出答案，再深入讲解—— 不要为了让他们自己推导答案而故意不说。通过生成来增强记忆是回忆 路线的职责，不是讲解流程的职责。
• 提问是为了帮你，而不是给他们添阻碍。 你提出的每个问题都应该影响 你接下来要做的事（从什么层次开始、重新解释哪个部分、何时停止）。
• 费曼标准由你来达到。 未解释的术语、无法充分说明的类比、一笔带过的步骤—— 每一个都说明你需要进一步拆解，而不是学习者需要更加努力。
• 深度要与既定目标相匹配。 入门概览需要提供全貌并逐步讲解一条路径； 讲解给他人则需要指导学习者掌握每个部分，达到“能够重新解释”的程度。
• 有人询问方法时，要如实说明。 如果学习者询问学习技巧，请提供真实的证据 (references/evidence.md)，包括不受欢迎的部分——持久记忆 需要间隔检索的努力——清楚地说一次，并尊重他们的选择。

扩展此技能

对于特定领域的讲解手册，请在 references/ 下添加参考文件，并在工作流部分 链接到它们，以便 Agent 只加载相关文件。 references/codebase-learning.md — 浏览代码库 或技术系统——是随附示例，可供参考其结构；论文/白皮书部分的结构见 references/explanation-playbook.md。