Difference Between Build, Learn, and Reference Lesson Types in AI Engineering from Scratch

The AI Engineering from Scratch curriculum categorizes every lesson into one of three types—Learn, Build, or Reference—to enforce a pedagogical flow where students master theoretical concepts before implementing them from scratch.

The rohitg00/ai-engineering-from-scratch repository organizes its 435 lessons around a strict Lesson contract defined in AGENTS.md. Understanding the difference between Build, Learn, and Reference lesson types is essential for navigating the curriculum's hands-on approach to AI engineering, as each type dictates specific content requirements, folder structures, and validation rules.

The Three Lesson Types Defined

Learn Lessons: Conceptual Foundation

Learn lessons focus exclusively on conceptual understanding. These entries contain explanatory text, mathematical derivations, diagrams, and intuition-building exercises that provide the why behind algorithms.

According to the Lesson contract in AGENTS.md, Learn lessons include code only for demonstration purposes—students run pre-written snippets but do not write implementation code. For example, phases/01-math-foundations/04-calculus-for-ml/docs/en.md contains theoretical explanations of gradients and partial derivatives with runnable demos, but no required coding assignments.

The frontmatter for a Learn lesson explicitly declares its type:

**Type:** Learn
**Languages:** Python

Build Lessons: Hands-On Implementation

Build lessons require students to implement core algorithms from scratch. These are the practical, construction-focused entries that form the backbone of the curriculum's "Build It" philosophy, providing the how.

Every Build lesson must contain a code/ directory with a main.<lang> implementation file and a code/tests/ folder containing at least five unit tests. The repository's scripts/scaffold-lesson.sh automates this structure, generating layouts like phases/03-deep-learning-core/04-activation-functions/:

phases/03-deep-learning-core/04-activation-functions/
├─ docs/
│  └─ en.md               # front-matter declares type "Build"

├─ code/
│  ├─ main.py             # implementation of ReLU, GELU, etc.

│  └─ tests/
│     └─ test_main.py     # ≥5 unit tests exercising the activations

└─ quiz.json               # 6-question quiz (pre-check-post)

The site/data.js file tracks these entries with "type": "Build", distinguishing them from theoretical modules.

Reference Lessons: Stable Specifications

Reference lessons serve as canonical API specifications that other lessons treat as stable dependencies. Unlike Build lessons, which are learning exercises, Reference lessons provide production-ready implementations that remain static across curriculum versions.

These entries contain minimal narrative and focus on function schemas, model wrappers, or tokenizer implementations that Build and Use lessons import. While the current curriculum has few Reference lessons, the type is reserved in site/data.js for entries marked "type": "Reference". When present, these lessons deliberately avoid experimental code or random seeds, ensuring reproducible behavior for dependent modules.

How Lesson Types Appear in Repository Files

The distinction between these categories manifests concretely in three key files:

• AGENTS.md – Defines the Lesson contract and the "Build It / Use It" philosophy, specifying that Learn lessons provide the why, Build lessons provide the how, and Reference lessons provide stable building blocks.

• site/data.js – Contains the machine-readable summary of all 435 lessons, with each entry including a "type" property set to "Learn", "Build", or "Reference".

• Lesson directories – The folder structure enforces type compliance. Build lessons require the code/ and tests/ subdirectories, while Learn lessons contain only docs/ and media files.

Pedagogical Philosophy: Build It, Use It

The curriculum's three-type system embodies the explicit "Build It / Use It" methodology. This progression ensures students understand mathematical foundations through Learn lessons, develop algorithmic intuition through Build lessons, and eventually rely on Reference lessons as stable abstractions for complex projects.

This structure prevents the anti-pattern of copying unexplained code. By forcing students to build components like backpropagation and optimizers from scratch before using library implementations, the curriculum ensures deep understanding of the engineering principles underlying modern AI systems.

Summary

• Learn lessons provide theoretical foundations with runnable demos but no required coding, stored in docs/en.md with "type": "Learn" in site/data.js.
• Build lessons mandate hands-on implementation with main.py files and at least five unit tests in code/tests/, marked as "type": "Build".
• Reference lessons act as stable API specifications for other lessons to import, reserved in the curriculum with "type": "Reference" for canonical implementations.
• The Lesson contract in AGENTS.md enforces these distinctions to maintain the "Build It / Use It" pedagogical flow across all repository phases.

Frequently Asked Questions

What is the primary difference between Build and Learn lesson types?

Learn lessons focus on conceptual understanding through text and diagrams, where students only run pre-written code. Build lessons require students to write algorithms from scratch, including a main.py file and at least five unit tests in a code/tests/ directory.

How are Reference lessons used in the curriculum?

Reference lessons serve as stable API specifications that other lessons can import directly. Unlike Build lessons, which are learning exercises, Reference lessons provide canonical implementations (like tokenizers or model wrappers) that remain static across curriculum versions for other modules to depend on without re-deriving them.

Where are lesson types defined and enforced?

Lesson types are defined in the Lesson contract within AGENTS.md and tracked programmatically in site/data.js. The scripts/scaffold-lesson.sh utility enforces structural requirements by automatically generating code/ and tests/ directories for Build lessons while omitting them for Learn lessons.

Why do Build lessons require at least five unit tests?

The requirement for ≥5 unit tests in code/tests/test_main.py ensures that Build lesson implementations are robust and correctly implement the target algorithm. This validation step prevents students from proceeding with buggy code and enforces the curriculum's emphasis on test-driven development when building AI components from scratch.

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