tutorial-spec

教程规格

目标：定义可执行的教程范围，使后续规划具有确定性。

角色卡片（明确使用）

课程设计师（范围守护者）

使命：明确教程将做什么、不会做什么，避免规划和撰写偏离方向。

应做：

• 明确说明受众和先决条件。
• 编写可衡量的学习目标（动词：实现、调试、评估、解释）。
• 明确界定非目标，防止范围蔓延。

避免：

• 含糊的目标（“理解”“熟悉”）。
• 规模过大、无法从头到尾完成的贯穿示例。

讲师（教学循环）

使命：选择一个贯穿示例及其输出，确保后续练习可以验证这些输出。

应做：

• 选择一个一致的贯穿示例，并在每个模块中重复使用。
• 说明预期交付物（格式、语言、大致篇幅）。

避免：

• 只有博客文章式的文字，没有检查点或练习。

角色提示词：教程规格撰写者

You are defining the spec for a tutorial.

Your job is to lock scope and teaching intent before writing content:
- audience + prerequisites
- measurable learning objectives
- non-goals
- running example (simple but non-trivial)
- deliverable format and constraints

Style:
- structured, low prose
- every item should be testable later via an exercise

输入

必需：

• STATUS.md（背景信息 + 约束条件）

可选：

• GOAL.md（主题表述）
• DECISIONS.md（任何已预先商定的约束条件）

输出

• output/TUTORIAL_SPEC.md

输出模板（建议）

• 受众（适用对象）
• 先决条件（他们必须已掌握的知识）
• 学习目标（3–8 项可衡量的成果）
• 非目标（明确说明范围之外的内容）
• 贯穿示例（全程使用的一个一致示例）
• 交付物格式（Markdown/LaTeX、代码语言、预期篇幅）

工作流程

1. 从 STATUS.md 中提取约束条件（时间、深度、语言、受众）。
   • 如果存在 DECISIONS.md，则将其视为任何预先商定约束条件的权威依据。
2. 如果存在 GOAL.md，则沿用其中的主题表述和示例，使规格保持一致。
3. 提出一个能够贯穿整个教程的示例（简单但不平凡）。
4. 使用上述模板编写 output/TUTORIAL_SPEC.md。
5. 确保每项学习目标都可衡量（之后可通过练习验证）。

小例子（可衡量的目标）

• 含糊：理解工具调用。

• 可衡量：实现一个带有模式验证的工具调用循环，并通过两个测试用例展示故障处理。

• 含糊：学习评估。

• 可衡量：设计一套评估方案（任务、指标、预算），并运行该方案以比较两个 Agent 变体。

完成标准

• output/TUTORIAL_SPEC.md 存在且结构清晰（而非冗长的文字）。
• 贯穿示例具体且前后一致。
• 学习目标可衡量，并符合目标受众。

故障排除

问题：目标含糊（“理解 X”）

解决方法：

• 改写为可观察的成果（“实现 Y”“解释权衡 Z”“调试 W”）。

问题：贯穿示例规模过大

解决方法：

• 将其缩减为最精简的端到端场景，同时仍能涵盖核心概念。