ai-tutorials

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Course & Tutorial Design Guide

1. 核心理念

1. Core Principles

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

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

Produce high-quality AI courses consisting of two parts: lectures and hands-on projects.

Projects are the essence and core of the course. Students truly understand concepts by working on hands-on projects
Lectures serve as a foundation for projects, responsible for concisely introducing key concepts to remove cognitive barriers for the projects

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

2. Workflow (Execute in Strict Order)

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: Scan project directory               ──→  Detect current progress and determine where to start
Step 1: Read/Create introduction.md  ──→  Understand the audience
Step 2: Organize knowledge point list             ──→  Output knowledge-points.md
Step 3: User confirms knowledge points             ──→  ⛔ Do not generate the syllabus until confirmed
Step 4: Generate syllabus.md           ──→  Organize knowledge points into a course syllabus
Step 5: User confirms the syllabus               ──→  ⛔ Do not write specific content until confirmed
Step 6: Write lectures + projects section by section ──→  Produce course content
Step 7: Comprehensive self-check and code validation         ──→  Ensure correctness and quality
Step 8: Generate README + illustrations         ──→  Overall packaging of the course

Step 0: 扫描项目目录

Step 0: Scan Project Directory

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

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

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

优先级	已有文件 / 状态	跳转到
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

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

The first thing to do each time this guide is invoked is to scan the current working directory, judge the course progress based on existing files, and jump to the corresponding step directly.

⚠️ If the user explicitly specifies which step to start with, follow the user's instructions directly and skip automatic detection.

Automatic Detection Rules —— Match from bottom to top in the following order, take the highest progress:

Priority	Existing Files / Status	Jump to
5	All `lesson*/` are completed (consistent with the number of sections in the syllabus)	Step 7
4	Some `lesson*/` exist but are not fully completed	Step 6 (continue writing unfinished sections)
3	`syllabus.md` exists	Step 5
2	`knowledge-points.md` exists	Step 3
1	`introduction.md` exists	Step 2
0	The directory is empty with no course files	Step 1

After jumping, first briefly inform the user of the detected status and which step will be started, then begin execution.

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

Step 1: Understand Course Information and Student Background

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

Read or create
```
introduction.md
```
in the project root directory
It must include:
- Course Information: Course name, course objectives, total class hours, teaching format
- Student Profile: Technical background, learning objectives, available time, existing AI experience
If the user does not provide the above information, actively ask for it and write it into
```
introduction.md
```

Step 2: 梳理知识点清单

Step 2: Organize Knowledge Point List

根据

introduction.md

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

knowledge-points.md

。

要求：

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

Based on the course objectives, student background, and key knowledge points mentioned in

introduction.md

, comprehensively sort out all important knowledge points to be covered in this course, and output them to

knowledge-points.md

Requirements:

Comprehensive Coverage: Combine the course theme to systematically list all knowledge points that should be covered, without omitting key content
Categorized Organization: Group knowledge points by theme or module for subsequent arrangement into the syllabus
Priority Labeling: Distinguish between "compulsory/core" and "elective/advanced" knowledge points
No Arrangement Involved: Focus only on "what to teach" at this stage, not "how to arrange the courses"

Step 3: 确认知识点

Step 3: Confirm Knowledge Points

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

⛔ The knowledge point list must be confirmed by the user before entering the syllabus design stage. The user may add, delete, or adjust knowledge points.

Step 4: 生成课程大纲

Step 4: Generate Course Syllabus

将已确认的知识点组织编排为课程大纲，输出到

syllabus.md

。编排时需考虑：知识点的前后依赖关系、难度递进、每节课的信息量控制（2-3 个核心概念）。

大纲格式：

markdown

undefined

Organize the confirmed knowledge points into a course syllabus and output it to

syllabus.md

. When arranging, consider the dependencies between knowledge points, progressive difficulty, and control the information volume of each class (2-3 core concepts).

Syllabus Format:

markdown

undefined

课程名称

Course Name

课程信息

Course Information

目标受众：...
总课时：X 节

Target Audience: ...
Total Class Hours: X sessions

课程目录

Course Directory

第 1 节：[标题]

Session 1: [Title]

核心知识点：...
项目任务：[一句话描述做什么]
学完能做到：...（可验证的学习成果）

undefined

Core Knowledge Points: ...
Project Task: [One-sentence description of what to do]
Learning Outcome: ... (Verifiable achievement)

undefined

Step 5: 确认大纲

Step 5: Confirm Syllabus

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

⛔ Before starting to write any specific lectures and projects, the user must confirm the syllabus first.

Step 6: 编写课程内容

Step 6: Write Course Content

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

文件组织

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

执行节奏

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

断点续写

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

After confirmation, produce lectures and projects section by section according to the syllabus.

File Organization

One folder per session:
```
lesson{i}/
```
Separate lectures and projects into two files:
```
lecture.md
```
and
```
project.md
```
Note that a project may consist of multiple files, where
```
project.md
```
mainly describes the project content. If the project involves code, a new
```
src/
```
directory can be created under the course folder to save it; if other resources are involved, new directories can also be created to save files. It is not recommended to stuff everything into
```
project.md
```

Execution Rhythm

After finishing writing one session, pause to let the user confirm before proceeding to the next session
If the user explicitly requests batch generation, continuous output is allowed, but each session must remain independently reviewable

Resume from Breakpoint

If Step 0 detects that some
```
lesson*/
```
already exist, read
```
syllabus.md
```
to confirm the total number of sessions, and only continue writing the missing sessions

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

Step 7: Comprehensive Self-Check and Code Validation

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

正确性检查

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

文件结构示例：

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

可读性与质量检查

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

After all content is produced, conduct a systematic self-check, focusing on two dimensions:

Correctness Check

Verify concepts, terms, and API usage in each lecture section to ensure no factual errors
Write complete runnable code for each project personally and place it in the
```
answer/
```
folder of the corresponding session
If testing is required, write test code in the
```
test/
```
folder and run it actually to confirm that the output meets expectations
If errors are found, immediately go back to correct the corresponding content in the project document

Example File Structure:

lesson1/
├── lecture.md
├── project.md
├── answer/        ← Complete reference implementation, written and verified by yourself
│   └── main.py
└── test/          ← Test code (if needed)
    └── test_main.py

Readability and Quality Check

Lectures: Is the logic smooth? Are concepts explained clearly? Is it written for beginners?
Projects: Is the scaffolding complete? Are tasks split reasonably? Are acceptance criteria self-verifiable?
Overall: Is the difficulty progressive across sections? Is there coherence between previous and subsequent knowledge points?

Step 8: 生成 README + 配图

Step 8: Generate README + Illustrations

生成课程 README

在课程根目录生成

README.md

，内容包括：

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

询问用户是否生成配图

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

询问时需要确认两件事：

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

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

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

Generate Course README

Generate

README.md

in the course root directory, which includes:

Course introduction and target audience
Course directory (title of each session + one-sentence project description)
Environment configuration instructions (unified dependency installation)
Learning suggestions (how to use this course)

Ask the User Whether to Generate Illustrations

⛔ Must ask the user first before deciding whether to generate illustrations.

Two things need to be confirmed when asking:

Whether illustrations are needed
If yes, what method to use for generation (e.g., code generation (matplotlib/PIL), call image generation API/MCP, generate prompts for users to generate by themselves, etc.)

After confirmation, generate one illustration for each session with the following requirements:

Text Part: Reflect the core theme and key knowledge points of the session
Image Part: Illustrate the actual effect or core scenario of the session's project
Uniform illustration style consistent with the overall tone of the course
Store in the corresponding
```
lesson{i}/
```
folder, named
```
cover.png
```

3. 讲义编写原则 (Lectures)

3. Lecture Writing Principles (Lectures)

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

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

The positioning of lectures is to lay the groundwork for projects, not an encyclopedia.

Concise and Restrained: Focus on 2-3 core concepts per session, stop once clearly explained, do not overstuff
Provide Signposts: Attach supplementary links for underlying principles and advanced content, do not expand in the lecture
Serve the Project: The explanation of each concept should point to "you will use this in the project immediately"

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

4. Hands-On Project Design Principles (Projects)

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

Projects are where students truly learn, and they need careful design.

基本原则

Basic Principles

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

Hands-on Task for Each Session: No theory without practice
Flexible Project Arrangement: One small project per session or a large project combined across multiple sessions is acceptable
Closely Linked to Knowledge Points: Projects must directly apply the core concepts in the lecture of this session

项目模板

Project Template

markdown

undefined

markdown

undefined

项目：[项目名称]

Project: [Project Name]

你将学到什么

What You Will Learn

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

Through this project, you will personally experience the application of [core concept] in real scenarios.

环境准备

Environment Preparation

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

Runtime Environment: ...
Install Dependencies:
```
pip install ...
```
Required API Key / Account: ...

背景介绍

Background Introduction

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

[Describe the project scenario and why this project is needed in 2-3 sentences to help students understand the context]

任务分解

Task Breakdown

Task 1：[子任务名称]

Task 1: [Subtask Name]

目标： [这一步要实现什么] 提示： [关键思路或需要用到的 API/函数] 脚手架代码：

python

undefined

Objective: [What to achieve in this step] Hint: [Key ideas or API/functions to use] Scaffold Code:

python

undefined

给出起始代码框架，标注需要学生填写的部分

Provide initial code framework, mark parts that need students to fill in

def your_function(): # TODO: 在这里实现 xxx pass

undefined

def your_function(): # TODO: Implement xxx here pass

undefined

Task 2：[子任务名称]

Task 2: [Subtask Name]

...

Task 3：[子任务名称]

Task 3: [Subtask Name]

...

参考实现

Reference Implementation

<details> <summary>点击查看参考代码（建议先自己尝试）</summary>

python

undefined

<details> <summary>Click to view reference code (try it on your own first)</summary>

python

undefined

完整的参考实现

Complete reference implementation

</details>

</details>

验收标准

Acceptance Criteria

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

[Self-verifiable completion standard 1]
[Self-verifiable completion standard 2]
[Self-verifiable completion standard 3]

挑战任务（选做）

Challenge Tasks (Optional)

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

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

undefined

Advanced challenges beyond the basic tasks for students who want to learn more:

Challenge 1: [Description]
Challenge 2: [Description]

undefined

设计要点

Design Key Points

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

Scaffold First: Provide initial code framework, let students fill in the core logic, do not start from an empty file
Break Down Tasks: Split large projects into 3-5 small tasks, guide step by step
Progressive Difficulty: Focus on "following along" in the first few sessions, gradually shift to "thinking, researching, and designing on your own" in later sessions
Collapsed Reference Implementation: Provide complete reference code but keep it collapsed by default to encourage students to try independently first
Self-verifiable Acceptance: Students can judge "did I do it right" without a teacher
Runnable Code: All code (scaffold and reference implementation) must be fully runnable, including dependency and environment instructions

5. 常见错误

5. Common Mistakes

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

Mistake	Correction
Skipping syllabus confirmation and directly writing content	First output syllabus.md and wait for user confirmation
Lectures overstuff concepts, covering too much in one chapter	Focus on 2-3 core concepts per session, stop when enough
Projects are disconnected from lectures	Projects must directly apply the core knowledge points of this session
Projects only provide final code without process guidance	Split into multiple tasks and guide step by step
Projects start from scratch without scaffolding	Provide initial code framework to lower the entry barrier
Incomplete code that cannot run	Include complete imports, dependency installation, and environment instructions
Skipping self-check and delivering directly	Step 7 must be executed, run through each project code personally
Missing README or not asking the user about illustrations	Generate README first, then explicitly ask whether illustrations are needed