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

Add a new lesson by creating a numbered folder under phases/ with code/, docs/, and outputs/ subdirectories, writing a docs/en.md file following the standard template from LESSON_TEMPLATE.md, and registering the lesson in the README.md and ROADMAP.md navigation tables before submitting a single-commit pull request.

The AI Engineering from Scratch curriculum is organized as a collection of modular lessons within the rohitg00/ai-engineering-from-scratch repository. To add a new lesson to this curriculum, contributors must follow a strict folder naming convention, documentation format, and registration process that integrates with the automated site generator at site/build.js.

Prerequisites and Key Files

Before adding a new lesson, review the following authoritative resources in the repository:

• CONTRIBUTING.md: The primary contribution guide describing folder layout, commit conventions, and the pull request workflow.
• LESSON_TEMPLATE.md: The scaffold file containing the required folder hierarchy, documentation skeleton, and output formats (lines 7–21).
• README.md: Contains the phase-wise lesson tables that power the website navigation.
• ROADMAP.md: Tracks lesson status glyphs (✅, 🚧, ⬚) and drives the CI integrity checks.
• site/build.js: Parses the markdown tables to generate site/data.js, the website's source of truth.

Step-by-Step Implementation

Scaffold the Lesson Directory

Every lesson lives in a path following the pattern phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/. For example, lesson 23 in Phase 3 would reside at phases/03-deep-learning-core/23-my-new-lesson/.

Create the mandatory subdirectories:

• code/: Runnable implementations (Python, TypeScript, Rust, Julia).
• docs/: Narrative documentation containing the required en.md file.
• outputs/: Optional prompts, skills, agents, or MCP servers produced by the lesson.

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

Write the Documentation File

The docs/en.md file must begin with a standardized front-matter block as defined in LESSON_TEMPLATE.md (lines 25–34):

# My New Lesson Title

> One-line motto that captures the core idea.

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

Following the front matter, the document must follow the six-beat narrative structure: Problem → Concept → Build It → Use It → Ship It → Exercises (see the template lines 35–80). Copy the template to your lesson folder and replace the placeholder content:

cp LESSON_TEMPLATE.md phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

Update Navigation Tables

The curriculum UI discovers lessons through markdown tables in README.md and ROADMAP.md. You must update both files to register the new lesson:

1. Append a row to the appropriate phase table in README.md:

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

2. Add a matching entry to the phase’s section in ROADMAP.md, preserving the status glyph (⬚ for work-in-progress):

⬚ 23  My New Lesson

Both files are parsed by site/build.js (described in CONTRIBUTING.md lines 8–11). After editing, run the generator locally to verify that only a timestamp change appears in site/data.js.

Commit and Submit

The repository enforces a strict one commit per lesson policy. Use a conventional commit title following the format feat(phase-<NN>/<MM>): add <lesson-slug>:

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"

The CI pipeline will automatically regenerate the site data and enforce README.md/ROADMAP.md integrity. Ensure you have run unit tests for your code before pushing:

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

Complete Working Example

Below is a minimal shell script demonstrating the full workflow to add a lesson to Phase 3:

# 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️⃣ Create 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

# 4️⃣ Edit docs/en.md with your $EDITOR (follow the six-beat structure)

# 5️⃣ Update README.md table (add row under Phase 3)

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

# 6️⃣ Update ROADMAP.md (add under Phase 3 section)

# ⬚ 23  My New Lesson

# 7️⃣ Test and commit

python -m unittest discover phases/03-deep-learning-core/23-my-new-lesson/code
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

# 8️⃣ Open PR (using GitHub CLI)

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

• Lesson location: Create folders at phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/ with code/, docs/, and outputs/ subdirectories.
• Documentation: Write docs/en.md using the front-matter template from LESSON_TEMPLATE.md and the six-beat structure.
• Registration: Add rows to both README.md and ROADMAP.md for the site generator at site/build.js to discover the lesson.
• Submission: Commit exactly one change per lesson using conventional commit format feat(phase-XX/YY): add lesson-name.

Frequently Asked Questions

What is the required folder naming convention for new lessons?

Lessons must follow the path phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/, where <NN> is the two-digit phase number and <MM> is the two-digit lesson number. For example, phases/03-deep-learning-core/23-my-new-lesson/ places lesson 23 in Phase 3.

How do I register a new lesson so it appears on the website?

You must manually update two files: add a row to the phase table in README.md and add an entry with a status glyph (⬚, 🚧, or ✅) to ROADMAP.md. The site/build.js script parses these tables to generate the navigation data.

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 with a conventional title like feat(phase-03/23): add my-new-lesson.

What content structure must the docs/en.md file follow?

The documentation must start with the standard front-matter block (Title, Type, Languages, Prerequisites, Time) followed by a six-beat narrative: Problem → Concept → Build It → Use It → Ship It → Exercises. This template is defined in LESSON_TEMPLATE.md lines 25–80.

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