# The Complete Lesson Directory Contract Structure in AI Engineering from Scratch

> Understand the strict four-part contract structure for AI engineering lessons in the rohitg00/ai-engineering-from-scratch repository. Learn about documentation, code, tests, and quizzes.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: architecture
- Published: 2026-09-11

---

**Every lesson directory in the rohitg00/ai-engineering-from-scratch repository follows a strict four-part contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), requiring standardized documentation in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), runnable code with tests in `code/`, a six-question assessment in [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), and optional reusable artifacts in `outputs/`.**

The rohitg00/ai-engineering-from-scratch repository treats each lesson as a self-contained, reproducible artifact governed by a strict lesson directory contract structure. This contract ensures consistency, testability, and reusability across the entire curriculum, enabling automated validation and seamless navigation for learners. Each lesson resides in its own directory under `phases/NN-phase-slug/MM-lesson-slug/` and must obey the specifications detailed in the **AGENTS.md** file.

## The Four-Part Contract Structure

According to the source code in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 68-92), every lesson directory must implement four mandatory components to maintain curriculum integrity.

### Documentation Front-Matter ([`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md))

Each lesson must include a [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file containing a predefined front-matter block. This Markdown file defines the **lesson title**, hook, type, languages, prerequisites, estimated time, and learning objectives. The `Languages` field must accurately reflect the actual implementation by listing only languages that have a corresponding `main.*` file in the `code/` folder.

```markdown

# Linear Regression from Scratch  

> Learn how to implement ordinary least‑squares without any ML libraries.  

**Type:** Build  
**Languages:** Python  
**Prerequisites:** None  
**Time:** ~30  

## Learning Objectives

- Derive the OLS solution analytically  
- Implement the solution in pure Python  
- Visualize the fitted line with Matplotlib  
- Evaluate the model on a synthetic dataset

```

### Implementation (`code/`)

The `code/` directory houses the runnable source file named `main.<lang>` (e.g., [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.js)). This file must begin with a **4-6 line header comment** citing the lesson’s documentation path and any external specifications. The directory also contains a `tests/` subdirectory with **≥ 5 unit tests** executed via the language’s standard test runner (e.g., `python3 -m unittest discover`).

```python
"""
Lesson: linear-regression
Path: docs/en.md
External Spec: OLS Derivation v1.2
"""

import numpy as np

def ols_solution(X, y):
    """Compute Ordinary Least Squares solution."""
    return np.linalg.inv(X.T @ X) @ X.T @ y

```

### Assessment ([`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json))

Every lesson must provide a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file describing exactly **six questions**: 1 pre-check, 3 check-stage, and 2 post-check. Each entry requires `stage`, `question`, `options`, `correct` (zero-based index), and an optional `explanation`. This schema is strictly enforced by the repository’s audit scripts.

```json
{
  "lesson": "linear-regression",
  "title": "Linear Regression from Scratch",
  "questions": [
    {"stage":"pre","question":"What does OLS stand for?","options":["Ordinary Least Squares","Optimal Linear Solver","Open Learning System","None"],"correct":0,"explanation":"OLS = Ordinary Least Squares"},
    {"stage":"check","question":"Which matrix equation gives the OLS solution?","options":["XᵀXβ = Xᵀy","Xβ = y","β = (XᵀX)⁻¹Xᵀy","None"],"correct":2,"explanation":"The closed‑form solution"},
    {"stage":"check","question":"What is the time‑complexity of computing (XᵀX)⁻¹?","options":["O(n³)","O(n²)","O(n)","O(1)"],"correct":0,"explanation":"Matrix inversion is cubic in the dimension"},
    {"stage":"check","question":"Which metric is used for regression evaluation?","options":["Accuracy","Precision","Recall","RMSE"],"correct":3,"explanation":"Root‑Mean‑Square Error"},
    {"stage":"post","question":"How would you extend the model to polynomial features?","options":["Add higher‑order terms","Use a neural network","Apply regularization","None"],"correct":0,"explanation":"Add polynomial terms to X"},
    {"stage":"post","question":"What is a potential overfitting sign?","options":["Low training error, high test error","High training error, low test error","Both errors low","Both errors high"],"correct":0,"explanation":"Gap between train and test error"}
  ]
}

```

### Reusable Artifact (`outputs/`)

The optional `outputs/` directory ships concrete artifacts (skills, prompts, agents, MCP servers, etc.) that downstream lessons or learners can import. When present, the artifact must be documented and referenced in the lesson’s README row, creating a composable curriculum where advanced lessons build upon foundational components.

## Additional Constraints and Governance

Beyond the four-part structure, the contract enforces strict repository hygiene. The **one-commit-per-lesson** policy ensures atomic changes, while naming conventions require phase and lesson slugs to follow the `NN-phase-slug` and `MM-lesson-slug` patterns. Generated files such as [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) must never be committed directly to the repository (lines 44-53 of [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)).

## Validation and Compliance

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script serves as the CI-run validator that checks contract compliance. This audit script verifies:
- Front-matter fields match actual directory contents
- Quiz JSON adheres to the six-question schema
- Test directories contain the minimum five unit tests
- Language declarations align with present implementation files

By automating these checks, the repository maintains high educational quality even as it scales to hundreds of lessons.

## Summary

- **Four mandatory components**: Documentation ([`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)), Implementation (`code/`), Assessment ([`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)), and optional Artifacts (`outputs/`).
- **Strict front-matter requirements**: Must include title, type, languages, prerequisites, time estimate, and learning objectives.
- **Testing standards**: Every lesson requires ≥ 5 unit tests in `code/tests/` using standard language runners.
- **Assessment schema**: Exactly six questions following the 1-pre/3-check/2-post pattern with zero-based indexing for correct answers.
- **Automated validation**: [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) enforces contract compliance during CI/CD.

## Frequently Asked Questions

### What file defines the lesson directory contract structure?

The **AGENTS.md** file at the repository root defines the canonical contract structure. Lines 68-92 specify the four-part requirement (documentation, implementation, assessment, and artifacts), while lines 44-53 cover repository governance rules like the one-commit-per-lesson policy.

### How many unit tests must each lesson include?

Each lesson must include **at least five unit tests** in the `code/tests/` subdirectory. These tests must be executable via the language’s standard test runner, such as `python3 -m unittest discover` for Python or equivalent commands for other supported languages.

### What is the required format for the quiz.json file?

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must contain exactly **six questions** structured as: 1 pre-check question, 3 check-stage questions, and 2 post-check questions. Each question object requires `stage`, `question`, `options` (array), `correct` (zero-based integer index), and an optional `explanation` string.

### Can a lesson support multiple programming languages?

Yes, a lesson can support multiple languages, but the [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter must list each language in the `Languages` field, and each listed language must have a corresponding `main.<lang>` file in the `code/` directory. The repository validator cross-references these declarations against actual file presence.