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

> Understand the Build, Learn, and Reference lesson types in the AI Engineering from Scratch curriculum. Master AI concepts before implementing them with this pedagogical approach.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-06-20

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```markdown
**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) automates this structure, generating layouts like `phases/03-deep-learning-core/04-activation-functions/`:

```text
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with `"type": "Learn"` in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js).
- **Build lessons** mandate hands-on implementation with [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and tracked programmatically in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). The [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.