AI Course & Tutorial Design Guide

1. Core Principles

• 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. Workflow (Execute in Strict Order)

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: Scan Project Directory

lesson*/

lesson*/

syllabus.md

knowledge-points.md

introduction.md

Step 1: Understand Course Information and Student Background

• 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: Organize Knowledge Point List

introduction.md

knowledge-points.md

• 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: Confirm Knowledge Points

Step 4: Generate Course Syllabus

syllabus.md

# Course Name

## Course Information
- Target Audience: ...
- Total Class Hours: X sessions

## Course Directory
### Session 1: [Title]
- Core Knowledge Points: ...
- Project Task: [One-sentence description of what to do]
- Learning Outcome: ... (Verifiable achievement)

Step 5: Confirm Syllabus

Step 6: Write Course Content

• 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

• 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

• 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: Comprehensive Self-Check and Code Validation

• 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

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

• 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: Generate README + Illustrations

README.md

• 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)

1. Whether illustrations are needed
2. 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.)

• 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. Lecture Writing Principles (Lectures)

• 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. Hands-On Project Design Principles (Projects)

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

## Project: [Project Name]

### What You Will Learn
Through this project, you will personally experience the application of [core concept] in real scenarios.

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

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

### Task Breakdown
#### Task 1: [Subtask Name]
**Objective:** [What to achieve in this step]
**Hint:** [Key ideas or API/functions to use]
**Scaffold Code:**
```python
# Provide initial code framework, mark parts that need students to fill in
def your_function():
    # TODO: Implement xxx here
    pass

Task 2: [Subtask Name]

Task 3: [Subtask Name]

Reference Implementation

# Complete reference implementation

Acceptance Criteria

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

Challenge Tasks (Optional)

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

### Design Key Points

- **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. Common Mistakes

| 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 |