# How the AI Engineering from Scratch Curriculum Structures Its Lessons: A Complete Guide

> Discover how the AI Engineering from Scratch curriculum structures lessons. Learn about phases, documentation, implementations, tests, quizzes, and CI pipelines for effective AI engineering education.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: architecture
- Published: 2026-08-26

---

**The AI Engineering from Scratch curriculum organizes content into sequentially numbered phases containing self-contained lessons, each with mandatory documentation, reference implementations, unit tests, and quizzes, enforced by automated CI pipelines.**

The `rohitg00/ai-engineering-from-scratch` repository structures its educational content through a rigid, modular architecture defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). This design ensures every lesson in the AI Engineering from Scratch curriculum functions as a reproducible, self-contained learning unit with standardized components and strict quality controls.

## Repository-Wide Layout and Conventions

The curriculum follows a strict hierarchical structure centered on phases and lessons. According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) source file, the repository enforces specific organizational rules that guarantee consistency across all learning materials.

### Directory Hierarchy

All content lives under the `phases/` directory, following a predictable pattern:

```text
phases/
  NN-phase-slug/
    NN-lesson-slug/
      docs/
        en.md                # lesson description & objectives

      code/
        main.<lang>          # reference implementation

        tests/
          test_main.*        # unit tests

      outputs/               # optional reusable artifacts

      quiz.json              # 6-question assessment

```

Each phase uses sequential numbering (for example, `01-foundations`, `19-capstone-projects`), with lessons numbered within their parent phase (such as `01-linear-algebra`, `02-gradient-descent`). The [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md) file provides shared terminology across all lessons.

### Version Control Standards

The AI Engineering from Scratch curriculum enforces strict git hygiene through two policies:

- **One commit per lesson**: Every lesson addition or modification is isolated to a single atomic commit
- **Conventional commit messages**: Follow the format `feat(phase-05/03): add attention-mechanism`

Additionally, every fenced code block must include a language tag, and the [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) schema requires exactly six questions.

## The Lesson Contract

Every lesson directory must contain five mandatory components validated by CI jobs in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml). The [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) script enforces this contract before any pull request can merge.

### Documentation Standards

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must include front-matter specifying:

- Title and hook
- Lesson type and supported languages
- Prerequisites and estimated completion time
- Specific learning objectives

### Reference Implementation

The `code/main.<lang>` file contains a minimal working implementation (typically 4-6 lines) preceded by a header comment citing the lesson's documentation path and any external specifications.

### Testing Requirements

The `code/tests/` directory must contain **at least five deterministic unit tests** runnable via standard language commands. For Python lessons, use `python3 -m unittest discover`; for TypeScript, use `npx tsx --test`.

### Assessment Structure

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file follows a fixed schema requiring exactly six questions categorized as pre-assessment, check-in, or post-assessment.

### Optional Artifacts

Lessons may include an `outputs/` directory containing reusable artifacts such as skill markdown files, prompts, or agent definitions.

## Curriculum Flow and Tracking

The curriculum progression is managed through specific governance files that track completion status and generate public documentation.

### Status Tracking with ROADMAP.md

The [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) file maintains a phase/lesson status matrix using symbols like `✅` for complete and `🚧` for work-in-progress, providing at-a-glance visibility into curriculum development status.

### Automated Website Generation

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generator parses markdown links in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) to construct the public lesson catalog. Missing links trigger build failures, ensuring every lesson remains discoverable and properly indexed.

## Dependency and Philosophy Constraints

The curriculum maintains a strict dependency policy aligned with its "build-it-use-it" philosophy. Only a curated allowlist of third-party packages (such as `numpy` and `torch` for Python) is permitted. All other functionality must be implemented from scratch, reinforcing fundamental understanding of AI engineering principles.

## Example Lesson Structure

Below is the concrete directory structure for a matrix multiplication lesson in phase 3:

```text
phases/03-math-basics/01-matrix-multiplication/
├─ docs/
│  └─ en.md               # front-matter + description

├─ code/
│  ├─ main.py             # 4-6 line implementation

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

├─ outputs/
│  └─ skill-matrix-mul.md # optional reusable skill

└─ quiz.json              # 6-question quiz

```

The reference implementation in [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) includes a mandatory header comment:

```python

# Lesson: Matrix Multiplication (phases/03-math-basics/01-matrix-multiplication/docs/en.md)

```

Tests execute via standard runners:

```bash
python3 -m unittest discover -s code/tests -v

```

## Summary

- The AI Engineering from Scratch curriculum organizes content into sequentially numbered phases containing self-contained lessons
- Each lesson follows a strict contract requiring [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/main.<lang>`, minimum five unit tests in `code/tests/`, and a six-question [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)
- The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file governs repository-wide conventions including directory structure, file naming, and commit message formats
- CI pipelines in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) validate all lessons via [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) before merge
- The [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) matrix tracks lesson status while [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) ensures public discoverability through [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) link validation

## Frequently Asked Questions

### What files are required in every lesson directory?

Every lesson must contain [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) for documentation, `code/main.<lang>` for the reference implementation, `code/tests/test_main.*` with at least five unit tests, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) with exactly six questions. An optional `outputs/` directory may contain additional artifacts like skill definitions or prompt templates.

### How does the curriculum enforce quality standards?

The repository uses automated CI jobs defined in [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) that run [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) to validate the lesson contract. Additionally, the [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generator fails builds if [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) links are missing, ensuring all lessons are properly cataloged and accessible.

### What is the dependency policy for implementations?

Only a curated allowlist including packages like `numpy` and `torch` is permitted. All other functionality must be built from scratch according to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specifications, reinforcing the curriculum's foundational learning approach and "build-it-use-it" philosophy.

### How are lessons numbered and organized?

Lessons reside within numbered phases (e.g., `01-foundations`) and are sequentially numbered within their phase (e.g., `01-linear-algebra`). The [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) file tracks completion status using emoji indicators for quick visual reference across the entire curriculum.