The Complete Lesson Directory Contract Structure in AI Engineering from Scratch

Every lesson directory in the rohitg00/ai-engineering-from-scratch repository follows a strict four-part contract defined in AGENTS.md, requiring standardized documentation in docs/en.md, runnable code with tests in code/, a six-question assessment in 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 (lines 68-92), every lesson directory must implement four mandatory components to maintain curriculum integrity.

Documentation Front-Matter (docs/en.md)

Each lesson must include a 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.

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

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

Every lesson must provide a 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.

{
  "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 must never be committed directly to the repository (lines 44-53 of AGENTS.md).

Validation and Compliance

The 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), Implementation (code/), Assessment (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 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 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 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.

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