# Folder Structure for Adding a New Lesson to AI Engineering From Scratch

> Learn the exact folder structure for adding new lessons to AI Engineering From Scratch. Discover the required code docs and outputs directories and file structure.

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

---

**To add a new lesson to ai-engineering-from-scratch, you must create a directory under `phases/<NN>-<phase-name>/<NN>-<lesson-slug>/` containing `code/`, `docs/`, and `outputs/` subdirectories, with at least one implementation file in `code/` and a front-matter-backed Markdown file in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md).**

The `rohitg00/ai-engineering-from-scratch` repository enforces a rigid curriculum architecture to ensure every lesson integrates seamlessly with the automated tooling and documentation pipeline. This standardized folder structure for adding a new lesson is documented in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) and validated through the repository's CI checks.

## Top-Level Phase Organization

All lessons reside within the `phases/` directory at the repository root. This folder groups content by curriculum phase using a strict naming convention: `<NN>-<phase-name>`, where `NN` represents a two-digit sequential prefix (e.g., `04-computer-vision`). The hyphenated name describes the phase domain and must remain consistent across all lessons within that phase.

## Lesson Directory Naming Convention

Inside a phase folder, each lesson lives in its own directory named `<NN>-<lesson-slug>`. The two-digit prefix must represent the next sequential number within that specific phase, while the slug briefly describes the lesson topic (e.g., `04-image-fundamentals`). This numbering ensures the curriculum maintains logical progression and allows build scripts to order content correctly.

## Required Subdirectories

Every lesson directory must contain three mandatory subdirectories and one optional folder. The structure is enforced by the template defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) and referenced in the README's "The shape of a lesson" section.

### The code/ Directory

The `code/` folder houses all runnable implementations. You must provide at least one primary implementation file named `main.<ext>`. The repository supports multilingual implementations:

- [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) for Python
- [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts) for TypeScript (optional)
- [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs) for Rust (optional)
- `main.jl` for Julia (optional)

Any additional language files must match the languages declared in the lesson's front-matter metadata.

### The docs/ Directory

The `docs/` folder must contain [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md), the canonical lesson document. This file requires strict front-matter schema compliance including fields for `title`, `type` (e.g., Learn or Build), `languages`, `prerequisites`, and `time`. The narrative content follows this front-matter block.

### The outputs/ Directory

The `outputs/` folder stores reusable artifacts that the lesson produces. This includes `prompt-*.md` files containing LLM prompts and `skill-*.md` files documenting acquired skills. These artifacts ship with the lesson for learner reference.

### The notebook/ Directory (Optional)

An optional `notebook/` subdirectory may contain `lesson.ipynb` for interactive Jupyter-based experimentation. While not required, this directory supports hands-on exploration when complex visualization or iterative development is beneficial.

## Automated Folder Creation

The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file's "New-lesson onboarding" section recommends automating scaffold creation to prevent structural errors. Use this Bash snippet to generate a compliant lesson skeleton:

```bash

# Configure these variables for your specific lesson

phase="04-computer-vision"
lesson_num="04"               # Next sequential number in the phase

lesson_slug="image-fundamentals"

lesson_dir="phases/${phase}/${lesson_num}-${lesson_slug}"
mkdir -p "${lesson_dir}/code" "${lesson_dir}/docs" "${lesson_dir}/outputs"

# Create a placeholder Python implementation

cat > "${lesson_dir}/code/main.py" <<'PY'
def run():
    print("Hello, AI Engineering!")
PY

# Create documentation with required front-matter

cat > "${lesson_dir}/docs/en.md" <<'MD'
---
title: "Image Fundamentals: Pixels, Channels, Color Spaces"
type: Learn
languages: [Python]
prerequisites: []
time: "~30 minutes"
---

Understanding the raw visual data that feeds all vision models.
MD

```

This script produces a directory structure that passes the repository's structural validation checks.

## Authoritative Source Files

Three files define and enforce the required scaffolding:

- **[`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)**: Provides the definitive folder-structure diagram and the exact Markdown template for [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter.
- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** (section *The shape of a lesson*): Visualizes the hierarchy within the full curriculum context and links each lesson from the main index.
- **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** (section *New-lesson onboarding*): Lists the exact post-creation steps, including updating the main README and ROADMAP files and running CI checks.

## Summary

- Lessons must reside under `phases/<NN>-<phase-name>/<NN>-<lesson-slug>/` using sequential two-digit numbering.
- The `code/` directory requires at least one `main.<ext>` implementation file, with Python being the primary supported language.
- Documentation must live in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and follow the strict front-matter schema defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md).
- Generated artifacts ship in `outputs/` as `prompt-*.md` or `skill-*.md` files.
- The structure is mandatory and validated against the templates in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) and [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md).

## Frequently Asked Questions

### What happens if I don't include the two-digit numeric prefix in the lesson folder name?

The curriculum build system and linking logic in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) depend on lexicographical ordering of these prefixes to sequence lessons correctly. Omitting the prefix or using non-sequential numbers will break the automated table of contents generation and cause CI validation failures.

### Can I create a lesson with only a TypeScript implementation and no Python code?

While the `code/` directory supports multiple languages, the curriculum requires at least one implementation file. However, the front-matter in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) must accurately reflect which languages are provided. If you list TypeScript in the front-matter but only provide [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts), ensure the build agents in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) are configured to handle language-specific validation for that lesson.

### Where does the lesson metadata come from if not from the folder name?

The canonical metadata (title, type, prerequisites, estimated time) is parsed from the YAML front-matter in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), not the directory name. The folder name provides only the URL slug and ordering information. The [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) specifies the exact front-matter keys required for curriculum ingestion.

### Is there a specific naming convention for files inside the outputs/ directory?

Yes. Prompt artifacts must follow the pattern `prompt-*.md` and skill documentation must follow `skill-*.md`. These naming conventions allow the repository's indexing scripts to automatically catalog reusable prompts and skills generated by each lesson, as described in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) onboarding guide.