Required Directory Structure for Adding a New Lesson in AI Engineering from Scratch

A new lesson in the AI Engineering from Scratch curriculum requires a specific four-folder layout (code/, notebook/, docs/, outputs/) under a NN-lesson-name/ directory to ensure compatibility with automated catalog generation and CI validation.

The rohitg00/ai-engineering-from-scratch repository enforces a strict directory structure for adding a new lesson to maintain consistency across the curriculum. This standardized layout allows automated tooling to discover lessons, validate their contents, and generate the public documentation site without manual intervention.

Canonical Lesson Directory Layout

According to the Lesson Template (LESSON_TEMPLATE.md) and contributor guide (AGENTS.md), every new lesson must reside in a top-level folder following the NN-lesson-name/ naming convention. Inside this directory, four mandatory subdirectories organize the lesson components.

The Four Required Subdirectories

• code/: Contains the primary implementation files. You must include main.py for the Python reference implementation. Optional polyglot versions include main.ts (TypeScript), main.rs (Rust), and main.jl (Julia).
• notebook/: Holds lesson.ipynb, an optional Jupyter notebook for interactive experimentation and visualization.
• docs/: Contains en.md, the lesson documentation written in Markdown with specific front-matter requirements.
• outputs/: Stores generated artifacts including prompt-*.md and skill-*.md files produced during lesson execution.

Creating a New Lesson from Scratch

To scaffold the required directory structure for adding a new lesson, use the following command pattern, replacing NN with the phase number and MM-new-lesson with your lesson slug:

mkdir -p phases/NN-phase-slug/MM-new-lesson/{docs,code,notebook,outputs}

After creation, populate the folders with the required files. The resulting tree should match this structure as implemented in rohitg00/ai-engineering-from-scratch:

phases/01-intro-to-ml/01-linear-regression/
├── code
│   ├── main.py
│   ├── main.ts
│   ├── main.rs
│   └── main.jl
├── notebook
│   └── lesson.ipynb
├── docs
│   └── en.md
└── outputs
    ├── prompt-example.md
    └── skill-example.md

Documentation Front-Matter Standards

The docs/en.md file must follow specific conventions defined in LESSON_TEMPLATE.md. Include structured headers that specify the lesson type, supported languages, prerequisites, and estimated duration:

# Linear Regression

> Learn to fit a line to data from first principles.

**Type:** Build  
**Languages:** Python, TypeScript  
**Prerequisites:** None  
**Time:** ~30 minutes

CI Validation and Automated Discovery

The repository's automated tooling scans the phases/ directory to build the curriculum catalog. Deviating from the required directory structure causes CI checks to fail, as the build system expects to find main.py in the code/ folder and en.md in the docs/ folder for every lesson. The AGENTS.md file specifies that contributors must also update README.md and ROADMAP.md when adding new lessons to keep the project documentation in sync.

Summary

• Strict four-folder layout: Every lesson requires code/, notebook/, docs/, and outputs/ directories.
• Polyglot support: While main.py is mandatory, TypeScript, Rust, and Julia implementations are optional additions in the code/ folder.
• Documentation requirements: The docs/en.md file must include standardized front-matter describing the lesson metadata.
• Automation compliance: Following the exact structure in LESSON_TEMPLATE.md ensures CI validation passes and the lesson appears correctly in the generated site.

Frequently Asked Questions

Where is the required directory structure officially defined?

The canonical layout is documented in LESSON_TEMPLATE.md at the repository root, with additional onboarding instructions in the AGENTS.md file under the "New-lesson onboarding" section. These files specify the exact folder hierarchy and file naming conventions required for automated processing.

Can I omit the notebook directory or polyglot implementation files?

Yes. The notebook/ directory and its lesson.ipynb file are optional for experimentation purposes. Similarly, while main.py is mandatory, the TypeScript (main.ts), Rust (main.rs), and Julia (main.jl) implementations are optional polyglot additions that enhance the lesson but are not required for CI validation.

What naming convention should I use for the lesson folder?

Use the format NN-lesson-name/ where NN is a two-digit number indicating the lesson sequence within its phase. Place this folder inside phases/NN-phase-slug/ to maintain the curriculum hierarchy. For example, phases/01-intro-to-ml/01-linear-regression/ follows the established convention.

How does the automated tooling detect new lessons?

The build system recursively scans the phases/ directory looking for folders containing the four required subdirectories (code/, docs/, notebook/, outputs/). It validates the presence of code/main.py and docs/en.md before including the lesson in the catalog generation and site build process.

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