How Phase Numbers and Lesson Slugs Are Formatted in the ai-engineering-from-scratch Directory Structure

Phase numbers and lesson slugs follow a strict two-digit zero-padded pattern with hyphenated descriptive text, structured as phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/ to ensure lexical sorting matches numeric ordering.

The rohitg00/ai-engineering-from-scratch repository organizes its curriculum content using a deterministic directory structure that enforces consistent formatting for phase numbers and lesson slugs. This convention, defined in the project's AGENTS.md file, ensures that all twenty phases and their respective lessons sort correctly in file explorers and automated build systems. Understanding this formatting is essential for contributors writing new lessons or integrating the content into external tooling.

Phase-Level Directory Formatting

Each phase resides in the top-level phases/ folder and follows the pattern:

phases/<PHASE_NUMBER>-<phase-slug>/

The <PHASE_NUMBER> component always uses two-digit zero-padding ranging from 00 through 19, while the <phase-slug> is a lowercase, hyphen-separated descriptor of the phase theme. For example, phases/01-math-foundations/ represents phase 1, where the zero-padding ensures that phase 11 (phases/11-advanced-topics/) sorts after phase 2 in lexical ordering.

Examples of Phase Directories

• phases/00-setup-and-tooling/ – Phase 0, covering initial environment configuration.
• phases/01-math-foundations/ – Phase 1, containing mathematical prerequisites.
• phases/19-capstone-project/ – Phase 19, the final project phase.

Lesson-Level Directory Formatting

Within each phase directory, individual lessons follow an identical two-digit pattern:

phases/<PHASE_NUMBER>-<phase-slug>/<LESSON_NUMBER>-<lesson-slug>/

The <LESSON_NUMBER> increments within the specific phase starting at 01, and the <lesson-slug> provides a concise, hyphenated description of the lesson content. For instance, phases/01-math-foundations/11-singular-value-decomposition/ locates lesson 11 of phase 1, which covers singular value decomposition, according to the repository source code.

AGENTS.md Specification

The definitive source for this formatting resides in AGENTS.md at the repository root. This file documents the Repo layout section, specifying that all directories must maintain the zero-padded, hyphenated structure. According to the rohitg00/ai-engineering-from-scratch source code, CI checks enforce this convention automatically, rejecting pull requests that deviate from the defined pattern.

Programmatic Path Generation

To reliably construct paths to lesson content, tooling must replicate the zero-padding logic. The following Python function demonstrates how to generate valid paths matching the directory structure:

from pathlib import Path

REPO_ROOT = Path("/path/to/ai-engineering-from-scratch")

def lesson_path(phase_num: int, phase_slug: str, lesson_num: int, lesson_slug: str) -> Path:
    """
    Build the absolute Path to a lesson directory given its identifiers.
    """
    phase_dir = f"{phase_num:02d}-{phase_slug}"
    lesson_dir = f"{lesson_num:02d}-{lesson_slug}"
    return REPO_ROOT / "phases" / phase_dir / lesson_dir

# Example: locate the SVD lesson (phase 1, lesson 11)

svd_path = lesson_path(1, "math-foundations", 11, "singular-value-decomposition")
print(svd_path)

# → /path/to/ai-engineering-from-scratch/phases/01-math-foundations/11-singular-value-decomposition

This helper uses Python's formatted string literals (:02d) to enforce the two-digit zero-padding requirement, ensuring compatibility with the repository's indexing system used in site/data.js.

Standard Lesson Contents

Every lesson directory formatted with the <NN>-<lesson-slug> pattern contains a standardized layout including:

• docs/ – Documentation files (e.g., en.md)
• code/ – Implementation files
• outputs/ – Generated artifacts
• quiz.json – Assessment data

For example, the singular value decomposition lesson at phases/01-math-foundations/11-singular-value-decomposition/ contains its documentation at phases/01-math-foundations/11-singular-value-decomposition/docs/en.md.

Summary

• Phase directories use the format phases/<NN>-<phase-slug>/ with two-digit zero-padded numbers ranging from 00 to 19.
• Lesson directories extend this pattern as phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/ with lesson numbers starting at 01 within each phase.
• The AGENTS.md file defines these conventions and CI enforces them automatically.
• Zero-padding guarantees that lexical sorting matches numeric ordering, which is critical for the site/data.js generation and content indexing.
• Use programmatic string formatting like f"{num:02d}" to ensure compliance when generating paths.

Frequently Asked Questions

Why are phase and lesson numbers zero-padded?

Zero-padding ensures that file systems and build tools sort the directories in numeric order rather than alphabetical order. Without zero-padding, phase 10 would sort before phase 2 because string comparison prioritizes the first character (1 vs 2). The two-digit format guarantees that 02 comes before 10 lexically.

Where is the directory structure format officially defined?

The official specification resides in the AGENTS.md file in the repository root, specifically within the Repo layout section. This document serves as the contract for contributors and is enforced by continuous integration checks that validate new lesson submissions.

How many phases are supported by this numbering scheme?

The two-digit zero-padded format supports phases 00 through 99 theoretically, though the repository currently implements phases 00 through 19. The ai-engineering-from-scratch source code indicates there are twenty phases total (0-19), leaving room for future expansion within the existing schema.

Can I manually create a lesson directory without the zero-padding?

Manual creation without zero-padding will cause CI checks to fail and break the automated indexing that generates site/data.js. Always use the two-digit format (01, 02, etc.) when creating new lesson folders, matching the pattern seen in existing paths like phases/01-math-foundations/11-singular-value-decomposition/.

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