How Lessons Are Organized in the AI Engineering from Scratch Curriculum

The AI Engineering from Scratch curriculum follows a phase-based hierarchy with 20 numbered phases, each containing atomic lessons that follow a strict six-step pedagogical pattern and ship reusable artifacts.

The rohitg00/ai-engineering-from-scratch repository treats educational content as a production codebase rather than a simple wiki. Understanding how lessons are organized in the AI Engineering from Scratch curriculum reveals an architecture designed for both progressive learning and standalone module consumption.

Phase-Based Directory Structure

The curriculum lives entirely under the phases/ directory, organized into 20 sequential phases numbered 00 through 19. Each phase represents a logical collection of related topics, from foundational tooling to production-grade agent engineering.

Every phase directory follows the naming convention phases/<NN>-<phase-name>/ and contains its own README.md that serves as the phase index. For example, phases/01-math-foundations/README.md contains a table listing every lesson in that phase with direct navigation links to the first lesson.

The Atomic Lesson Pattern

Six-Step Pedagogical Flow

Each lesson follows a rigid narrative structure designed to move from theory to shipped artifact:

1. MOTTO – A guiding principle or philosophy
2. PROBLEM – The specific challenge being solved
3. CONCEPT – Theoretical foundations and intuition
4. BUILD IT – Implementation details and code construction
5. USE IT – Practical application and testing
6. SHIP IT – Packaging the result as a reusable artifact

This pattern ensures every lesson in the AI Engineering from Scratch curriculum produces a tangible output, whether that is a debug skill, a prompt template, or a Model Context Protocol (MCP) server.

Folder Layout

Lessons are self-contained within their own directories using the path phases/<NN>-<phase-name>/<NN>-<lesson-slug>/. Each lesson folder contains three standardized subdirectories:

• docs/ – Contains en.md (and potentially localized versions) with the narrative content, theory, and front-matter metadata
• code/ – Runnable implementations in one or more supported languages (Python, TypeScript, Rust, Julia)
• outputs/ – The final artifact produced by the lesson, such as a reusable skill or agent configuration

This structure makes lessons atomic: learners can run code directly from the repository root using paths like python3 phases/01-math-foundations/01-linear-algebra-intuition/code/vectors.py without missing required context.

Lesson Metadata and Front-Matter Schema

Every lesson's docs/en.md begins with structured front-matter fields that specify metadata using a bold key-value format. The repository parses these fields to build curriculum tables automatically.

Standard metadata fields include:

• type – Categorizes the lesson as Learn (conceptual), Build (implementation), or Reference (lookup material)
• languages – Lists available programming languages for the lesson's code examples
• prerequisites – Specifies required prior knowledge or lesson dependencies
• time – Provides an estimated duration for completion

This schema allows the build system to generate filterable lesson tables and ensures learners understand the commitment and requirements before starting.

Navigation and Curriculum Flow

The root README.md serves as the master navigation hub. Around lines 14-20, it contains a "Start here" table linking directly to each phase and its inaugural lesson. Additionally, a collapsible "Contents" section expands to show lesson tables for every phase.

For visualizing dependencies, the README.md includes a Mermaid flowchart (located approximately at lines 78-100) illustrating how phases connect. The progression moves from foundational math (Phase 0 and Phase 1) up through deep learning core and finally to production-level agents (Phase 14 through Phase 19).

Programmatically Discovering Lessons

You can programmatically enumerate the curriculum structure to build custom study plans or documentation. The following Python script parses lesson metadata directly from the source files:

import os
import pathlib
import re
import json

def parse_frontmatter(md_path):
    """Extract front‑matter fields from a lesson's docs/en.md."""
    front = {}
    with open(md_path, encoding="utf‑8") as f:
        for line in f:
            if line.strip() == "---":       # end of front‑matter

                break
            m = re.match(r"\*\*(\w+)\*\*:\s*(.*)", line)
            if m:
                key, val = m.groups()
                front[key.lower()] = val.strip()
    return front

def list_lessons(phase_dir):
    lessons = []
    for lesson in sorted(pathlib.Path(phase_dir).iterdir()):
        if not lesson.is_dir():
            continue
        doc = lesson / "docs" / "en.md"
        if not doc.is_file():
            continue
        meta = parse_frontmatter(doc)
        lessons.append({
            "slug": lesson.name,
            "type": meta.get("type", "?"),
            "langs": meta.get("languages", "?"),
            "title": meta.get("title", lesson.name.replace("-", " ").title())
        })
    return lessons

# Example: list Phase 1 (Math Foundations)

phase_path = "phases/01-math-foundations"
for l in list_lessons(phase_path):
    print(f"{l['slug']}: {l['title']} – {l['type']} ({l['langs']})")

Running this script against a cloned repository outputs structured data matching the lesson tables rendered in the documentation:

01-linear-algebra-intuition: Linear Algebra Intuition – Learn (Python, Julia)
02-vectors-matrices-operations: Vectors, Matrices & Operations – Build (Python, Julia)
22-stochastic-processes: Stochastic Processes – Learn (Python)

Summary

• 20 sequential phases live under phases/, each with zero-padded numbering (e.g., 01-math-foundations, 14-agent-engineering)
• Atomic lesson folders contain docs/en.md for theory, code/ for polyglot implementations, and outputs/ for shipped artifacts
• Front-matter metadata in docs/en.md specifies lesson type (Learn/Build/Reference), supported languages, prerequisites, and estimated time
• Six-step flow ensures every lesson progresses from MOTTO to SHIP IT, producing reusable artifacts
• Master navigation resides in the root README.md, including a Mermaid flowchart (lines 78-100) showing phase dependencies

Frequently Asked Questions

What is the directory structure for a typical lesson in the AI Engineering from Scratch curriculum?

Each lesson resides at phases/<NN>-<phase-name>/<NN>-<lesson-slug>/ and contains three subdirectories: docs/ for narrative content and front-matter, code/ for runnable implementations in multiple languages, and outputs/ for the final shipped artifact such as a skill or agent configuration.

How does the curriculum track lesson prerequisites and estimated completion time?

Every lesson's docs/en.md file includes structured front-matter fields marked with bold key-value syntax, specifically type, languages, prerequisites, and time. The repository parses these fields to generate curriculum tables and filterable lesson indices.

Can learners jump between non-sequential phases, or must they follow the numbered order?

While the root README.md provides a Mermaid flowchart showing recommended dependencies between phases, the atomic design of individual lessons allows learners to enter at any point. Each lesson includes sufficient context within its docs/en.md to be understood independently, though the numbered sequence (00 through 19) represents the recommended pedagogical progression from math foundations to production agents.

Which programming languages are supported in the lesson code directories?

The curriculum supports polyglot implementations. Lesson metadata specifies available languages in the front-matter languages field, and the code/ directory within each lesson contains implementations in Python, TypeScript, Rust, and Julia, allowing learners to study concepts in their preferred language.

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