# How to Add a New Lesson to the AI Engineering from Scratch Curriculum: A Step-by-Step Guide

> Learn how to add a new lesson to the AI Engineering from Scratch curriculum with this step-by-step guide. Follow our simple process to contribute to the open-source project.

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

---

**To add a new lesson to the AI Engineering from Scratch curriculum, create a folder with `code/`, `docs/`, and `outputs/` subdirectories under `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, write the documentation in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) following the standard template, and register the lesson in [`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) before submitting a pull request.**

The **AI Engineering from Scratch** repository by `rohitg00` organizes its curriculum as independent lesson folders under the `phases/` directory. Adding a new lesson requires coordinating three distinct tasks: scaffolding the folder structure, authoring standardized documentation, and updating the navigation tables that power the site generator. This process is governed by the guidelines in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) and the scaffolding template in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md).

## Step 1: Create the Lesson Folder Structure

Every lesson must reside in a path following the pattern `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where `NN` represents the phase number and `MM` represents the lesson number within that phase.

### Required Subdirectories

Inside your new lesson folder, create three mandatory subdirectories:

- **`code/`** – Stores runnable implementations in Python, TypeScript, Rust, or Julia.
- **`docs/`** – Contains the narrative documentation, specifically the required [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md) file.
- **`outputs/`** – Optional storage for prompts, skills, agents, or MCP servers produced by the lesson.

As defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 7–21), this structure ensures the lesson integrates cleanly with the build system and provides consistent organization for learners.

## Step 2: Write the Lesson Documentation

The lesson documentation lives in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and must adhere to strict formatting standards for the site generator ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) to parse it correctly.

### Front Matter Requirements

Begin the file with the standard front-matter block specified in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 25–34):

```markdown

# My New Lesson Title

> One‑line motto that captures the core idea.

**Type:** Build
**Languages:** Python, TypeScript
**Prerequisites:** [Previous lesson link]
**Time:** ~30 minutes

```

### The Six-Beat Narrative Structure

Following the front matter, the document must follow the six-beat structure outlined in the template (lines 35–80):

1. **Problem** – Define the challenge being solved.
2. **Concept** – Explain the theoretical foundation.
3. **Build It** – Implement the solution step-by-step.
4. **Use It** – Demonstrate practical application.
5. **Ship It** – Package and deploy the code.
6. **Exercises** – Provide hands-on practice tasks.

This standardized format ensures consistency across the curriculum and enables proper indexing by the documentation parser.

## Step 3: Register the Lesson in Navigation Tables

The curriculum UI is generated from markdown tables in the top-level [`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) files. You must manually update both files to make the new lesson discoverable.

### Update README.md

Add a row to the appropriate phase table in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md). For example, to add lesson 23 to Phase 3:

```markdown
| 23 | [My New Lesson](phases/03-deep-learning-core/23-my-new-lesson/) | Build | Python |

```

### Update ROADMAP.md

Add a matching entry to the corresponding phase section in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), using the status glyph `⬚` to indicate work-in-progress:

```markdown
  ⬚ 23  My New Lesson

```

According to the source code in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), these files are parsed to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), which serves as the site's source of truth. After editing, run the generator locally to verify that only a timestamp change appears in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) (as noted in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md), line 22).

## Step 4: Submit the Pull Request

The repository enforces specific contribution rules that must be followed exactly.

### Branch and Commit Conventions

1. **Fork** the repository and create a descriptive branch (e.g., `add-lesson-phase3-23-my-new-lesson`).
2. **Commit exactly once** per lesson folder—the repo enforces a "one commit per lesson" policy.
3. **Use conventional commit titles** following the format: `feat(phase-03/23): add my-new-lesson`.

### Testing and Validation

Before submitting, run the unit tests for your new code:

```bash
python -m unittest discover phases/03-deep-learning-core/23-my-new-lesson/code

```

The CI pipeline will automatically regenerate the site data and enforce [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)/[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) integrity. Ensure your changes pass these checks before opening the PR.

## Complete Workflow Example

Below is a minimal shell script demonstrating the full process:

```bash

# 1. Clone and branch

git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
git checkout -b add-lesson-phase3-23-my-new-lesson

# 2. Scaffold folders

mkdir -p phases/03-deep-learning-core/23-my-new-lesson/{code,docs,outputs}
cp LESSON_TEMPLATE.md phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

# 3. Edit documentation

$EDITOR phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

# 4. Add implementation

cat > phases/03-deep-learning-core/23-my-new-lesson/code/main.py <<'PY'
def demo():
    print("Hello from my new lesson")
if __name__ == "__main__":
    demo()
PY

# 5. Update README.md (add table row)

# 6. Update ROADMAP.md (add status line)

# 7. Test

python -m unittest discover phases/03-deep-learning-core/23-my-new-lesson/code

# 8. Commit (single commit per lesson rule)

git add phases/03-deep-learning-core/23-my-new-lesson README.md ROADMAP.md
git commit -m "feat(phase-03/23): add my-new-lesson"
git push origin add-lesson-phase3-23-my-new-lesson

```

## Summary

- **Create the folder structure** at `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` with `code/`, `docs/`, and `outputs/` subdirectories.
- **Write documentation** in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) using the front-matter template from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) and the six-beat narrative structure.
- **Register the lesson** by adding entries to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) (navigation table) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) (status tracking).
- **Submit one commit per lesson** with a conventional commit message like `feat(phase-03/23): add my-new-lesson`.
- **Validate locally** by running `python -m unittest discover` and checking that [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generates only timestamp changes in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js).

## Frequently Asked Questions

### What files are required to add a new lesson to the AI engineering curriculum?

You must create a folder containing three subdirectories (`code/`, `docs/`, and `outputs/`) and a documentation file at [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md). Additionally, you must update the top-level [`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) files to register the lesson in the navigation tables.

### Where does the documentation template for new lessons come from?

The scaffolding template is located in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) at the repository root. This file defines the required folder hierarchy, front-matter format (lines 25–34), and the six-beat narrative structure (lines 35–80) that all lessons must follow.

### Why does the repository require exactly one commit per lesson?

The CI pipeline and contribution workflow enforce a "one commit per lesson" policy to maintain a clean git history and ensure atomic changes. This rule is documented in [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) and helps reviewers isolate changes to specific curriculum additions.

### How does the site generator discover new lessons?

The site generator script [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) parses the markdown tables in [`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), along with [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md), to produce [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). This generated file serves as the source of truth for the curriculum website, making manual updates to both markdown files essential for lesson visibility.