# How to Add a New Lesson to the AI Engineering from Scratch Curriculum

> Learn to add a new lesson to the AI Engineering from Scratch curriculum. Follow simple steps to create folders, write documentation, and register your lesson for contribution.

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

---

**Adding a new lesson to the AI Engineering from Scratch curriculum requires creating a standardized folder structure under `phases/`, writing [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) using the provided template, and registering the lesson in both [`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 opening a pull request.**

The `rohitg00/ai-engineering-from-scratch` repository organizes its hands-on curriculum into independent lesson directories that feed a static site generator. If you want to add a new lesson to the AI Engineering from Scratch curriculum, you must follow a strict three-step convention—folder scaffolding, documentation, and navigation registration—that is enforced by the CI pipeline. The entire workflow is defined in **[`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md)** and **[`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)** at the repository root.

## Create the Lesson Folder Structure

The repository uses a deterministic file system layout. Every lesson lives under `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/`, where `<NN>` is the phase number and `<MM>` is the lesson number.

Inside that path, you must create three sub-directories:

- **`code/`** — Runnable implementations in Python, TypeScript, Rust, or Julia.
- **`docs/`** — Narrative documentation; must contain **[`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md)**.
- **`outputs/`** — Optional artifacts such as prompts, skills, agents, or MCP servers.

The canonical layout is illustrated in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 7–21). Copy this scaffold directly and replace the placeholder slugs with your own.

## Write the Lesson Documentation

All curriculum content is authored in a single file: `<lesson-path>/docs/en.md`. This file must start with a standardized front-matter block that the site generator expects.

### Front-Matter Template

As shown in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 25–34), the header should follow this exact shape:

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

After the front matter, the document must follow the six-beat sequence documented in the template (lines 35–80):

1. **Problem** — Define what the learner will solve.
2. **Concept** — Explain the underlying theory.
3. **Build It** — Implement the solution step by step.
4. **Use It** — Demonstrate real-world usage.
5. **Ship It** — Package or deploy the artifact.
6. **Exercises** — Provide practice challenges.

Stick to this structure so the generated site renders the lesson consistently with the rest of the curriculum.

## Register the Lesson in the AI Engineering from Scratch Curriculum

Visibility depends on two top-level markdown files. The **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** script parses both to produce **[`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)**, so manual updates are mandatory.

### Update README.md

Add a new row to the appropriate phase table in **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)**. Maintain the existing column order:

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

```

This entry creates the hyperlink used by the curriculum browser.

### Update ROADMAP.md

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

```markdown
⬚ 23  My New Lesson

```

According to the contribution guide, keeping [`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 sync triggers the CI `readme-counts-sync` job correctly.

## Validate Locally with the Site Generator

Before committing, run [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to verify that the site data regenerates cleanly. After execution, `git diff site/data.js` should show **only a timestamp change** (see [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) line 22). If additional lines appear, your folder path or table row is malformed.

You can run the generator with Node:

```bash
node site/build.js

```

And check the diff:

```bash
git diff site/data.js

```

## Submit Your Lesson Changes

The repository enforces a strict pull-request workflow. Follow these steps exactly:

1. Fork the repository and create a feature branch (e.g., `add-lesson-phase3-23-my-new-lesson`).
2. Commit **one** change per lesson folder. Multiple lessons require separate commits.
3. Run unit tests inside the lesson's `code/` directory:

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

```

4. Use a conventional commit title such as `feat(phase-03/23): add my-new-lesson`.
5. Open a PR; the CI pipeline will automatically regenerate site data and enforce README/ROADMAP integrity.

## Complete Shell Workflow to Add a New Lesson

Below is a runnable sequence that scaffolds a lesson, writes documentation, updates navigation files, and prepares a commit. Replace the placeholder slugs with your actual lesson:

```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 a runnable 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. Append row to README.md phase table

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

# 6. Append entry to ROADMAP.md

# ⬚ 23  My New Lesson

# 7. Run lesson tests

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

# 8. 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

# 9. Open pull request

gh pr create --title "feat(phase-03/23): add my-new-lesson" \
    --body "Adds a new lesson to Phase 3 on building X from scratch."

```

## Summary

- **Folder layout:** Create `phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/` with `code/`, `docs/`, and `outputs/` subdirectories.
- **Documentation:** Write [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) using the front-matter and six-beat template from [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md).
- **Navigation:** Add a table row to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and a status line to [`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 lesson.
- **Validation:** Run the site generator locally and confirm only [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) timestamps change.
- **Contribution:** Submit one commit per lesson with a conventional commit title and passing unit tests.

## Frequently Asked Questions

### What files are required inside a new lesson folder?

At minimum, you need **[`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** inside a **`docs/`** directory, plus a **`code/`** directory for implementations. An **`outputs/`** directory is optional and used for prompts, skills, agents, or MCP servers. The exact skeleton is shown in [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) (lines 7–21).

### Where do I find the documentation template for a lesson?

The scaffold lives in **[`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)** at the repository root. It specifies the folder hierarchy, the front-matter block (lines 25–34), and the six-beat narrative structure (lines 35–80) that every lesson must follow.

### Why does my pull request fail CI after adding a lesson?

The most common cause is desynchronized navigation tables. The CI pipeline 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 regenerate the site. If either file is missing the new lesson entry, or if [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) contains unexpected diffs, the `readme-counts-sync` job will fail. Always run `node site/build.js` locally first.

### Can I submit multiple new lessons in a single commit?

No. The repository enforces a strict "one commit per lesson" policy. Each new lesson folder, along with its corresponding [`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) updates, should be committed separately with a conventional title such as `feat(phase-03/23): add my-new-lesson`.