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

To contribute a new lesson to the AI Engineering from Scratch curriculum, scaffold a numbered folder under the appropriate phase in phases/, populate it with code/, docs/, and outputs/ subdirectories, write the narrative in docs/en.md following the standard six-beat structure, and register the lesson in the README.md and ROADMAP.md navigation tables before submitting a single-commit pull request.

The rohitg00/ai-engineering-from-scratch repository organizes its curriculum into independent lesson folders that feed a static site generator. When you contribute a new lesson to the AI Engineering curriculum, you must adhere to a strict folder hierarchy and documentation protocol that allows site/build.js to discover and render your content correctly.

Lesson Folder Structure and Requirements

Every lesson lives in a path following the pattern phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/, where <NN> is the phase number and <MM> is the lesson number. According to the LESSON_TEMPLATE.md scaffold (lines 7-21), each lesson folder must contain three subdirectories:

• code/ – Runnable implementations in Python, TypeScript, Rust, or Julia.
• docs/ – Narrative documentation containing the required en.md file.
• outputs/ – Optional artifacts such as prompts, skills, agents, or MCP servers produced by the lesson.

The repository enforces a "one commit per lesson" rule, so all changes for a single lesson must be contained within one commit.

Writing the Lesson Documentation

The docs/en.md file must begin with a standardized front-matter block as shown in LESSON_TEMPLATE.md (lines 25-34). The header follows this 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

After the front matter, the narrative must follow the six-beat structure documented in the template (lines 35-80):

1. Problem – Define the challenge being solved.
2. Concept – Explain the theoretical foundation.
3. Build It – Step-by-step implementation guide.
4. Use It – Demonstration of the working code.
5. Ship It – Deployment or production considerations.
6. Exercises – Hands-on tasks for the reader.

Registering the Lesson in Navigation Tables

The curriculum website is built from markdown tables in README.md and ROADMAP.md, which are parsed by site/build.js (as described in CONTRIBUTING.md, lines 8-11).

To make the lesson discoverable:

• In README.md: Append a row to the appropriate phase table using the format:

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

• In ROADMAP.md: Add 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 that only a timestamp change appears in site/data.js (see CONTRIBUTING.md line 22).

Submitting Your Contribution

The pull request workflow follows strict conventions to maintain CI integrity:

1. Fork the repository and create a branch named add-lesson-phase<NN>-<MM>-<lesson-slug>.
2. Ensure your implementation includes unit tests in the code/ folder and run them with python -m unittest discover.
3. Commit using a conventional title format: feat(phase-03/23): add my-new-lesson.
4. Push the branch and open a PR; the CI pipeline will automatically regenerate site data and enforce README/ROADMAP integrity.

Complete Workflow Example

The following shell commands demonstrate the full process, replacing placeholders with your actual phase and lesson identifiers:

# 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

# 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

# Edit documentation

$EDITOR phases/03-deep-learning-core/23-my-new-lesson/docs/en.md

# 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

# Update navigation tables in README.md and ROADMAP.md

# (Add row to phase table and roadmap entry)

# Run tests

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

# 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 code/, docs/, and outputs/ subdirectories.
• Write docs/en.md using the front-matter template and six-beat narrative structure defined in LESSON_TEMPLATE.md.
• Update navigation tables in README.md and ROADMAP.md to register the lesson with site/build.js.
• Submit a single-commit PR with a conventional title like feat(phase-03/23): add my-new-lesson after verifying local tests pass.

Frequently Asked Questions

What is the required folder structure for a new lesson?

You must create a folder under phases/<NN>-<phase-slug>/<MM>-<lesson-slug>/ containing three subdirectories: code/ for implementations, docs/ for the en.md narrative file, and outputs/ for optional artifacts. This structure is enforced by the site/build.js generator and documented in LESSON_TEMPLATE.md (lines 7-21).

How do I format the lesson documentation file?

The docs/en.md file must start with a front-matter block specifying Type, Languages, Prerequisites, and Time, followed by a six-beat narrative structure: Problem, Concept, Build It, Use It, Ship It, and Exercises. Refer to LESSON_TEMPLATE.md (lines 25-80) for the exact scaffold.

Where do I register the lesson so it appears on the website?

Add a row to the appropriate phase table in README.md and a corresponding entry in ROADMAP.md using the ⬚ status glyph. These tables are parsed by site/build.js to generate the site navigation and data files.

What commit message format should I use for my contribution?

Use conventional commit format: feat(phase-<NN>/<MM>): add <lesson-slug>. The repository requires exactly one commit per lesson, so stage all changes—including the new lesson folder and updates to README.md and ROADMAP.md—in a single commit before opening your pull request.

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