# How Lessons Are Documented in AI Engineering from Scratch: The 5-Component Structure

> Discover how AI Engineering from Scratch documents lessons using a 5-component structure including metadata, reference code, unit tests, quizzes, and outputs for reproducible learning.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-08-26

---

**TLDR:** The AI Engineering from Scratch curriculum enforces a strict, reproducible documentation standard where every lesson contains five mandatory components—metadata in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), reference code in `code/`, unit tests in `code/tests/`, a structured [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), and optional `outputs/`—all governed by the lesson contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).

The rohitg00/ai-engineering-from-scratch repository implements a self-documenting curriculum architecture that ensures every lesson is testable, reproducible, and pedagogically consistent. Each lesson lives within a phase directory (e.g., `phases/01-foundations/05-linear-algebra/`) and follows a rigid folder structure defined by the **lesson contract** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). This system allows learners and contributors to understand, execute, and validate any lesson in isolation while maintaining coherence across the broader AI engineering roadmap.

## The Five-Component Lesson Structure

Every lesson in the AI Engineering from Scratch curriculum is organized into five distinct components that separate intent from implementation and verification from assessment.

### 1. Lesson Metadata – [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file serves as the canonical source for lesson documentation and website rendering. This file contains **front-matter metadata** following the strict template defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), requiring specific fields:

- **Title**: The lesson headline
- **Hook**: Engagement statement
- **Type**: Classification (e.g., foundations, capstone)
- **Languages**: Supported programming languages
- **Prerequisites**: Required prior knowledge
- **Time**: Estimated completion duration
- **Learning Objectives**: Bullet list of measurable outcomes

For example, in [`phases/19-capstone-projects/01-terminal-native-coding-agent/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/01-terminal-native-coding-agent/docs/en.md), this metadata drives both the curriculum website and learner expectations.

### 2. Executable Code – `code/`

The `code/` directory houses the **reference implementation** (`main.<lang>`) written from first principles, deliberately avoiding black-box library calls where possible. This directory contains the actual executable content that learners run to complete the lesson, with implementations provided in the languages specified in the lesson metadata.

### 3. Verification Suite – `code/tests/`

Each lesson ships with **at least five unit tests** located in `code/tests/` to validate the reference implementation. These tests are executed using the language's standard runner, such as:

```bash
python3 -m unittest discover

```

The test suite ensures that implementations remain functional across different environments and provides immediate feedback to learners when their code deviates from expected behavior.

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

Every lesson includes a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file that follows a strict **six-question schema**:

- 1 pre-check question
- 3 check-stage questions
- 2 post-check questions

This structured quiz drives learner self-assessment and integrates with the curriculum CI pipeline to enforce comprehension before progression.

### 5. Reusable Artifacts – `outputs/`

When lessons produce reusable artifacts—such as prompt templates, skill files, or model checkpoints—these are placed in the optional `outputs/` directory. This separation ensures that generated assets remain accessible for downstream lessons without cluttering the source code.

## The Lesson Contract in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)

The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file at the repository root defines the **lesson contract** that binds all components together. This contract enforces consistency across the entire curriculum, specifying:

- The required directory structure
- Front-matter schema validation rules
- Testing requirements (minimum five unit tests)
- Quiz schema constraints

By adhering to this contract, contributors can scaffold new lessons that integrate seamlessly into the existing AI Engineering from Scratch learning path.

## Minimal Lesson Scaffold

Below is the standard directory structure for a new lesson in the curriculum:

```text
phases/XX-phase-slug/YY-new-lesson/
├─ docs/
│  └─ en.md                 # front-matter + narrative content

├─ code/
│  ├─ main.py               # reference implementation

│  └─ tests/
│     └─ test_main.py       # ≥5 unit tests

├─ quiz.json                # 6-question assessment

└─ outputs/                 # optional reusable artifacts

```

## Summary

- Every lesson in rohitg00/ai-engineering-from-scratch follows a rigid five-component structure: [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/`, `code/tests/`, [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), and optional `outputs/`.
- The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file defines the lesson contract that enforces metadata schema, testing requirements, and directory conventions.
- Lessons must include at least five unit tests in `code/tests/` to verify implementations.
- The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file follows a strict six-question format (1 pre-check, 3 check-stage, 2 post-check) for assessment.
- This architecture makes the curriculum self-documenting, testable, and extensible for both learners and contributors.

## Frequently Asked Questions

### What metadata fields are required in the [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter?

According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification, the [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must include **Title**, **Hook**, **Type**, **Languages**, **Prerequisites**, **Time**, and a **Learning Objectives** list. These fields populate the curriculum website and establish clear expectations for learners before they begin the lesson.

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

The lesson contract requires **at least five unit tests** in the `code/tests/` directory. These tests validate the reference implementation and are executed by the language's standard test runner, ensuring that the lesson code remains functional across different environments and use cases.

### What is the structure of the [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) assessment file?

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file follows a strict **six-question schema** consisting of 1 pre-check question, 3 check-stage questions, and 2 post-check questions. This structure enforces learner comprehension at specific milestones and integrates with the curriculum's CI pipeline to validate understanding.

### Where are lesson outputs and artifacts stored?

Reusable artifacts generated during a lesson—such as prompt templates, skill files, or model checkpoints—are stored in the optional `outputs/` directory. This separation keeps generated assets organized and accessible for downstream lessons while maintaining a clean separation from source code and documentation.