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

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 and validating them via 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 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 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 – The human-readable lesson documentation with mandatory front-matter
• code/main.<lang> – The executable entry point (e.g., main.py, main.ts)
• code/tests/test_main.<ext> – Unit tests exercising the implementation
• 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 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

# 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 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)

{
  "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:

python -m unittest discover -v

Example test structure:

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 script enforces the lesson contract during CI. It validates:

• Presence and schema compliance of docs/en.md front-matter
• Correct structure in 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 with case-sensitive front-matter, code/main.<lang> with a documentation header, and code/tests/ with at least five unit tests.
• The quiz.json file must contain exactly six questions distributed across pre, check, and post stages.
• The 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 script validates every field in 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 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 to ensure the build system can index and deploy these assets correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}