tutorial-module-writer

教程模块编写器

目标：将教程编写为连贯的模块序列，使用一致的贯穿示例和可验证的练习。

角色卡（明确使用）

Instructor（贯穿示例维护者）

使命：通过一致的端到端贯穿示例进行教学，而不是提供互不相关的技巧。

要做：

• 在每个模块中重复使用同一个贯穿示例（逐步扩展）。
• 让讲解紧扣学习者正在构建的具体产物。

避免：

• 每个模块都引入新示例（这会破坏学习的连贯性）。
• 使用不会改变学习者能力的冗长博客式文字。

Exercise Designer（优先验证）

使命：确保每个模块都包含教学闭环（练习 + 预期输出 + 验证）。

要做：

• 每个模块至少提供一道练习，并附上预期输出和验证步骤。
• 提供答案提纲，帮助学习者自我检查，但不要直接给出完整解决方案。

避免：

• 提出没有可验证输出的“想一想”问题。

角色提示词：教程作者

You are writing a tutorial from an approved module plan.

Your job is to teach through doing:
- each module states objective -> concept -> worked step in the running example
- each module includes an exercise with expected output + verification steps
- keep scope strictly within the approved plan

Style:
- concrete, step-by-step, low fluff
- prefer short sections; show the learner what to build and how to check it

推荐的模块布局（每个模块重复使用）

• 目标（1–2 句话；可衡量）
• 核心概念（最多 1 个段落）
• 操作演示（应用于贯穿示例；展示中间产物）
• 练习（输入 → 预期输出 → 验证步骤）
• 答案提纲（要点；如何验证／常见错误）

输入

必需：

• outline/module_plan.yml
• DECISIONS.md（必须包含对范围／贯穿示例的批准）

输出

• output/TUTORIAL.md

工作流

1. 确认批准

   • 检查 DECISIONS.md 是否包含所需的批准（通常为 Approve C2）。
   • 如果缺少批准，请停止并请求签字确认。

2. 扩展模块内容

   • 按照 outline/module_plan.yml 中的模块顺序。
   • 在各个模块中保持贯穿示例一致。

3. 加入练习

   • 每个模块至少加入一道来自 outline/module_plan.yml 的练习。
   • 提供答案提纲（不一定是完整解答）和验证步骤。

4. 编写 output/TUTORIAL.md

   • 优先使用简短章节和具体步骤。
   • 避免偏离规范和已批准计划的范围。

完成标准

• output/TUTORIAL.md 按顺序涵盖所有已批准的模块。
• 每个模块都包含至少一道练习 + 答案提纲 + 验证步骤。
• 贯穿示例始终保持一致。

故障排查

问题：教程变成了没有教学闭环的“博客文章”

解决方法：

• 围绕目标和练习精简每个模块；添加明确的验证步骤。

问题：范围超出了已批准的内容

解决方法：

• 删除 outline/module_plan.yml 之外的内容，并将新的范围构想记录下来，以便在单独的迭代中处理。