# How to Add a New Lesson to AI Engineering from Scratch: Complete Contributor Guide

> Learn to add a new lesson to the AI Engineering from Scratch curriculum. Follow our guide for creating directories, documentation, code, tests, and quizzes. Contribute today

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-07-20

---

**To add a new lesson to the AI Engineering from Scratch curriculum, you must create a structured directory under `phases/` containing documentation, implementation code, unit tests, and a quiz file, then update the curriculum indexes and validate your changes with the audit script.**

The `rohitg00/ai-engineering-from-scratch` repository organizes its educational content into a strict directory structure defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). Each lesson follows a **lesson contract** that ensures consistency across the phases, making it discoverable by the build system and testable by CI pipelines.

## Understanding the Lesson Structure

Every lesson in the curriculum lives in its own directory under `phases/NN-phase-slug/MM-new-lesson/`, where `NN` represents the phase number and `MM` the lesson number within that phase.

### Directory Layout

Create the following skeleton to satisfy the repository’s structural requirements:

- `docs/` – Contains the lesson documentation in Markdown
- `code/` – Houses the main implementation file
- `code/tests/` – Stores unit tests for the implementation
- `outputs/` – Optional directory for reusable artifacts like skills or prompts

The repository supports implementations in **Python**, **TypeScript**, **Rust**, and **Julia**, with each language requiring specific file extensions in the `code/` directory.

### Required Files

A complete lesson requires four mandatory files:

1. [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) – Lesson description with standardized frontmatter
2. `code/main.<lang>` – Core implementation with a 4-6 line header comment citing the documentation path
3. `code/tests/test_main.<lang>` – Unit tests using the language’s standard test framework
4. [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) – Six-question assessment following the schema (1 pre-assessment, 3 check-for-understanding, 2 post-assessment)

## Step-by-Step Implementation

Follow this exact workflow to ensure your lesson passes automated validation in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).

### 1. Create the Lesson Skeleton

Use `mkdir` to generate the nested directory structure. For example, to create lesson 43 in phase 14:

```bash
mkdir -p phases/14-agent-engineering/43-new-lesson/{docs,code,code/tests,outputs}

```

This command creates all necessary subdirectories in one operation, including the optional `outputs/` folder for artifacts.

### 2. Write Documentation

Populate [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with the required frontmatter block. The file must include the title, hook, type, languages, prerequisites, time estimate, and learning objectives:

```markdown

# My New Lesson Title

> A one-line hook that sparks curiosity

**Type:** Build
**Languages:** python
**Prerequisites:** 14-agent-engineering/42-agent-workbench-capstone
**Time:** ~30

## Learning Objectives

- Implement a simple agent loop
- Demonstrate prompt engineering basics
- Write unit tests for the agent

```

The **prerequisites** field must reference existing lessons using the phase/lesson slug format to maintain curriculum dependencies.

### 3. Implement the Code

Create [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) (or the appropriate language file) beginning with a standardized header comment that links back to the documentation:

```python

# Lesson: My New Lesson Title

# Docs: phases/14-agent-engineering/43-new-lesson/docs/en.md

# Implements a trivial echo agent for illustration

def agent(prompt: str) -> str:
    return f"Echo: {prompt}"

```

The header comment must span 4-6 lines and cite the exact documentation path for traceability.

### 4. Add Unit Tests

Populate [`code/tests/test_main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/tests/test_main.py) with **at least five** test cases using the standard library’s testing framework:

```python
import unittest
from main import agent

class TestAgent(unittest.TestCase):
    def test_echo(self):
        self.assertEqual(agent("hello"), "Echo: hello")

if __name__ == "__main__":
    unittest.main()

```

Run tests locally before committing:

```bash
cd phases/14-agent-engineering/43-new-lesson/code
python3 main.py && python3 -m unittest discover tests -v

```

### 5. Create the Quiz

Write [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) following the strict six-question schema. The file must contain exactly one pre-assessment question, three check-for-understanding questions, and two post-assessment questions:

```json
{
  "lesson": "43-new-lesson",
  "title": "My New Lesson Title",
  "questions": [
    {"stage":"pre","question":"...","options":["a","b","c","d"],"correct":0,"explanation":""},
    {"stage":"check","question":"...","options":["a","b","c","d"],"correct":1,"explanation":""},
    {"stage":"check","question":"...","options":["a","b","c","d"],"correct":2,"explanation":""},
    {"stage":"check","question":"...","options":["a","b","c","d"],"correct":1,"explanation":""},
    {"stage":"post","question":"...","options":["a","b","c","d"],"correct":3,"explanation":""},
    {"stage":"post","question":"...","options":["a","b","c","d"],"correct":0,"explanation":""}
  ]
}

```

Each question object requires the `stage`, `question`, `options` array, `correct` index, and `explanation` fields.

### 6. Update Curriculum Indexes

You must modify three index files to register the new lesson:

- **README.md** – Insert a markdown table row linking to the lesson directory: `[Lesson Title](phases/NN-phase-slug/MM-new-lesson/)`
- **ROADMAP.md** – Add a row tracking the lesson status (e.g., *WIP* or *Done*)
- **glossary/terms.md** – Add entries for any new terminology introduced

These updates ensure the lesson appears in the public curriculum index and build pipeline.

## Validation and Testing

Before submitting, execute the audit script to check for contract violations:

```bash
python3 scripts/audit_lessons.py

```

This script validates directory structure, file presence, quiz schema compliance, and documentation frontmatter. Fix any reported errors to prevent CI failures.

Commit only the new lesson directory and the three modified index files using conventional commit format:

```bash
git add phases/14-agent-engineering/43-new-lesson/ README.md ROADMAP.md glossary/terms.md
git commit -m "feat(phase-14/43): add new-lesson-slug"

```

## CI Pipeline Integration

When you open a pull request, the CI pipeline automatically executes three jobs:

1. **`audit`** – Re-runs [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) to verify contract compliance
2. **`readme-counts-sync`** – Synchronizes lesson counts in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)
3. **`site-rebuild`** – Regenerates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) for the documentation website

These automated checks ensure that every merged lesson is immediately available and correctly indexed.

## Summary

- Create the directory skeleton under `phases/` with `docs/`, `code/`, `code/tests/`, and optional `outputs/` subdirectories
- Write [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with mandatory frontmatter including prerequisites and learning objectives
- Implement `code/main.<lang>` with a standardized header comment linking to documentation
- Provide **≥5** unit tests in `code/tests/` using the language’s standard framework
- Structure [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) with exactly six questions (1 pre, 3 check, 2 post)
- Update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md) to register the lesson
- Validate locally with `python3 scripts/audit_lessons.py` before committing

## Frequently Asked Questions

### What is the lesson contract in AI Engineering from Scratch?

The **lesson contract** is a set of structural and content requirements defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) that governs how lessons must be organized. It mandates specific directory layouts, frontmatter fields, test coverage minimums, and quiz schemas to ensure every lesson works with the automated build and validation systems.

### Which programming languages can I use for lesson implementations?

The repository currently supports **Python**, **TypeScript**, **Rust**, and **Julia**. You must place the main implementation in `code/main.<ext>` using the appropriate extension, and the test file must use the language’s standard testing framework (e.g., `unittest` for Python).

### How many unit tests are required for a new lesson?

You must write **at least five** unit tests in `code/tests/test_main.<ext>` according to the contributor guidelines. The CI pipeline will fail if the test directory is missing or contains fewer than five test cases.

### What happens if the audit script finds errors?

If [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) reports contract violations—such as missing frontmatter, incorrect directory structure, or malformed quiz JSON—you must fix these issues before submitting your pull request. The CI pipeline runs this script automatically and will block merging until all violations are resolved.