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

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, code/main.<lang>, code/tests/, 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 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 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, main.js, main.rs)
• tests/ – A subdirectory containing at least five unit tests for validating the lesson implementation

Assessment Files

The 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 – Validates that all lessons contain required files and conform to naming conventions
• 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 – Parses markdown links in README.md to generate site/data.js, requiring the [Title](phases/...) link format to locate content

Scaffolding New Lessons

The 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:

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

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

# 2. Edit the autogenerated markdown front-matter

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

# 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)]

# 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 following the exact pipe-table format:

| 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 (with front-matter), code/main.<lang> (reference implementation), code/tests/ (minimum five tests), and 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, scripts/check_readme_counts.py, and site/build.js all expect these exact paths.
• Use 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 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 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. naming convention?

The code/main.<lang> naming convention (such as main.py, main.rs, or 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, 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.

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