# How to Add a New Lesson Using the AI Engineering from Scratch Curriculum Template

> Easily add new lessons to the AI Engineering from Scratch curriculum template. Follow our step-by-step guide for directory structure, content population, code implementation, and testing.

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

---

**To add a new lesson to the rohitg00/ai-engineering-from-scratch curriculum, scaffold the directory `phases/NN-phase-slug/MM-new-lesson/` with the mandatory four-folder layout, populate [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with YAML-like front-matter, implement the source code with a path-citing header, provide at least five unit tests, define a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) following the schema, and register the entry in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) before committing atomically.**

The `rohitg00/ai-engineering-from-scratch` repository organizes its curriculum into self-contained lessons that follow a strict contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). Adding a new lesson requires adhering to a specific file structure and metadata format that enables automated catalog generation, site building, and CI validation. This guide provides the exact sequence of steps and file templates needed to integrate a new lesson seamlessly.

## Step-by-Step Guide to Adding a New Lesson

### 1. Scaffold the Directory Structure

Create the lesson directory under the appropriate phase folder. The path must follow the pattern `phases/NN-phase-slug/MM-new-lesson/` and contain four mandatory subdirectories.

```bash
mkdir -p phases/01-math-foundations/99-matrix-multiplication/{docs,code/tests,outputs}

```

This layout—`docs/`, `code/`, `code/tests/`, and `outputs/`—is enforced by the lesson contract in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 63-79) and is required for the build pipeline to recognize the lesson.

### 2. Document the Lesson in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)

Every lesson requires a [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file with structured front-matter that drives the autogenerated README tables and roadmap. The front-matter must include the title, one-line hook, type, languages, prerequisites, time estimate, and learning objectives.

```markdown

# Matrix Multiplication

> Multiply two matrices element-wise.

**Type:** Build
**Languages:** python
**Prerequisites:** Linear Algebra Intuition
**Time:** ~30min

## Learning Objectives

- Derive the matrix-product formula
- Implement a naïve O(n³) multiplication
- Validate with unit tests

```

According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification (lines 65-79), this metadata is parsed by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) to generate static site navigation and lesson cards.

### 3. Implement the Core Code

Create `code/main.<lang>` (e.g., [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py)) and begin with a 4-6 line header comment that anchors the source file to its documentation. This satisfies the `code/` contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 102-107).

```python

# File: code/main.py

# Lesson: phases/01-math-foundations/99-matrix-multiplication/docs/en.md

# Implements a naïve matrix multiplication from scratch.

import numpy as np

def matmul(A: np.ndarray, B: np.ndarray) -> np.ndarray:
    """Return A @ B using a triple-nested loop."""
    assert A.shape[1] == B.shape[0], "inner dimensions must match"
    C = np.zeros((A.shape[0], B.shape[1]), dtype=A.dtype)
    for i in range(A.shape[0]):
        for j in range(B.shape[1]):
            for k in range(A.shape[1]):
                C[i, j] += A[i, k] * B[k, j]
    return C

```

### 4. Write Comprehensive 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 tests exercising the public API. The test suite ensures the lesson runs end-to-end and passes CI gates.

```python
import unittest
import numpy as np
from ..main import matmul

class TestMatMul(unittest.TestCase):
    def test_identity(self):
        I = np.eye(3)
        A = np.random.randn(3, 3)
        self.assertTrue(np.allclose(matmul(A, I), A))

    def test_random(self):
        A = np.random.randn(2, 3)
        B = np.random.randn(3, 4)
        self.assertTrue(np.allclose(matmul(A, B), A @ B))

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

```

### 5. Configure the Assessment Quiz

Create [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) in the lesson root following the schema from [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 83-98). Include pre-check, check, and post-quiz questions.

```json
{
  "lesson": "99-matrix-multiplication",
  "title": "Matrix Multiplication",
  "questions": [
    { "stage": "pre",   "question": "What does A @ B represent?", "options": ["Sum", "Product", "Difference", "None"], "correct": 1, "explanation": "" },
    { "stage": "check", "question": "What is the time complexity of the naïve algorithm?", "options": ["O(n)", "O(n²)", "O(n³)", "O(log n)"], "correct": 2, "explanation": "" },
    { "stage": "check", "question": "Which dimension must match for multiplication?", "options": ["Rows-Rows", "Cols-Cols", "Rows-Cols", "Cols-Rows"], "correct": 3, "explanation": "" },
    { "stage": "check", "question": "What is the result of multiplying a matrix by the identity matrix?", "options": ["Zero matrix", "The original matrix", "Transposed matrix", "None"], "correct": 1, "explanation": "" },
    { "stage": "post",  "question": "Can the algorithm be parallelised?", "options": ["Yes", "No", "Only on GPUs", "Only on CPUs"], "correct": 0, "explanation": "" },
    { "stage": "post",  "question": "Which library provides a faster implementation?", "options": ["NumPy", "SciPy", "Pandas", "Matplotlib"], "correct": 0, "explanation": "" }
  ]
}

```

### 6. Register in Public Indexes

Update the master [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) by inserting a row into the lessons table so the site builder can discover the lesson.

```markdown
| # | Lesson | Type | Lang |

|:---:|--------|:----:|------|
| 99 | [Matrix Multiplication](phases/01-math-foundations/99-matrix-multiplication/) | Build | Python |

```

Simultaneously, update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to reflect the lesson status (e.g., "WIP → Done").

### 7. Validate Locally and Commit

Run the per-lesson sanity checks before committing. Navigate to the code directory and execute the implementation and tests.

```bash
cd phases/01-math-foundations/99-matrix-multiplication/code
python3 main.py && python3 -m unittest discover tests -v

```

Once validation passes, commit atomically following the hard rules in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 38-47). The commit must be single-purpose and use conventional commit format.

```bash
git add phases/01-math-foundations/99-matrix-multiplication README.md ROADMAP.md
git commit -m "feat(phase-01/99): add matrix-multiplication"
git push -u origin <your-branch>
gh pr create --title "feat(phase-01/99): add matrix-multiplication" --body "<5-line summary>"

```

## Summary

- **Directory Layout**: Create `phases/NN-phase-slug/MM-lesson/` with `docs/`, `code/tests/`, and `outputs/` subdirectories.
- **Documentation**: Write [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with mandatory front-matter (Type, Languages, Prerequisites, Time, Learning Objectives).
- **Code Standards**: Implement `code/main.<lang>` with a header comment citing the lesson path, and provide at least five unit tests in `code/tests/`.
- **Assessment**: Define [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) with pre-check, check, and post-quiz questions per the schema.
- **Registration**: Add entries to [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) (lessons table) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) (status tracking).
- **Validation**: Run local tests (`python3 main.py && python3 -m unittest discover tests -v`) before committing.
- **Git Workflow**: Commit atomically with conventional commit messages (`feat(phase-NN/MM): add <slug>`) and open a pull request.

## Frequently Asked Questions

### What happens if I don't include the front-matter in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)?

The curriculum automation relies on the front-matter to populate the README tables and generate the static site navigation. Without it, [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) will fail to index your lesson, and it will not appear in the public catalog.

### Can I use a language other than Python for the implementation?

Yes. The **Languages** field in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) accepts any value, and `code/main.<lang>` can use any extension. However, you must still provide a test suite in `code/tests/` and ensure the header comment in `main.<lang>` cites the correct path to [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md).

### Is the `outputs/` directory mandatory?

No. The `outputs/` folder is optional and only required if your lesson generates a reusable artifact such as a skill, prompt, or MCP server. If present, place a Markdown file describing the artifact (e.g., [`outputs/skill-matrix-multiplication.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/skill-matrix-multiplication.md)) so it can be discovered by [`scripts/install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/install_skills.py).

### How many questions must [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) contain?

The schema requires a minimum structure covering pre-check, check, and post stages. While the exact number is not strictly enforced, the standard template includes six questions to adequately assess comprehension before, during, and after the lesson.