Learn, Build, and Reference Lesson Types in the AI Engineering From Scratch Curriculum

The AI Engineering From Scratch curriculum categorizes every lesson into one of three types—Learn, Build, or Reference—each serving distinct pedagogical roles that govern whether the lesson contains conceptual explanations, executable code, or reusable data tables.

The rohitg00/ai-engineering-from-scratch repository organizes its self-contained lessons using a strict front-matter taxonomy that separates theoretical knowledge from practical implementation. Every lesson directory includes a docs/en.md file that declares its Type as either Learn, Build, or Reference, determining the content structure, validation rules, and presence of code directories. Understanding these lesson types is essential for navigating the curriculum and contributing new material that passes the automated audit_lessons.py CI checks.

The Three Pedagogical Lesson Types

Learn Lessons (Conceptual Foundation)

Learn lessons introduce theory, background, and concepts without requiring executable implementations. According to the lesson contract defined in AGENTS.md (lines 72-76), these lessons must not contain a code/ directory and instead focus on long-form narrative explanations and conceptual quizzes stored in quiz.json. The primary goal is knowledge acquisition through reading and assessment, preparing students for subsequent hands-on exercises.

For example, the dual-use risk lesson at phases/18-ethics-safety-alignment/30-dual-use-risk-cyber-bio-chem-nuclear/docs/en.md declares **Type:** Learn and contains only explanatory text and learning objectives, with no runnable code.

Build Lessons (Hands-On Implementation)

Build lessons transition from theory to practice by requiring students to write actual implementations. These lessons must include a code/ directory containing a main.<lang> entry point and a tests/ subdirectory with at least five unit tests. Generated artifacts such as skills, prompts, or MCP servers are stored in an outputs/ folder, making these lessons the construction pipeline of the curriculum.

The end-to-end safety gate capstone at phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md declares **Type:** Build and contains the full implementation alongside its documentation.

Reference Lessons (Canonical Data)

Reference lessons provide reusable, lookup-friendly material that other lessons can cite, such as tables of model specifications, hyper-parameter defaults, or architectural diagrams. These lessons require no code/ directory and often consist solely of Markdown documents or figures stored in site/assets/figures/. The site generator (site/build.js) parses these files to populate site/data.js, making them integral to the documentation infrastructure.

The DPO reference table at phases/10-llms-from-scratch/08-dpo/docs/en.md declares **Type:** Reference and provides a canonical table of frozen SFT checkpoints used for Direct Preference Optimization.

How Lesson Types Shape the Curriculum Architecture

The curriculum follows a structured learning pipeline: students begin with Learn lessons to establish theoretical foundations, progress to Build lessons to implement algorithms from scratch, and consult Reference lessons for authoritative data during both phases. This separation ensures that conceptual material remains free of implementation clutter while hands-on exercises contain rigorous test suites. The architecture enforces a clean distinction between understanding concepts and applying them, preventing the common anti-pattern of mixing lengthy theory with incomplete code snippets.

Validation and Enforcement

The strict categorization is enforced by the Lesson contract defined in AGENTS.md and validated by the audit_lessons.py CI script. Any deviation, such as a Learn lesson containing a code/ directory or a Build lesson lacking sufficient unit tests, triggers a validation failure. This automated enforcement ensures that the pedagogical intent declared in the front-matter matches the actual file structure, maintaining curriculum integrity across contributions.

Practical Examples of Front-Matter Definitions

The following excerpts demonstrate how each lesson type appears in the docs/en.md front-matter blocks:

Learn lesson front-matter:

# Dual‑Use Risk: Cyber‑Bio‑Chem‑Nuclear  

> Understanding the spectrum of dual‑use threats.  

**Type:** Learn  
**Languages:** None  
**Prerequisites:** None  
**Time:** ~15 min  

## Learning Objectives

- Define dual‑use risk categories.  
- Identify real‑world examples.  
- Explain mitigation strategies.  

Build lesson front-matter:

# End‑to‑End Safety Gate  

> Assemble a safety‑gate that blocks harmful completions.  

**Type:** Build  
**Languages:** Python  
**Prerequisites:** 86‑constitutional‑rules‑engine  
**Time:** ~45 min  

## Learning Objectives

- Implement a rule‑engine API.  
- Write unit tests for safety checks.  
- Deploy the gate as a reusable skill.  

Reference lesson front-matter:

# DPO Reference Model Table  

> Canonical frozen SFT checkpoints used for DPO.  

**Type:** Reference  
**Languages:** None  
**Prerequisites:** None  
**Time:** ~5 min  

| Model | Size | Reference Checkpoint |
|-------|------|----------------------|
| Llama‑3.2‑1B‑Instruct‑spec | 1 B | `meta‑llama/Llama‑3.2‑1B‑Instruct‑spec` |
| Qwen‑3‑0.6B‑spec | 0.6 B | `Qwen/Qwen3‑0.6B‑spec` |

Summary

• Learn lessons provide theoretical foundations through narrative explanations and quizzes, explicitly forbidding code directories.
• Build lessons require complete implementations with code/ directories, main.<lang> files, and minimum five unit tests in tests/.
• Reference lessons supply reusable data tables and figures for curriculum-wide citation, parsed by site/build.js for documentation generation.
• All types are enforced by the Lesson contract in AGENTS.md (lines 72-76) and validated by audit_lessons.py to maintain pedagogical consistency.

Frequently Asked Questions

Can a single lesson combine Learn and Build types?

No, the curriculum enforces strict separation. The audit_lessons.py validation script flags any lesson that mixes conceptual content with executable code directories, ensuring that Learn lessons remain theory-focused and Build lessons contain complete, testable implementations.

Where are Reference lesson assets stored?

Reference lesson figures and tables are typically stored in site/assets/figures/ and referenced within the Markdown using relative paths like ![FIG_NNN](../../site/assets/figures/...). The site generator (site/build.js) processes these links to populate site/data.js for global curriculum access.

What happens if a Build lesson lacks the required five unit tests?

The CI validation will fail. According to the lesson contract in AGENTS.md, Build lessons must contain a tests/ directory with at least five unit tests. This requirement ensures that every hands-on implementation includes sufficient coverage for verifying correctness.

How are Learn lessons assessed compared to Build lessons?

Learn lessons typically include a quiz.json file to assess conceptual understanding, whereas Build lessons validate learning through the execution of unit tests in the tests/ directory. This distinction ensures that theoretical knowledge is checked via quizzes while practical skills are verified through code compilation and test results.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}