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 lesson folder under phases/ containing code/, docs/, and outputs/ subdirectories, author the documentation in docs/en.md using the standard front‑matter template, and register the lesson by appending entries to the navigation tables in README.md and 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 (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.
• 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:

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 and must begin with a standardized front‑matter block defined in LESSON_TEMPLATE.md (lines 25‑34). This metadata drives the site’s lesson cards and search indexing.

Required Front‑Matter Format

# 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 (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) parses README.md and ROADMAP.md to construct the curriculum navigation (see 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 using the format:

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

⬚ 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 (see 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 file.

3. Test locally – Run the unit tests within the lesson’s code/ folder:

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

4. Commit – Stage the lesson folder, README.md, and ROADMAP.md in a single commit using conventional commit format:

   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:

# 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 following the front‑matter template and six‑beat narrative structure defined in LESSON_TEMPLATE.md.
• Register the lesson by appending rows to the phase tables in README.md and ROADMAP.md so 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 parses the markdown tables in README.md and ROADMAP.md at build time to construct the navigation and lesson registry. It also processes 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 update, and the 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 (e.g., **Languages:** Python, Rust), and the site generator will display the appropriate language badges in the lesson card.

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