# How Phase Numbers and Lesson Slugs Are Formatted in the ai-engineering-from-scratch Directory Structure > Learn how phase numbers and lesson slugs are formatted in the ai-engineering-from-scratch directory structure. Discover the two-digit zero-padded pattern with descriptive text for effective organization. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: internals - Published: 2026-07-30 --- **Phase numbers and lesson slugs follow a strict two-digit zero-padded pattern with hyphenated descriptive text, structured as `phases/-/-/` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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/-/ ``` The `` component always uses two-digit zero-padding ranging from `00` through `19`, while the `` 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/-/-/ ``` The `` increments within the specific phase starting at `01`, and the `` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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: ```python 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). ## Standard Lesson Contents Every lesson directory formatted with the `-` pattern contains a standardized layout including: - `docs/` – Documentation files (e.g., [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md)) - `code/` – Implementation files - `outputs/` – Generated artifacts - [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/01-math-foundations/11-singular-value-decomposition/docs/en.md). ## Summary - Phase directories use the format `phases/-/` with two-digit zero-padded numbers ranging from `00` to `19`. - Lesson directories extend this pattern as `phases/-/-/` with lesson numbers starting at `01` within each phase. - The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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/`.