AI Course & Tutorial Design Guide

1. 核心理念

产出高质量的 AI 课程，由讲义和项目实战两部分组成。

项目是课程的精华和核心。学生通过动手做项目来真正理解概念
讲义是项目的铺垫，负责精炼地介绍重点概念，为项目扫清认知障碍

2. 工作流程（严格按顺序执行）

Step 0: 扫描项目目录               ──→  检测当前进度，决定从哪里开始
Step 1: 读取/创建 introduction.md  ──→  了解受众
Step 2: 梳理知识点清单             ──→  输出 knowledge-points.md
Step 3: 用户确认知识点             ──→  ⛔ 未确认前不得生成大纲
Step 4: 生成 syllabus.md           ──→  将知识点组织为课程大纲
Step 5: 用户确认大纲               ──→  ⛔ 未确认前不得编写具体内容
Step 6: 逐节编写讲义 + 项目        ──→  产出课程内容
Step 7: 全面自查与代码验证         ──→  确保正确性与质量
Step 8: 生成 README + 配图         ──→  课程整体包装

Step 0: 扫描项目目录

每次被调用时，第一件事是扫描当前工作目录，根据已有文件判断课程进度，直接跳转到对应步骤。

⚠️ 如果用户显式指定了从哪一步开始，直接按用户指示执行，跳过自动检测。

自动检测规则——按以下顺序从下往上匹配，取最高进度：

优先级	已有文件 / 状态	跳转到
5	所有 `lesson*/` 均已完成（与大纲节数一致）	Step 7
4	有 `lesson*/` 但未全部完成	Step 6（继续编写未完成的课节）
3	有 `syllabus.md`	Step 5
2	有 `knowledge-points.md`	Step 3
1	有 `introduction.md`	Step 2
0	目录为空，无任何课程文件	Step 1

跳转后，先向用户简要说明检测到的状态和即将从哪一步继续，再开始执行。

Step 1: 了解课程信息与学生背景

读取或创建项目根目录下的 introduction.md
必须包含：
- 课程信息：课程名称、课程目标、总课时、授课形式
- 学生情况：技术背景、学习目标、可投入时间、已有 AI 经验
如果用户未提供，主动询问以上信息后写入 introduction.md

Step 2: 梳理知识点清单

根据 introduction.md 中的课程目标、学生背景以及其中提及的关键知识点，全面梳理本课程需要覆盖的所有重要知识点，输出到 knowledge-points.md。

要求：

全面覆盖：结合课程主题，系统性地列出所有应覆盖的知识点，不遗漏关键内容
分类组织：按主题或模块对知识点进行分组，便于后续编排到大纲中
标注优先级：区分「必修/核心」和「选修/进阶」知识点
不涉及编排：此阶段只关注"教什么"，不关注"怎么排课"

Step 3: 确认知识点

⛔ 知识点清单必须经用户确认后，才能进入大纲设计阶段。 用户可能会增删或调整知识点。

Step 4: 生成课程大纲

将已确认的知识点组织编排为课程大纲，输出到 syllabus.md。编排时需考虑：知识点的前后依赖关系、难度递进、每节课的信息量控制（2-3 个核心概念）。

大纲格式：

# 课程名称

## 课程信息
- 目标受众：...
- 总课时：X 节

## 课程目录
### 第 1 节：[标题]
- 核心知识点：...
- 项目任务：[一句话描述做什么]
- 学完能做到：...（可验证的学习成果）

Step 5: 确认大纲

⛔ 在开始编写任何具体讲义和项目之前，必须先让用户确认大纲。

Step 6: 编写课程内容

确认后，按大纲逐节产出讲义和项目。

文件组织

每节课一个文件夹：lesson{i}/
讲义和项目分开为两个文件：lecture.md 和 project.md
注意，项目可能是多个文件，其中project.md主要是项目内容描述。关于项目如果涉及到代码，可以在该课程下新建一个src/目录保存，如果涉及到其他也可以新建目录并保存文件。不鼓励什么都塞到project.md中

执行节奏

每次写完一节课后，暂停让用户确认，再继续下一节
如果用户明确要求批量生成，可连续产出，但每节仍需保持独立可审阅

断点续写

如果 Step 0 检测到部分 lesson*/ 已存在，读取 syllabus.md 确认总节数，只续写缺失的课节

Step 7: 全面自查与代码验证

所有内容产出完毕后，进行系统性自查，重点检查两个维度：

正确性检查

逐节核查讲义中的概念、术语、API 用法，确保无事实性错误
为每个项目亲自编写完整可运行代码，放入对应课节的 answer/ 文件夹
如需测试，在 test/ 文件夹中编写测试代码并实际运行，确认输出符合预期
发现错误立即回头修正项目文档中的对应内容

文件结构示例：

lesson1/
├── lecture.md
├── project.md
├── answer/        ← 完整参考实现，自己写并验证通过
│   └── main.py
└── test/          ← 测试代码（如有需要）
    └── test_main.py

可读性与质量检查

讲义：逻辑是否顺畅？概念是否解释清楚？是否为初学者写？
项目：脚手架是否完整？Task 拆分是否合理？验收标准是否可自检？
整体：各节难度是否递进？前后知识点是否衔接？

Step 8: 生成 README + 配图

生成课程 README

在课程根目录生成 README.md，内容包括：

课程简介与目标受众
课程目录（每节标题 + 一句话描述项目）
环境配置说明（统一的依赖安装）
学习建议（如何使用本课程）

询问用户是否生成配图

⛔ 必须先询问用户，再决定是否生成配图。

询问时需要确认两件事：

是否需要配图
如果需要，使用什么方式生成（例如：代码生成（matplotlib/PIL）、调用图片生成 API/MCP、生成 prompt 由用户自行生成等）

确认后，为每节课生成一张配图，要求：

文字部分：体现该节课的核心主题和关键知识点
图像部分：示意该节项目的实际效果或核心场景
配图风格统一，与课程整体调性一致
存放于对应 lesson{i}/ 文件夹下，命名为 cover.png

3. 讲义编写原则 (Lectures)

讲义的定位是为项目做铺垫，不是百科全书。

精炼克制：每节课聚焦 2-3 个核心概念，讲清楚就停，不堆砌
给出路标：底层原理和进阶内容附上补充链接，不在讲义中展开
服务项目：每个概念的讲解都应指向"你马上要在项目中用到这个"

4. 项目实战设计原则 (Projects)

项目是学生真正学会东西的地方，需要精心设计。

基本原则

每节必有动手任务：不能只有理论没有实践
项目安排灵活：可以一节一个小项目，也可以多节组合成一个大项目
紧扣知识点：项目必须直接运用本节讲义中的核心概念

项目模板

## 项目：[项目名称]

### 你将学到什么
通过这个项目，你将亲手体验 [核心概念] 在实际场景中的应用。

### 环境准备
- 运行环境：...
- 安装依赖：`pip install ...`
- 需要的 API Key / 账号：...

### 背景介绍
[用 2-3 句话描述项目场景和为什么要做这个项目，让学生理解上下文]

### 任务分解
#### Task 1：[子任务名称]
**目标：** [这一步要实现什么]
**提示：** [关键思路或需要用到的 API/函数]
**脚手架代码：**
```python
# 给出起始代码框架，标注需要学生填写的部分
def your_function():
    # TODO: 在这里实现 xxx
    pass

Task 2：[子任务名称]

...

Task 3：[子任务名称]

...

参考实现

# 完整的参考实现

验收标准

[可自行检验的完成标准 1]
[可自行检验的完成标准 2]
[可自行检验的完成标准 3]

挑战任务（选做）

基础任务之上的进阶挑战，供学有余力的同学尝试：

挑战 1：[描述]
挑战 2：[描述]


### 设计要点

- **脚手架先行**：给出起始代码框架，学生填核心逻辑，不要从空白文件开始
- **任务要拆细**：大项目拆成 3-5 个小 Task，每个 Task 有明确目标，逐步推进
- **渐进式难度**：前几节侧重"跟着做"，后期逐步转向"自己想、自己查、自己设计"
- **参考实现折叠**：提供完整参考代码但默认折叠，鼓励学生先独立尝试
- **验收可自检**：学生不需要老师就能判断"我做对了没有"
- **代码必须能跑**：所有代码（脚手架和参考实现）必须完整可运行，含依赖和环境说明

## 5. 常见错误

| 错误 | 修正 |
|------|------|
| 跳过大纲确认直接写内容 | 先输出 syllabus.md，等用户确认 |
| 讲义堆砌概念，一章讲太多 | 每节 2-3 个核心概念，够用就停 |
| 项目和讲义脱节 | 项目必须直接运用本节核心知识点 |
| 项目只给最终代码没有过程 | 拆成多个 Task，逐步引导 |
| 项目没有脚手架从零开始 | 提供起始代码框架，降低启动门槛 |
| 代码不完整无法运行 | 含完整 import、依赖安装和环境说明 |
| 跳过自查直接交付 | Step 7 必须执行，亲自跑通每个项目代码 |
| README 缺失或配图未询问用户 | 先生成 README，再明确询问是否需要配图 |

ai-tutorials