# 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 instructions to structure folders, author docs, and update navigation.

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

---

**To add a new lesson to the AI Engineering from Scratch curriculum, create a lesson folder under `phases/` containing `code/`, `docs/`, and `outputs/` subdirectories, author the documentation in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) using the standard front‑matter template, and register the lesson by appending entries to the navigation 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).**

The `rohitg00/ai-engineering-from-scratch` repository organizes its educational content into independent lesson folders that feed a static site generator. When you add a new lesson to the AI Engineering curriculum, you must coordinate folder structure, documentation formatting, and navigation registry to ensure the lesson appears correctly in the generated website and passes continuous integration validation.

## Scaffold the Lesson Folder Structure

Every lesson lives in a path following the pattern `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where `<NN>` and `<MM>` are sequential numbers. According to [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 7‑21), you must create three subdirectories:

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

For example, to add lesson 23 to Phase 3, you would execute:

```bash
mkdir -p phases/03-deep-learning-core/23-my-new-lesson/{code,docs,outputs}

```

## Author the Lesson Documentation

The lesson narrative resides in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and must begin with a standardized front‑matter block defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 25‑34). This metadata drives the site’s lesson cards and search indexing.

### Required Front‑Matter Format

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

```

### Six‑Beat Narrative Structure

Following the front‑matter, the document must implement the six‑beat structure outlined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 35‑80):

1. **Problem** – Define the real‑world challenge.
2. **Concept** – Explain the theoretical foundation.
3. **Build It** – Step‑by‑step implementation guide.
4. **Use It** – Demonstrate practical usage.
5. **Ship It** – Deployment or production considerations.
6. **Exercises** – Hands‑on tasks for the reader.

## Register the Lesson in Navigation Tables

The site generator ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) parses [`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) to construct the curriculum navigation (see [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md), lines 8‑11). You must update both files to make the lesson discoverable.

### Update README.md

Append a row to the appropriate phase table in **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** using the format:

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

```

### Update ROADMAP.md

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

```markdown
⬚ 23  My New Lesson

```

After editing these tables, run the site 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) (see [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md), line 22).

## Execute the Pull‑Request Workflow

The repository enforces a strict “one commit per lesson” policy. Follow these steps to submit your contribution:

1. **Fork and branch** – Create a descriptive branch (e.g., `add-lesson-phase3-23-my-new-lesson`).
2. **Implement** – Populate the `code/` directory with runnable examples and write the [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file.
3. **Test locally** – Run the unit tests within the lesson’s `code/` folder:
   ```bash
   python -m unittest discover phases/03-deep-learning-core/23-my-new-lesson/code
   ```

4. **Commit** – Stage the lesson folder, [`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) in a single commit using conventional commit format:
   ```bash
   git commit -m "feat(phase-03/23): add my-new-lesson"
   ```

5. **Open a PR** – Submit the pull request; the CI pipeline will automatically regenerate site data and enforce README/ROADMAP integrity.

## Complete Workflow Example

Below is a minimal shell script demonstrating the full addition 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 runnable code

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 navigation tables (edit README.md and ROADMAP.md manually)

# 6. Run tests

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

# 7. Commit and push

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** under `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` with mandatory `code/`, `docs/`, and `outputs/` subdirectories.
- **Write [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** following the front‑matter template and six‑beat narrative structure defined in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md).
- **Register the lesson** by appending rows to the phase 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) so [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) can discover the content.
- **Submit a single-commit PR** using conventional commit format after running local unit tests.

## Frequently Asked Questions

### What is the exact folder path format for a new lesson?

Lessons must reside in `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where numbers are typically zero‑padded (e.g., `phases/03-deep-learning-core/23-my-new-lesson/`). This hierarchy separates the curriculum into phases while keeping individual lessons modular and portable.

### How does the site generator discover newly added lessons?

The 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) at build time to construct the navigation and lesson registry. It also processes [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md) to generate cross‑references. If you omit these table entries, the lesson will not appear in the generated site even if the folder exists.

### Can I add multiple lessons in a single pull request?

No. The repository enforces a strict “one commit per lesson” policy. Each lesson must be a single, atomic commit that includes the lesson folder, the [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) update, and the [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) update. This keeps the history clean and simplifies rollback operations.

### Which programming languages are supported for lesson code examples?

The curriculum welcomes code implementations in **Python**, **TypeScript**, **Rust**, and **Julia**. You can specify the relevant languages in the front‑matter of [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) (e.g., `**Languages:** Python, Rust`), and the site generator will display the appropriate language badges in the lesson card.