# Standard Directory Structure for Lessons in AI Engineering From Scratch: A Complete Guide

> Discover the standard directory structure for AI engineering lessons in the rohitg00/ai-engineering-from-scratch repo. Learn about the phases NN-phase-slug NN-lesson-slug hierarchy and essential lesson components.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-23

---

**The rohitg00/ai-engineering-from-scratch repository organizes its 503-lesson curriculum under a strict `phases/NN-phase-slug/NN-lesson-slug/` hierarchy, where every lesson contains mandatory [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/main.<lang>`, `code/tests/`, [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), and optional `outputs/` directories to enable automated tooling and site generation.**

The **AI Engineering From Scratch** repository implements a rigorous file organization system that governs how educational content is structured across the entire curriculum. This standardized approach ensures that automated pipelines, CI scripts, and the documentation site can reliably parse and publish lesson materials. Understanding this directory layout is essential for contributors who need to add new lessons while maintaining compatibility with the existing build system.

## Core Directory Hierarchy

The curriculum is organized as a set of **phases**, each containing a collection of **lessons**. Every lesson follows a strict layout defined in the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file under the "Repo layout" section.

### Top-Level Phase Organization

All content lives under the `phases/` directory. Each phase subdirectory uses a two-digit numeric prefix followed by a kebab-case slug:

```

phases/
  01-math-foundations/
  02-supervised-learning/
  03-neural-networks/

```

The `NN-phase-slug/` naming convention (where `NN` represents the two-digit phase number) allows the build system to sequence content correctly while maintaining human-readable directory names.

### Lesson-Level Structure

Inside each phase directory, individual lessons follow an identical pattern with two-digit prefixes:

```

phases/01-math-foundations/
  01-scalars-and-vectors/
  02-matrix-basics/
  03-linear-algebra-intuition/

```

This nesting creates predictable paths like `phases/01-math-foundations/03-linear-algebra-intuition/` that automated tools depend on for parsing.

## Mandatory Files and Subdirectories

Every lesson directory must contain four specific components to satisfy the **lesson contract** defined in the repository documentation.

### Documentation and Front-Matter

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file contains the human-readable lesson description and must include specific front-matter metadata as mandated by the lesson contract. This markdown file serves as the primary entry point for learners and the build system.

### Reference Implementation and Testing

The `code/` directory houses the lesson's source code with strict naming requirements:

- **`main.<lang>`** – The reference implementation file must match the language declared in the lesson's front-matter (e.g., [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.js), [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs))
- **`tests/`** – A subdirectory containing at least five unit tests for validating the lesson implementation

### Assessment Files

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file contains a fixed six-question schema (one pre-assessment, three check-in questions, and two post-assessment questions) encoded in JSON format.

### Optional Artifacts

The `outputs/` directory stores reusable artifacts such as skill markdown files, prompts, or compiled models that the lesson ships as supplementary materials.

## Automation and Tooling Integration

The rigid directory structure exists primarily to support automated maintenance and publishing workflows across the curriculum.

### CI Validation Scripts

The repository relies on several scripts that expect this exact hierarchy:

- **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** – Validates that all lessons contain required files and conform to naming conventions
- **[`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py)** – Ensures the README.md accurately reflects the number of lessons in each phase by scanning the `phases/` directory
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** – Parses markdown links in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), requiring the `[Title](phases/...)` link format to locate content

### Scaffolding New Lessons

The [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) script creates the complete directory hierarchy automatically. When contributors run this script, it generates the exact folder structure, ensuring consistency across the 503-lesson curriculum.

## Practical Example: Creating a New Lesson

Contributors follow a specific workflow that assumes the repository root as the current working directory. Below are the commands required to add a lesson following the standard structure:

```bash

# 1. Scaffold the lesson directories (creates docs, code, outputs, etc.)

scripts/scaffold-lesson.sh 01-math-foundations 03-linear-algebra-intuition

```

```bash

# 2. Edit the autogenerated markdown front-matter

code phases/01-math-foundations/03-linear-algebra-intuition/docs/en.md

```

```python

# 3. Implement the reference code

# File: phases/01-math-foundations/03-linear-algebra-intuition/code/main.py

def vector_addition(v1, v2):
    return [a + b for a, b in zip(v1, v2)]

```

```bash

# 4. Add unit tests (must be placed under the tests/ subdirectory)

python3 -m unittest discover phases/01-math-foundations/03-linear-algebra-intuition/code/tests -v

```

When updating documentation, contributors must also add a markdown link row to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) following the exact pipe-table format:

```markdown
| 03 | [Linear Algebra Intuition](phases/01-math-foundations/03-linear-algebra-intuition/) | Build | Python |

```

The repository enforces a **one-lesson-per-commit rule**, requiring that each new lesson be added in a single commit to maintain clean version history and predictable review cycles.

## Summary

- **The standard directory structure** follows the pattern `phases/NN-phase-slug/NN-lesson-slug/` with two-digit numeric prefixes for sequencing.
- **Every lesson must contain** [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) (with front-matter), `code/main.<lang>` (reference implementation), `code/tests/` (minimum five tests), and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) (six-question schema).
- **Optional `outputs/` directories** store supplementary artifacts like skills, prompts, or compiled models.
- **Automation depends on this structure** – [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py), and [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) all expect these exact paths.
- **Use [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh)** to generate compliant lesson skeletons automatically.

## Frequently Asked Questions

### What is the exact path format for lesson directories?

Lessons must be nested under `phases/NN-phase-slug/NN-lesson-slug/`, where `NN` represents a two-digit number (e.g., `01`, `02`) and the slug uses kebab-case. For example, a valid path would be `phases/01-math-foundations/03-linear-algebra-intuition/`. This format is required for the site generation tools to parse links correctly.

### How does the scaffold script create the standard directory structure?

The [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) script accepts two arguments: the phase slug and the lesson slug. It automatically creates the lesson directory, populates it with the required `docs/`, `code/`, and `outputs/` subdirectories, generates the initial [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with template front-matter, and creates the `code/tests/` directory. This ensures every new lesson starts with the exact structure that CI scripts expect.

### Why must code files follow the main.<lang> naming convention?

The `code/main.<lang>` naming convention (such as [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs), or [`main.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.js)) ensures that automated testing and validation scripts can locate the primary implementation without parsing configuration files. According to the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), this file must match the language declared in the lesson's front-matter, allowing the build system to identify which runtime to use for testing.

### Where should unit tests be placed within a lesson directory?

Unit tests must be placed inside the `code/tests/` subdirectory within the lesson folder, not in the root of the `code/` directory or alongside `main.<lang>`. The CI scripts specifically look for test files in this location, and the scaffold script automatically creates this directory structure to ensure compliance with the requirement of having at least five unit tests per lesson.