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

Adding a new lesson to the AI Engineering from Scratch curriculum requires creating a standardized folder structure under phases/, writing docs/en.md using the provided template, and registering the lesson in both README.md and 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 and 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.
• outputs/ — Optional artifacts such as prompts, skills, agents, or MCP servers.

The canonical layout is illustrated in 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 (lines 25–34), the header should follow this exact shape:

# 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 script parses both to produce site/data.js, so manual updates are mandatory.

Update README.md

Add a new row to the appropriate phase table in README.md. Maintain the existing column order:

| 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. Use the ⬚ glyph to mark work-in-progress status:

⬚ 23  My New Lesson

According to the contribution guide, keeping README.md and ROADMAP.md in sync triggers the CI readme-counts-sync job correctly.

Validate Locally with the Site Generator

Before committing, run 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 line 22). If additional lines appear, your folder path or table row is malformed.

You can run the generator with Node:

node site/build.js

And check the diff:

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:

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:

# 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 using the front-matter and six-beat template from LESSON_TEMPLATE.md.
• Navigation: Add a table row to README.md and a status line to ROADMAP.md so site/build.js can discover the lesson.
• Validation: Run the site generator locally and confirm only 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 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 (lines 7–21).

Where do I find the documentation template for a lesson?

The scaffold lives in 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 and ROADMAP.md to regenerate the site. If either file is missing the new lesson entry, or if 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 and ROADMAP.md updates, should be committed separately with a conventional title such as feat(phase-03/23): add my-new-lesson.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}