Directory Structure for Phases and Lessons in AI Engineering from Scratch: A Complete Guide

The curriculum organizes content under a top-level phases/ directory using a hierarchical pattern of phases/<NN>-<phase-slug>/<LL>-<lesson-slug>/, where every lesson contains three standardized sub-folders: code/, docs/, and outputs/.

The open-source educational repository AI Engineering from Scratch by rohitg00 implements a deterministic directory structure for phases and lessons that separates learning materials into modular, reproducible units. This architecture, defined in the repository root README.md and enforced across all phase READMEs, allows learners to locate runnable implementations, narrative explanations, and generated artifacts through predictable file paths.

Top-Level Phase Organization

The repository root contains a single phases/ folder that houses the entire curriculum. Each phase follows a strict naming convention:

phases/<NN>-<phase-slug>/

Here, <NN> represents a two-digit zero-padded index (e.g., 00, 01, 02) and <phase-slug> describes the thematic focus in kebab-case.

According to the source code, valid phase directories include:

• phases/00-setup-and-tooling/ – Environment configuration and tooling
• phases/01-math-foundations/ – Mathematical prerequisites

These paths are documented in the phase-level README files located at phases/00-setup-and-tooling/README.md and phases/01-math-foundations/README.md, which enumerate their respective lessons and hyperlink to each lesson folder.

Lesson Directory Naming Convention

Inside each phase directory, individual lessons reside in sequentially numbered folders that mirror the phase naming pattern:

phases/<NN>-<phase-slug>/<LL>-<lesson-slug>/

The <LL> placeholder indicates a two-digit lesson index (e.g., 01, 02), while <lesson-slug> provides a descriptive, human-readable name. Concrete examples from the repository include:

• phases/00-setup-and-tooling/01-dev-environment/ – The first lesson of Phase 0
• phases/01-math-foundations/01-linear-algebra-intuition/ – The first lesson of Phase 1

As specified in the root README.md under "The shape of a lesson" section, this convention ensures lessons sort chronologically by filesystem default while maintaining descriptive identifiers.

The Three-Pillar Lesson Structure

Every lesson folder enforces a consistent three-part layout that separates concerns across implementation, documentation, and artifacts:

• code/ – Located at phases/.../<lesson>/code/, this folder contains runnable implementations in Python, TypeScript, Rust, or Julia.
• docs/ – Found at phases/.../<lesson>/docs/, typically containing en.md with the lesson narrative and theoretical explanations.
• outputs/ – Stored at phases/.../<lesson>/outputs/, this directory holds generated artifacts such as AI prompts, reusable skills, autonomous agents, or MCP (Model Context Protocol) servers.

The root README.md explicitly canonizes this structure as the standard lesson shape, ensuring contributors maintain consistency across the curriculum. For example, navigating to phases/01-math-foundations/01-linear-algebra-intuition/ reveals these three sub-directories, with implementations in code/, explanatory text in docs/en.md, and resulting AI artifacts in outputs/.

Practical Navigation Commands

To explore the directory structure for phases and lessons from the command line, use standard Unix utilities to inspect the hierarchy:

# List all phases in chronological order

ls phases/

# View lessons within a specific phase

ls phases/01-math-foundations/

# Display complete lesson tree including code, docs, and outputs

tree phases/01-math-foundations/01-linear-algebra-intuition/

These commands reveal the numeric sorting that the two-digit index enables, allowing 00 to appear before 01 and preserving lesson sequence across filesystem listings regardless of alphabetical slug names.

Summary

• The directory structure for phases and lessons in AI Engineering from Scratch roots at phases/ with two-digit indexed phase folders following the pattern <NN>-<phase-slug>/.
• Each phase contains lesson directories named <LL>-<lesson-slug>/, creating predictable paths like phases/01-math-foundations/01-linear-algebra-intuition/.
• Every lesson enforces a three-folder standard: code/ for implementations, docs/ for narrative content (specifically en.md), and outputs/ for AI artifacts such as prompts and agents.
• This architecture is documented in the root README.md "shape of a lesson" section and implemented consistently across phase READMEs such as phases/00-setup-and-tooling/README.md.

Frequently Asked Questions

What is the exact path pattern for lesson directories?

Lessons follow the nested pattern phases/<NN>-<phase-slug>/<LL>-<lesson-slug>/, where both <NN> and <LL> are two-digit zero-padded numbers. For instance, the first lesson of the setup phase resides at phases/00-setup-and-tooling/01-dev-environment/ according to the repository's source code.

What file contains the narrative explanation for each lesson?

Each lesson stores its primary documentation in docs/en.md relative to the lesson root. This file contains the narrative explanation and theoretical background corresponding to the runnable code in the sibling code/ directory.

What types of files belong in the outputs folder?

The outputs/ directory contains generated artifacts such as AI prompts, reusable skills, autonomous agents, or MCP servers produced during the lesson. This separation distinguishes transient build artifacts from immutable source code and documentation.

Where is the directory structure formally defined?

The canonical structure is defined in the root README.md of the rohitg00/ai-engineering-from-scratch repository under the section titled "The shape of a lesson". Additionally, each phase directory contains a README.md file (e.g., phases/01-math-foundations/README.md) that validates the lesson index and naming conventions for that specific phase.

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