# Understanding the Lesson Contract in AGENTS.md: Required Files and Structure

> Discover the lesson contract in AGENTS.md. Learn the essential files and structure required for each lesson in ai-engineering-from-scratch to ensure automated validation and publication.

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

---

**The lesson contract in AGENTS.md defines the mandatory file structure, metadata schema, and validation rules that every lesson in the ai-engineering-from-scratch curriculum must satisfy to pass automated auditing and be published.**

The rohitg00/ai-engineering-from-scratch repository enforces strict educational standards through this formal contract, ensuring each lesson is self-contained, executable, and testable. By codifying requirements in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and validating them via [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), the curriculum maintains consistency across all phases and enables automated rendering by the site generator.

## What Is the Lesson Contract in AGENTS.md?

The **lesson contract** is a specification document that dictates exactly how lesson content must be organized and formatted. Located in the repository root, [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) serves as the single source of truth for the curriculum's structure. It mandates that every lesson expose specific artifacts—documentation, code, tests, and assessments—in predictable locations with strict schemas.

This contract guarantees that the [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) CI script can automatically validate completeness. Any deviation, such as missing front-matter fields or fewer than five unit tests, triggers a build failure.

## Required Files for Each Lesson

Every lesson must reside under the path structure:

```

phases/<phase-number>-phase-slug/<lesson-number>-lesson-slug/

```

From this root, the following files are mandatory:

- **[`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** – The human-readable lesson documentation with mandatory front-matter
- **`code/main.<lang>`** – The executable entry point (e.g., [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts))
- **`code/tests/test_main.<ext>`** – Unit tests exercising the implementation
- **[`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)** – Structured assessment adhering to the six-question schema
- **`outputs/`** – *(Optional)* Directory for reusable artifacts like skills or prompts

Each file must use exact naming conventions; case sensitivity matters for both filenames and internal metadata keys.

## Front-Matter Requirements for docs/en.md

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must begin with a markdown front-matter block containing specific, case-sensitive fields. The block must include:

- **title** – The lesson title
- **hook** – A brief engagement sentence
- **type** – Classification (e.g., Learn, Build)
- **languages** – Supported programming languages
- **prerequisites** – Required prior knowledge
- **time estimate** – Expected completion duration
- **learning objectives** – Bullet list of measurable outcomes

```markdown

# Gradient Descent in One Dimension

> A gentle introduction to the most fundamental optimizer.

**Type:** Learn  
**Languages:** Python  
**Prerequisites:** None  
**Time:** ~15 minutes  

## Learning Objectives

- Derive the gradient descent update rule
- Implement a simple optimizer from scratch
- Visualize convergence on a quadratic loss

```

Missing any field causes the audit script to reject the lesson.

## Quiz Schema for quiz.json

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must follow a strict JSON schema containing exactly six questions. Each question object requires:

- **stage** – One of `pre`, `check`, or `post`
- **question** – The question text
- **options** – Array of possible answers
- **correct** – Zero-based index of the correct option
- **explanation** – Context for the answer (may be empty)

```json
{
  "lesson": "01-gradient-descent",
  "title": "Gradient Descent in One Dimension",
  "questions": [
    {"stage": "pre",   "question": "What does 'gradient' refer to in optimization?", "options": ["Direction of steepest ascent","Direction of steepest descent","Maximum value","Minimum value"], "correct": 0, "explanation": ""},
    {"stage": "check", "question": "Which learning-rate value will cause divergence for a convex quadratic?", "options": ["0.1","0.5","1.0","2.0"], "correct": 3, "explanation": ""},
    {"stage": "check", "question": "What is the effect of a too-small learning-rate?", "options": ["Fast convergence","Slow convergence","No convergence","Oscillation"], "correct": 1, "explanation": ""},
    {"stage": "check", "question": "Which Python library is *not* allowed for this lesson?", "options": ["numpy","torch","pandas","h5py"], "correct": 2, "explanation": ""},
    {"stage": "post",  "question": "After training, the loss should be close to", "options": ["0","1","Infinity","NaN"], "correct": 0, "explanation": ""},
    {"stage": "post",  "question": "Which statement best describes the algorithm?", "options": ["Stochastic","Deterministic","Random","Heuristic"], "correct": 1, "explanation": ""}
  ]
}

```

The schema requires at least one `pre` question, multiple `check` questions for interim validation, and `post` questions for final assessment.

## Code and Testing Standards

The `code/main.<lang>` file must be a runnable entry point that exits with status 0. It must include a header comment citing the lesson documentation and any external specifications. According to the curriculum's std-lib-only policy, implementations should avoid external dependencies unless explicitly permitted.

The `code/tests/` directory must contain **at least five** unit tests runnable with the language's standard test runner:

```bash
python -m unittest discover -v

```

Example test structure:

```python
import unittest
from main import gradient_descent

class TestGradientDescent(unittest.TestCase):
    def test_converges_to_zero(self):
        grads = [2 * i for i in [5, 4, 3, 2, 1]]
        self.assertAlmostEqual(gradient_descent(0.1, grads), 0.0, places=5)

    def test_no_update_when_step_zero(self):
        grads = [1, 2, 3]
        self.assertEqual(gradient_descent(0.0, grads), 0.0)

    def test_negative_step(self):
        grads = [1, -1]
        self.assertEqual(gradient_descent(-0.5, grads), 0.5)

    def test_multiple_calls(self):
        grads = [1, 1, 1]
        self.assertNotEqual(gradient_descent(0.1, grads), gradient_descent(0.2, grads))

    def test_type_error(self):
        with self.assertRaises(TypeError):
            gradient_descent(0.1, "not a list")

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

```

## Optional Outputs Directory

When a lesson produces a reusable artifact—such as a skill definition, prompt template, agent configuration, or MCP server—it must be stored in the `outputs/` directory. While optional, this directory follows strict naming conventions when present, ensuring artifacts can be automatically discovered and indexed by the curriculum's build system.

## Automated Enforcement via scripts/audit_lessons.py

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script enforces the lesson contract during CI. It validates:

- Presence and schema compliance of [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter
- Correct structure in [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) (exactly six questions with valid stages)
- Existence of `code/main.<lang>` with proper header comments
- Minimum of five tests in `code/tests/`
- Exit status 0 when running the test suite

Any violation fails the build, preventing incomplete lessons from merging into the main branch.

## Summary

- The **lesson contract in AGENTS.md** mandates specific file structures and metadata schemas for all curriculum content in rohitg00/ai-engineering-from-scratch.
- Every lesson requires [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with case-sensitive front-matter, `code/main.<lang>` with a documentation header, and `code/tests/` with at least five unit tests.
- The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must contain exactly six questions distributed across `pre`, `check`, and `post` stages.
- The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) CI script automatically validates all contract requirements, rejecting lessons with missing or malformed components.
- Optional artifacts may be stored in `outputs/` when lessons produce reusable skills, prompts, or agents.

## Frequently Asked Questions

### What happens if a lesson file is missing a required front-matter field?

The CI audit will fail. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script validates every field in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) against the contract specification, and missing fields—such as `prerequisites` or `learning objectives`—trigger immediate build errors that block publication.

### Can I use external libraries in the code implementation?

Generally no. The contract specifies that `code/main.<lang>` should use only the language's standard library unless the lesson documentation explicitly permits specific external dependencies. This ensures all lessons remain reproducible without complex environment setup.

### How does the quiz.json schema enforce the six-question requirement?

The audit script validates that [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) contains exactly six question objects, each with a `stage` property set to `pre`, `check`, or `post`. The schema requires at least one pre-assessment question, multiple check-in questions during the lesson, and post-assessment questions to verify learning outcomes.

### Where should reusable lesson artifacts be stored?

Reusable artifacts such as prompt files, agent configurations, or MCP servers belong in the `outputs/` directory at the lesson root. While this directory is optional, when present it must follow the naming conventions specified in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) to ensure the build system can index and deploy these assets correctly.