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

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 following the standard template, and register the lesson in README.md and 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 and the scaffolding template in 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 file.
• outputs/ – Optional storage for prompts, skills, agents, or MCP servers produced by the lesson.

As defined in 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 and must adhere to strict formatting standards for the site generator (site/build.js) to parse it correctly.

Front Matter Requirements

Begin the file with the standard front-matter block specified 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

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 and 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. For example, to add lesson 23 to Phase 3:

| 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, using the status glyph ⬚ to indicate work-in-progress:

  ⬚ 23  My New Lesson

According to the source code in site/build.js, these files are parsed to generate 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 (as noted in 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:

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/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:

# 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 using the front-matter template from LESSON_TEMPLATE.md and the six-beat narrative structure.
• Register the lesson by adding entries to README.md (navigation table) and 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 generates only timestamp changes in 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. Additionally, you must update the top-level README.md and 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 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 and helps reviewers isolate changes to specific curriculum additions.

How does the site generator discover new lessons?

The site generator script site/build.js parses the markdown tables in README.md and ROADMAP.md, along with glossary/terms.md, to produce 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.

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