How to Navigate Lessons in the AI-Engineering-from-Scratch Curriculum: 3 Methods Explained

You can navigate the AI-Engineering-from-Scratch curriculum using the web-based Contents table at aiengineeringfromscratch.com, by cloning the repository and browsing the hierarchical phases/ directory structure, or by running the scripts/lesson_run.py CLI helper to enumerate and validate lessons programmatically.

The rohitg00/ai-engineering-from-scratch repository organizes over 500 lessons into a structured curriculum covering AI engineering from fundamentals to advanced transformers. Whether you prefer browsing documentation online, exploring code locally, or automating navigation through command-line tools, understanding the repository layout is essential for efficient learning. This guide covers three distinct approaches to navigate lessons in the ai-engineering-from-scratch curriculum, each backed by the actual source code implementation.

Browse the Curriculum Online

The simplest way to navigate lessons is through the rendered website or the Contents section of the repository README.

Open the Contents table in the README:

[Contents](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md#contents)

Click on any phase (e.g., Phase 7 — Transformers Deep Dive) to expand its lesson list. Each lesson entry links directly to the lesson folder, such as:

[Self-Attention from Scratch](phases/07-transformers-deep-dive/02-self-attention-from-scratch/)

According to the source code, the README’s Contents section is generated automatically by the site/build.js script, ensuring it always reflects the current repository state.

Navigate Locally via the File System

For offline study or deep code inspection, clone the repository and explore the predictable directory hierarchy.

Clone the repository to your local machine:

git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch

List Available Phases

View all curriculum phases using standard directory listing:

ls phases/

Locate a Specific Lesson

Lessons follow a strict path pattern: phases/<phase-number>-<phase-slug>/<lesson-number>-<lesson-slug>/. To open a specific lesson documentation:

code phases/07-transformers-deep-dive/02-self-attention-from-scratch/docs/en.md

Standard Lesson Structure

Every lesson directory in the ai-engineering-from-scratch curriculum follows a reproducible layout:

phases/<NN>-<phase-name>/<MM>-<lesson-name>/
├── code/      # Runnable implementations (Python, TypeScript, Rust, Julia)

├── docs/
│   └── en.md  # Lesson narrative and explanations

└── outputs/   # Generated artifacts (prompts, skills, agents, MCP servers)

This structure ensures you can navigate directly to implementation files or documentation without searching through unrelated content.

Use the CLI Helper for Programmatic Navigation

The repository ships with scripts/lesson_run.py, a Python utility that provides command-line access to the curriculum hierarchy.

Run a Syntax Check Across All Lessons

Validate the entire curriculum without executing heavy dependencies:

python scripts/lesson_run.py

Example output:

lesson_run.py (syntax) — 503 lesson(s), 2140 python file(s): passed=503 failed=0 skipped=0

Filter Lessons by Phase

To navigate lessons within a specific phase only:

python scripts/lesson_run.py --phase 07

Execute Lesson Entry Scripts

For lessons without external dependencies, run the implementations directly:

python scripts/lesson_run.py --execute

Implementation detail: The script walks the phases/ tree using regular expressions (PHASE_DIR_RE and LESSON_DIR_RE) to match directory patterns, gathers .py files, and reports status programmatically.

Practical Code Examples

Find a Lesson Documentation Path Programmatically

Use this Python function to retrieve the absolute path to any lesson's en.md file:

from pathlib import Path

def get_lesson_doc(phase: int, lesson: int) -> Path:
    """Return the absolute path to the lesson's Markdown documentation."""
    root = Path(__file__).resolve().parent  # assuming script lives at repo root

    pattern = f"{phase:02d}-*/*{lesson:02d}-*/docs/en.md"
    matches = list((root / "phases").glob(pattern))
    if not matches:
        raise FileNotFoundError(f"No lesson found for phase {phase}, lesson {lesson}")
    return matches[0]

# Usage:

print(get_lesson_doc(7, 2))   # → phases/07-transformers-deep-dive/02-self-attention-from-scratch/docs/en.md

Identify Lessons with Skill Artifacts

This bash one-liner lists all lessons that generate reusable skill artifacts:

grep -rl "outputs/skill-" phases/*/*/outputs/ 2>/dev/null | \
  sed -E 's|/outputs/skill-.*||' | sort -u

The command walks the phases/ tree, locates outputs/skill-*.md files, and returns unique lesson directories containing these outputs.

Summary

• Web navigation: Use the Contents table in the README or visit aiengineeringfromscratch.com to browse lessons via clickable links.
• Local navigation: Clone the repository and follow the phases/<NN>-<name>/<MM>-<lesson>/ structure to locate docs/en.md, code/, and outputs/ directories.
• Programmatic navigation: Use scripts/lesson_run.py to enumerate lessons, validate syntax across the curriculum, or execute entry scripts for specific phases.
• Consistent structure: Every lesson follows the same directory layout, making it possible to construct paths predictably using the phase and lesson numbers.

Frequently Asked Questions

How is the README Contents table generated?

The Contents table is automatically generated by the site/build.js script, which walks the repository structure and updates the README to reflect the current phases and lessons. This ensures the navigation links remain synchronized with the actual directory layout as the curriculum evolves.

What files should I open first when exploring a lesson locally?

Start with docs/en.md for the narrative explanation, then examine the code/ directory for implementations in your preferred language (Python, TypeScript, Rust, or Julia). Check the outputs/ directory if the lesson produces artifacts like prompts, skills, or agents.

Can I run lesson code without installing dependencies?

Yes, for lessons that do not require external packages. Use python scripts/lesson_run.py --execute to run entry scripts, or use the --phase flag to limit execution to a specific phase. The script performs a syntax-only check by default, which validates code without running heavy ML dependencies.

Where are the transformer and self-attention lessons located?

The Transformers Deep Dive phase is located at phases/07-transformers-deep-dive/. Individual lessons like Self-Attention from Scratch follow the pattern phases/07-transformers-deep-dive/02-self-attention-from-scratch/, containing the documentation in docs/en.md and implementations in the code/ subdirectory.

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