AI Engineering From Scratch Lesson Contract: Complete Technical Specification

The Lesson Contract is a formal specification defined in AGENTS.md that mandates every lesson in the rohitg00/ai-engineering-from-scratch curriculum include standardized front-matter metadata in docs/en.md and a structured six-question quiz in quiz.json to ensure consistency across all 435 lessons.

The rohitg00/ai-engineering-from-scratch repository maintains rigorous quality standards across its extensive curriculum through a formal Lesson Contract. This contract governs how lesson content is authored, structured, and validated before integration. According to the source code in AGENTS.md, the specification defines exact metadata fields, file locations, and assessment schemas that every lesson must implement to remain compatible with the curriculum's automated audit tooling.

What Is the Lesson Contract?

The Lesson Contract is the authoritative specification that standardizes content creation across the AI Engineering From Scratch curriculum. As documented in AGENTS.md (lines ~68-123), this contract ensures that all 435 lessons follow identical patterns for documentation, assessment, and code presentation. The specification splits into two mandatory components: standardized front-matter for lesson documentation and a fixed JSON schema for knowledge validation.

Core Components of the Lesson Contract

Required Front-Matter in docs/en.md

Every lesson must contain a docs/en.md file beginning with strict front-matter headers. According to AGENTS.md (lines ~68-78), the markdown document must start with:

• Title: The lesson's display name
• One-line hook: A concise teaser describing the lesson's value
• Type: One of Learn, Build, or Reference
• Languages: Comma-separated list matching the main.* files in the code/ folder
• Prerequisites: Up-stream lesson dependencies or "None"
• Time: Estimated duration (e.g., ~10 minutes)

Following the front-matter, the document must include a Learning Objectives section containing 4-6 bullet points, each beginning with an action verb.

quiz.json Schema Requirements

The second mandatory component is a quiz.json file adhering to a fixed schema defined in AGENTS.md (lines ~94-123). The JSON must include:

• lesson: Identifier string
• title: Quiz title matching the lesson
• questions: Array of exactly six question objects:
  • 1 pre-quiz question ("stage": "pre")
  • 3 check-quiz questions ("stage": "check")
  • 2 post-quiz questions ("stage": "post")

Each question object requires:

• stage: pre, check, or post
• question: Prompt text
• options: Array of four answer choices
• correct: Zero-indexed integer (0-3) indicating the correct answer position
• explanation: Short rationale for the correct answer

File Structure and Validation

The repository enforces the Lesson Contract through automated tooling. The scripts/audit_lessons.py script validates each lesson directory against these requirements before any merge. Key files involved in the contract include:

• AGENTS.md: Contains the complete Lesson Contract definition
• phases/*/README.md: Lesson-specific documentation referencing the contract
• phases/*/*/docs/en.md: Content file with required front-matter
• phases/*/*/quiz.json: Assessment file adhering to the six-question schema

Practical Implementation Examples

docs/en.md Front-Matter Example

# Backpropagation from Scratch

> Derive the back-propagation algorithm without any library help.

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

## Learning Objectives

- Derive the gradient of a simple linear model.
- Implement the backward pass manually.
- Verify gradients with numerical approximation.
- Explain why back-propagation scales to deep networks.

quiz.json Schema Example

{
  "lesson": "backpropagation",
  "title": "Backpropagation from Scratch",
  "questions": [
    {"stage":"pre","question":"What does \"back-propagation\" compute?","options":["Loss","Gradients","Activations","Weights"],"correct":1,"explanation":"It computes gradients of the loss w.r.t. parameters."},
    {"stage":"check","question":"Which rule is used for gradient calculation?","options":["Chain Rule","Product Rule","Quotient Rule","L'Hôpital's Rule"],"correct":0,"explanation":"Back-propagation applies the chain rule."},
    {"stage":"check","question":"What is the purpose of a learning rate?","options":["Scale gradients","Initialize weights","Normalize data","Select optimizer"],"correct":0,"explanation":"It scales the gradient step size."},
    {"stage":"check","question":"Which of the following is a common issue with naive back-prop?","options":["Vanishing gradients","Exploding gradients","Both","None"],"correct":2,"explanation":"Both vanishing and exploding gradients can occur."},
    {"stage":"post","question":"What does a gradient-check verify?","options":["Speed","Correctness","Memory usage","Precision"],"correct":1,"explanation":"It checks that analytical gradients match numerical approximations."},
    {"stage":"post","question":"Which library can auto-differentiate?","options":["NumPy","PyTorch","Pandas","Matplotlib"],"correct":1,"explanation":"PyTorch provides automatic differentiation."}
  ]
}

Summary

• The Lesson Contract in AGENTS.md mandates standardized lesson structures across the rohitg00/ai-engineering-from-scratch curriculum.
• Every lesson requires docs/en.md with specific front-matter headers (Title, Type, Languages, Prerequisites, Time) and 4-6 action-oriented learning objectives.
• The quiz.json file must contain exactly six questions: one pre-quiz, three check-quizzes, and two post-quizzes, each with four options and zero-indexed correct answers.
• The scripts/audit_lessons.py validation script enforces compliance automatically, ensuring all 435 lessons maintain uniform quality and structure.
• File paths follow the convention phases/*/*/docs/en.md and phases/*/*/quiz.json for lesson content and assessments respectively.

Frequently Asked Questions

What files are required to satisfy the AI Engineering From Scratch Lesson Contract?

Each lesson must provide a docs/en.md file containing standardized front-matter metadata and learning objectives, plus a quiz.json file with exactly six assessment questions. The repository's scripts/audit_lessons.py validates these files against the specification in AGENTS.md before merging.

How are quizzes structured in the curriculum?

The quiz.json schema requires an array of six questions: one pre-quiz to assess prior knowledge, three check-quizzes to verify understanding during the lesson, and two post-quizzes to confirm retention. Each question must provide four options with the correct answer specified as a zero-indexed integer (0-3) and a brief explanation.

What types of lessons does the contract support?

The Type field in the front-matter accepts three values: Learn for conceptual introductions, Build for hands-on implementation projects, and Reference for documentation-style resources. This classification helps learners identify the appropriate engagement level for each lesson.

How does the repository enforce the Lesson Contract?

The scripts/audit_lessons.py script automatically validates every lesson directory against the contract requirements, checking for mandatory metadata fields, proper quiz.json schema compliance, and correct file placement within the phases/*/*/ directory structure.

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