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

> Learn the required directory structure for adding new AI Engineering lessons. Follow the four-folder layout for automated catalog generation and CI validation.

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

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)) and contributor guide ([`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) for the Python reference implementation. Optional polyglot versions include [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts) (TypeScript), [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs) (Rust), and `main.jl` (Julia).
- **notebook/**: Holds `lesson.ipynb`, an optional Jupyter notebook for interactive experimentation and visualization.
- **docs/**: Contains [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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:

```text
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must follow specific conventions defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md). Include structured headers that specify the lesson type, supported languages, prerequisites, and estimated duration:

```markdown

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) in the `code/` folder and [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md) in the `docs/` folder for every lesson. The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file specifies that contributors must also update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) is mandatory, TypeScript, Rust, and Julia implementations are optional additions in the `code/` folder.
- **Documentation requirements**: The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must include standardized front-matter describing the lesson metadata.
- **Automation compliance**: Following the exact structure in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) at the repository root, with additional onboarding instructions in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) is mandatory, the TypeScript ([`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts)), Rust ([`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) and [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) before including the lesson in the catalog generation and site build process.