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

Create a folder under phases/ with code/, docs/, and outputs/ subdirectories, write the documentation in docs/en.md using the template from LESSON_TEMPLATE.md, and update the navigation tables in README.md and ROADMAP.md to register the lesson.

The AI Engineering From Scratch curriculum organizes hands-on tutorials into independent lesson folders within the phases/ directory. Adding a new lesson to the rohitg00/ai-engineering-from-scratch repository requires scaffolding the correct folder structure, writing standardized documentation, and updating the navigation tables that the site generator parses. This guide covers the exact file paths and validation steps defined in the repository's contribution workflow.

Create the Lesson Folder Structure

Every lesson must reside in a path following the convention phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/, where NN is the phase number and MM is the lesson number. For example, a new lesson numbered 23 in Phase 3 would live at phases/03-deep-learning-core/23-my-new-lesson/.

Inside this folder, you must create three subdirectories:

• code/ – Stores runnable implementations in Python, TypeScript, Rust, or Julia.
• docs/ – Contains the narrative documentation, specifically the required en.md file.
• outputs/ – Holds optional deliverables such as prompts, skills, agents, or MCP servers produced by the lesson.

The exact folder skeleton is documented in LESSON_TEMPLATE.md (lines 7–21). You can copy this template to scaffold your new lesson quickly.

Write the Lesson Documentation

The primary content file is docs/en.md. This file must begin with a standardized front-matter block that the site generator and readers use to filter content:

# 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 defined in LESSON_TEMPLATE.md (lines 35–80):

1. Problem – Define the challenge.
2. Concept – Explain the theory.
3. Build It – Implement the solution.
4. Use It – Demonstrate usage.
5. Ship It – Production considerations.
6. Exercises – Practice problems.

Register the Lesson in Navigation

The curriculum UI is built from markdown tables in README.md and ROADMAP.md. The site/build.js script parses these files to generate site/data.js, which serves as the site's source of truth.

To make your lesson discoverable:

Update README.md by appending a row to the appropriate phase table:

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

Update ROADMAP.md by adding a matching entry under the correct phase section, using the status glyph ⬚ for work-in-progress:

⬚ 23  My New Lesson

After editing these files, run the site generator locally to verify integration. According to CONTRIBUTING.md (line 22), only the timestamp in site/data.js should change if the registration is correct.

Submit Your Changes via Pull Request

The repository enforces a strict "one commit per lesson" rule and uses conventional commit prefixes. Follow this workflow:

1. Fork the repository and create a feature branch (e.g., add-lesson-phase3-23-my-new-lesson).
2. Commit all changes for the lesson folder, README.md, and ROADMAP.md together.
3. Test your code by running python -m unittest discover inside the lesson's code/ folder.
4. Push your branch and open a PR with a title like feat(phase-03/23): add my-new-lesson.

The CI pipeline automatically validates the README/ROADMAP integrity and regenerates the site data.

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 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 table (manual step)

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

# 6. Update ROADMAP.md (manual step)

# Add: ⬚ 23  My New Lesson

# 7. Test

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

Summary

• Structure: Place lessons at phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/ with mandatory code/, docs/, and outputs/ folders.
• Documentation: Write docs/en.md using the front-matter template from LESSON_TEMPLATE.md and follow the six-beat narrative structure.
• Registration: Append rows to the phase tables in README.md and ROADMAP.md so site/build.js can discover the content.
• Validation: Run unit tests locally and verify only the timestamp changes in site/data.js after running the site generator.
• Submission: Use conventional commit messages (feat(phase-XX/YY): description) and bundle all changes into a single commit per lesson.

Frequently Asked Questions

What is the exact 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, lesson 5 in phase 2 would be phases/02-foundations/05-embedding-basics/. This structure is required for site/build.js to parse the curriculum correctly.

Do I need to manually update the website HTML after adding a lesson?

No. The curriculum uses a static site generator driven by site/build.js. This script automatically parses README.md, ROADMAP.md, and lesson metadata to generate site/data.js. Simply updating the markdown tables and pushing your changes triggers the CI pipeline to rebuild the site.

How do I mark a lesson as work-in-progress in the roadmap?

Use the glyph ⬚ (empty box) in ROADMAP.md to indicate work-in-progress status. When the lesson is complete, update this to ✅. The repository maintains a "readme-counts-sync" CI job that validates these glyphs match the actual folder structure.

Can I include multiple programming languages in a single lesson?

Yes. The docs/en.md front matter supports multiple languages in the Languages field (e.g., Python, TypeScript). Place language-specific code in the code/ subdirectory, organizing by file extension or subfolders as needed. Ensure you list all supported languages in the README.md table row when registering the lesson.

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