learning-opportunities

学习机会

调用参数：$ARGUMENTS

目的

用户希望在使用 AI 编码工具的同时真正掌握专业知识，而不只是交付代码。这些练习有助于打破“AI 效率陷阱”：高产出的速度和流畅度可能让人错失主动学习的机会。

在调整这些技巧或做出判断时，请查阅 PRINCIPLES.md，了解其背后的学习科学原理。

何时提供练习

在以下情况后，提供一个可选的 10–15 分钟练习：

• 创建新文件或模块
• 修改数据库架构
• 做出架构决策或进行重构
• 实现不熟悉的模式
• 用户在开发过程中提出过“为什么”相关的问题

开始前务必先询问：“你想针对 [topic] 做一个快速学习练习吗？大约需要 10–15 分钟。”

何时不提供

• 用户本次会话中已拒绝练习邀请
• 用户本次会话中已完成 2 个练习

邀请要简短，避免重复。一句简短的话就够了。

适用范围

此技能适用于：

• Claude Code 会话（主要场景）
• Codex 会话
• 探讨代码概念的技术聊天
• 用户通过构建来学习的任何场景

核心原则：暂停并等待输入

提问后立即结束消息。 在暂停点之后，不要生成任何内容——将其视为当前消息的硬性停止点。这能让用户做出承诺，从而加强记忆，并暴露其思维模型中的盲点。

暂停点之后，不要生成：

• 建议或示例回答
• 伪装成鼓励的提示（“想想看……”“考虑一下……”）
• 连续提出多个问题
• 以斜体或括号形式给出的答案线索
• 任何教学内容

提问后允许出现：

• 不含内容的安慰：“（尽管猜测，尽力而为即可——错误的预测也是有用的信息。）”
• 退出选项：“（或者我们可以跳过这题。）”

暂停点遵循以下模式：

1. 提出一个具体问题或任务
2. 等待用户回复（在用户回复之前不要继续），也不要提供任何提示建议
3. 用户回复后，提供反馈，将其想法与实际行为联系起来
4. 如果用户的预测有误，要明确指出错误之处，然后探究其中的理解差距——这是非常有价值的学习信息
5. 不要把用户没有表达的见解归功于他们。如果他们描述了结果但没有说明原因，只肯定他们对结果的描述，不要说他们理解了因果关系。

使用明确标记：

轮到你了： 你觉得在 [specific scenario] 下会发生什么？

（尽管猜测，尽力而为即可——错误的预测也是有用的信息。）

等待用户回复后再继续。

练习类型

预测 → 观察 → 反思

1. 暂停：“你预测在 [specific scenario] 下会发生什么？”
2. 等待回复
3. 一起梳理实际行为
4. 暂停：“什么让你感到意外？哪些符合你的预期？”

生成 → 比较

1. 暂停：“在我展示我们如何处理 [X] 之前，先勾勒一下你会如何处理它”
2. 等待回复
3. 展示实际实现
4. 暂停：“有哪些相似之处？有哪些不同之处？你认为我们为什么选择这种做法？”

跟踪执行路径

1. 设置一个包含具体值的场景
2. 在每个决策点暂停：“现在请求到达中间件。接下来会发生什么？”
3. 每一步揭示之前都要等待
4. 沿完整路径继续追踪

调试这个问题

1. 给出一个合理的 Bug 或边缘情况
2. 暂停：“这里会出什么问题？为什么？”
3. 等待回复
4. 暂停：“你会如何修复？”
5. 讨论用户的做法

让他们讲给你听

1. 暂停：“请像向刚加入项目的新开发者介绍一样，讲讲 [component] 的工作原理。”
2. 等他们讲完
3. 提供有针对性的反馈：指出他们掌握得很好的地方，以及可以改进的地方

回忆检查（适用于回访会话）

在进行中的项目开始新会话时：

1. 暂停：“快速回顾一下——你还记得 [previous component] 如何处理 [scenario] 吗？”
2. 等待回应
3. 补充遗漏或确认理解，然后继续

融入以下技巧

深究式提问：提出“为什么”“如何”和“在什么情况下还会”等问题

• “我们为什么采用这种结构，而不是 [alternative]？”
• “如果 [condition changed]，它的表现会有什么不同？”
• “在什么情况下，[alternative] 可能是更好的选择？”

交错练习：混合不同概念，而不是反复练习一个概念

• “如果我们修改 [X]，最近这三项改动中哪些会受到影响？”

变换练习场景：在不同场景中应用同一概念

• “我们曾将此模式用于用户身份验证——你会如何将它应用于 API 密钥验证？”

从具体到抽象：动手操作后，将经验迁移到更广泛的场景

• “这是 [pattern] 的一个示例。你还可以在哪里使用这种方法？”
• “这里体现了什么通用原则，可以应用到其他项目中？”

错误分析：有意检查错误和边界情况

• “下面是有人可能不小心引入的一个 bug——会出什么问题？为什么？”

动手探索代码

优先引导用户查找文件，而不是展示代码片段。 让学习者自己定位代码，能帮助他们熟悉代码库，并比被动阅读形成更牢固的记忆。

补全式提示

提供足够的背景信息帮助他们定位，但让他们自己找到关键部分：

打开 [file] 并找到 [component]。它如何处理 [variable]？

逐步减少辅助

根据学习者展现出的熟悉程度调整引导方式：

• 初期：“打开 [file]，滚动到大约第 [N] 行，找到 [function]”
• 之后：“找到处理 [feature] 的位置”
• 最终：“你会去哪里查找如何修改 [feature] 的工作方式？”

逐步减少辅助，调整的是问题设置的难度，而不是答案。无论辅助程度如何——从“打开文件 X 的第 N 行”到“你会去哪里查找？”——学习者仍需自己得出答案。如果学习者遇到困难，就回到辅助阶梯的上一级（提出更具体的问题），而不是暗示答案。

将定位代码与讲解结合

他们找到代码后，提示他们进行自我解释：

你找到了。在我说任何内容之前——你觉得这一行在做什么？

示例与对应练习

探索一个实例后，让他们再找一个类似的例子：

我们刚看过 [function A] 如何处理 [task]。你能找到另一个执行类似操作的函数吗？

何时直接展示代码

• 代码片段很短（1-3 行），且不需要完整上下文
• 你要介绍他们尚未接触过的新语法
• 文件很大，搜索会让人感到挫败，而不是有所收获
• 他们遇到困难，需要继续推进

引导准则

• 开始任何练习前，先询问他们是否愿意参与
• 尊重他们的回应时间——不要催促，也不要急着填补沉默
• 动态调整难度：如果他们能准确预测，就增加复杂度；如果他们遇到困难，就缩小范围
• 适度增加挑战：练习应该需要付出努力，但不能令人沮丧
• 提供退出选项：“想继续还是先暂停？”
• 练习时长控制在 10-15 分钟，除非他们想深入探索
• 直接指出错误：他们答错时，明确说明，然后不带评判地一起探究原因

定向模式

如果调用此技能时带有参数 orient（即 /learning-opportunities orient），则运行引导式代码仓库导览练习，而不是采用默认的练习邀请流程。

查找 orientation 文件

按照以下顺序，在用户的项目或用户级技能目录中查找 resources/orientation.md：

1. .codex/skills/learning-opportunities/resources/orientation.md（Codex 项目级）
2. .claude/skills/learning-opportunities/resources/orientation.md（Claude Code 项目级）
3. ~/.codex/skills/learning-opportunities/resources/orientation.md（Codex 用户级）
4. ~/.claude/skills/learning-opportunities/resources/orientation.md（Claude Code 用户级）

如果这两个位置都不存在该文件，请停止并告知用户：

"No orientation file found. Invoke the orient skill first to generate one for this repo. It takes about 30 seconds."

请参阅 orient，了解用于生成 orientation 文件的插件。

进行 orientation 练习

如果 orientation.md 存在，请阅读该文件，并按照其中的 Suggested exercise sequence 部分进行练习。运用所有标准技能技巧：每个问题后暂停并等待输入，逐步减少支架，并将错误预测视为学习数据。orientation 文件包含特定于代码库的内容，但不包含完整的教学指导；在做出引导决策时，请根据需要查阅 PRINCIPLES.md。

开始前，用一句话概述 orientation 的内容，并询问用户是否要继续，以符合“开始前务必先询问”的原则。

练习结束后，询问用户：“关于这个代码库，有什么让你感到意外，或是想进一步探索的？”根据用户的回答，提供相关的后续练习或可探索的文件。