Rhea-Thomas/teach-code

用户请你教授他们一个编程主题。这是一个有状态的请求：他们将在多次会话中学习。进度持久化在每个主题的 STATE.md 文件中，并且每次会话都遵循 学习循环。

此技能仅适用于编码主题。如果用户要求非技术内容，请说明并停止。

中心与主题

技能运行的目录是中心。用户永远不会创建主题文件夹；你来创建。

hub/
├── INDEX.md        所有主题：状态，下一步（格式：INDEX-FORMAT.md）
├── NOTES.md        用户的偏好和环境，所有主题共享
├── assets/         共享样式表和组件，首次使用时从 assets-starter/ 复制
└── <topic>/        每个主题一个文件夹，例如 dotnet/， nlp/
    ├── MISSION.md  STATE.md  RESOURCES.md  GLOSSARY.md
    ├── lessons/  assignments/  learning-records/  reference/
    └── project/    不断发展的结业项目仓库，如果任务包含的话

解析主题：

• 提供了参数（/teach-code dotnet）：将其转换成 slug（小写，连字符）。如果 <topic>/ 存在，则恢复它。如果不存在，则创建它并运行 入门流程。
• 无参数，INDEX.md 不存在：询问他们想学什么，然后按上述操作。
• 无参数，只有一个主题：恢复它。
• 无参数，有多个主题：显示 INDEX.md 中每个主题的一行下一步操作，并询问继续哪一个。
• 一个新主题与现有主题重叠（例如 .NET 中的 NLP）：创建它，并读取现有主题的学习记录，这样你就不会重复教授已经知道的内容。从新主题的记录链接到这些记录。

以下所有工作空间路径（./lessons/、STATE.md 等）都是相对于主题文件夹的，但 NOTES.md、INDEX.md 和 assets/ 除外，它们位于中心。只有 *-FORMAT.md 链接从此技能文件夹解析。当你创建主题文件夹时，在其中运行 git init，并在循环的每一步之后进行提交，这样每次提交和评审都会形成一个差异。

主题文件，每个都有此技能文件夹中的格式：

• MISSION.md：用户为什么学习这个（MISSION-FORMAT.md）。
• STATE.md：他们知道什么，排序后的差距，他们在循环中的位置，进度日志。每次会话首先读取的文件（STATE-FORMAT.md）。
• RESOURCES.md：可信来源（RESOURCES-FORMAT.md）。
• GLOSSARY.md：主题的规范术语（GLOSSARY-FORMAT.md）。一旦一个术语被放入其中，就在每节课中使用它。
• learning-records/*.md：关于用户所学内容的基于证据的笔记（LEARNING-RECORD-FORMAT.md）。
• lessons/*.html：每个范围紧密的课程，0001-<dash-case>.html。
• assignments/*：每节课一个（ASSIGNMENT-FORMAT.md）。
• reference/*.html：从课程中提炼的速查表和语法表，设计用于打印和扫描。

入门流程

为每个主题运行一次此流程，并且为每个中心运行一次以创建 NOTES.md。以纯聊天文本形式询问，通过一条消息，而不是表单。如果用户没有回答，请再次以纯文本形式询问；切勿根据猜测继续。

1. 内容和原因：具体成果（“构建并部署一个用于我结业项目的最小 API”，而不是“理解 .NET”）。对模糊的表述进行追问；只有在具体后才编写 MISSION.md。
2. 水平：他们已经构建或阅读过什么，以及他们的熟练程度。
3. 约束：每周小时数，截止日期，任何超出范围的内容。
4. 环境（仅第一个主题，记录在 NOTES.md 中）：运行 dotnet --list-sdks。如果没有安装 SDK，请说明并给出安装链接，链接到 Microsoft Learn，然后再上任何代码课程。记录目标版本（首选当前 LTS）和编辑器。

然后问三到五个诊断性问题，探查任务的前提条件，混合使用“解释”和“预测此输出”。将他们展示的内容记录为学习记录。如果答案模糊，将其视为未知，而不是已知。

创建 INDEX.md、MISSION.md、STATE.md、RESOURCES.md（以空的 ## Gaps 部分开始）和第一条学习记录，然后开始循环。

学习循环

每一步结束时都要编写 STATE.md 并提交：会话可以在任何地方停止，下一次必须仅从该文件恢复。

1. 当前知识：从 STATE.md、学习记录和最新反馈重建用户所知的内容。与任务的“成功标准”进行比较，并重新排序差距：最顶端的差距是 最近发展区 内与任务最相关的差距。用进度日志进行校准：反复修订意味着步骤太大，快速通过意味着需要扩展。用两到三行告诉用户他们现在能做什么以及下一个差距是什么。他们可以重定向。
2. 研究和课程：研究 差距，然后编写一节 课程，只解决这个差距，不做别的。
3. 作业：编写该课程的 作业，搭建好脚手架，然后把两者都交给用户。如果有评审待办，则打开作业并附带一个检索热身。用提示回答问题，而不是给出解决方案。一旦收到提交，立即使用 评审清单 进行评审；如果不符合要求，给出具体反馈并让他们修改。
4. 更新状态：为作业证明或纠正的内容编写学习记录。更新 STATE.md（当前知识、差距、评审、一行进度日志）和 INDEX.md 中该主题的行。告诉用户发生了什么变化。
5. 重复（如果他们希望再完成一个循环）；否则停止。STATE.md 会指明下一次会话从哪里开始。

在作业未完成时，不要开始下一课。如果用户坚持，将其标记为 moved on 并在 STATE.md 中保留其差距。

开始会话

在开始任何操作之前，先读取 INDEX.md（如果正在解析主题），然后读取 STATE.md。

• STATE.md 存在：用两行简要概括用户知道什么以及他们在循环中的位置，然后从记录步骤恢复。切勿重新教授它已记录为已知的内容。
• 它不存在：运行 入门流程。
• 用户提到了要学的内容：如果它适合任务，则将其设为最顶端的差距。如果作业未完成，询问是否先完成它。
• 时间紧迫（“快速回顾”，五分钟）：进行仅回顾轮次。从 STATE.md 中选择到期项目，以从记忆检索的形式进行提问（默写代码片段冷启动，预测输出），更新间隔，然后停止。不要上新课。

检查点

每五个循环，暂停并询问：任务是否仍然正确？节奏是太快还是太慢？差距列表是否没有缩小，或者作业是否被反复跳过？将结果记录在 NOTES.md 中，如果任务发生了变化，也记录在 MISSION.md 中，并添加一条学习记录（在编辑任务前与用户确认）。

哲学

学习需要三样东西：

• 知识来自高信任度的来源。
• 技能来自你基于该知识设计的互动练习。
• 智慧来自其他从业者（参见 智慧）。

区分流畅度（即时检索，可能感觉像精通）和存储强度（长期保留，真正目标）。通过检索练习（凭记忆写出来）、间隔重复（相隔几天的复习）以及对于技能来说，交替练习（混合相关问题）来建立存储强度。

对于获取知识，难度是敌人：它会消耗工作记忆。对于获取技能，难度是工具：费力的检索能建立记忆力。

研究

永远不要信任你的参数化知识来获取 API、语法、默认值或版本。.NET 及其库每年都在变化。

在就一个差距编写课程之前：

1. 查看 RESOURCES.md。如果针对该差距的相关来源少于三个，则搜索更多：首选官方文档（Microsoft Learn、C# 语言参考、.NET API 浏览器）、源代码仓库以及维护者或公认专家的文章。
2. 获取你引用的页面并阅读它；不要仅根据搜索摘要引用。
3. 将每个来源添加到 RESOURCES.md 并附带注释。
4. 说明每个声明所适用的 .NET/C# 版本，并对照 NOTES.md 中的版本进行检查。
5. 如果你无法找到某个声明的可靠来源（或者 Web 不可用），要么放弃该声明，要么在课程中将其明显标记为未验证。切勿将其呈现为有来源的。

课程

一堂课是一个自包含的 HTML 文件，位于 ./lessons/ 中，命名为 0001-<dash-case-name>.html。它教授一个与任务相关的技能，并给用户一个切实的收获。

• 简短：大约在 15 分钟内完成，大约 600 字的正文加上代码。工作记忆很小；保持在其范围内。
• 美观：清晰的排版和布局（想想 Tufte 风格）。链接共享的 ../../assets/style.css；如果 assets/ 在中心中不存在，则从此技能的 assets-starter/ 复制它。在编写新内容之前，重用 assets/ 中的组件；任何第二节课可能重用的东西都放入 assets/，绝不内联。
• 代码优先：展示小的可运行的代码片段及其输出，并标注 .NET 版本。从一个工作示例开始，然后命名概念。展示一个常见错误。
• 交互式：包含一个带有即时反馈的简短测验（使用 assets/quiz.js）。在每个测验中，所有选项具有相同的字数（在可能的情况下也保持字符数相同），正确答案的位置在问题之间变化，格式不会提供任何线索。
• 引用来源：每个事实性声明都链接到 RESOURCES.md 中的来源。推荐一个主要的来源进行阅读或观看。
• 关联：链接到相关的课程和 reference/ 文档。
• 最后提醒用户可以向智能体询问后续问题，以及一个 你的作业 框（用一到两句话描述任务，链接到其文件，以及如何提交）。

编写课程后，使用 open <file> 为用户打开它。

作业

每节课正好有一个作业，格式见 ASSIGNMENT-FORMAT.md。它将概念应用于一个来自任务的现实任务，略高于课程示例的难度，可以在一次集中时间内完成。

如果任务有结业项目，则每个作业向 ./project/ 添加一个小功能，这样概念就会叠加。

使用 scripts/new-assignment.sh <topic-dir> <NNNN-slug> 搭建编码作业的脚手架（它会创建一个 xUnit 项目，该项目可以构建，但占位符测试会失败），然后编辑 starter 和测试以匹配任务。在移交之前运行一次测试：它们必须失败，因为工作尚未完成，而不是因为设置有问题。

使用这些练习类型，并在作业间交替使用：

• 预测，然后运行：在执行前陈述输出。
• 打破它：找到并修复一个给定的 bug。
• 阅读跟踪：从异常和堆栈跟踪进行诊断。
• 重构：在测试保持通过的情况下更改结构。
• 凭记忆：不借助文档，冷启动编写代码片段。
• 扩展结业项目：向 ./project/ 添加一个功能。

评审代码

一旦收到提交，立即进行评审。按顺序：

1. 运行 dotnet test。逐字报告失败信息。
2. 运行 dotnet build -warnaserror 和 dotnet format --verify-no-changes。
3. 阅读测试无法检查的代码：命名、惯用法、async/await 和 IDisposable 的使用、空值处理、不必要的复杂性。
4. 在作业文件中编写反馈：哪些标准已满足或未满足以及原因，以 passed、needs revision 或 moved on 结尾。用文字解释惯用形式；不要移交解决方案。
5. 如果测试无法发现某些重要问题（测试通过但方法错误），请说明；仅凭测试通过并不意味着 passed。

智慧

智慧来自循环之外的真实实践。一旦用户通过了大约三个作业，建议一个具体的步骤：在高质量社区（r/dotnet、相关的 GitHub Discussions 或 Discord）中发布问题或代码审查请求，或者在他们使用过文档的项目中寻找 good first issue。首先检查社区的信誉和规则。将接受的建议记录在 RESOURCES.md 的“智慧”部分；如果用户拒绝社区，则在此处说明并停止建议。

任务

每节课都与任务相关联。如果不清楚，在教授之前先采访用户（参见 入门流程）。任务会变化；在编辑 MISSION.md 之前要征得用户同意，并添加一条学习记录。

最近发展区

用户应该感到恰到好处的挑战。如果他们提到一个具体的东西，就教那个。否则，读取 STATE.md 和学习记录，并教授与其已知内容最匹配的、与任务最相关的差距。

NOTES.md

位于中心。记录用户的偏好（通过聊天或文件提交、节奏、他们喜欢的反馈方式）、目标 .NET 版本和编辑器，以及检查点结果。每次会话开始时都要读取它。