AI Engineering from Scratch Lesson Anatomy: The Complete Repository Structure

Every lesson in the repository follows a strict, self-contained folder structure governed by AGENTS.md and LESSON_TEMPLATE.md, ensuring reproducible builds, automated testing, and consistent knowledge transfer across documentation, code, and assessments.

The rohitg00/ai-engineering-from-scratch curriculum treats each concept as a deployable unit. Understanding the lesson anatomy is essential for contributors building new material and learners navigating the codebase. Each lesson functions as an isolated package containing narrative documentation, from-scratch implementations, deterministic tests, reusable AI artefacts, and a standardized six-question assessment.

The Seven Core Components of Every Lesson

The repository enforces a uniform directory tree. Every lesson resides at phases/<phase-slug>/<lesson-slug>/ and must contain the following artefacts to satisfy the lesson contract.

Documentation Layer (docs/en.md)

Human-readable pedagogy lives in docs/en.md. This file must begin with YAML frontmatter strictly defined in AGENTS.md:

---
title: "Linear Regression from Scratch"
type: Build
languages: ["Python", "TypeScript"]
prerequisites: []
time: "~20 minutes"
---

The body follows with learning objectives, narrative walkthroughs, and mathematical explanations. The type field classifies the lesson as Build, Theory, or Integration, determining how the static site generator processes the content.

Implementation Layer (code/main.* and code/tests/)

The executable core sits in the code/ directory. A header comment must cite the canonical documentation path:

# main.py – implementation for “Linear Regression from Scratch”

# Docs: https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/01-foundations/01-linear-regression/docs/en.md

def predict(x, w, b):
    """Return w·x + b."""
    return w * x + b

def train(xs, ys, lr=0.01, epochs=1000):
    """Simple gradient-descent trainer for a single-dimensional line."""
    w, b = 0.0, 0.0
    n = len(xs)
    for _ in range(epochs):
        dw = sum((predict(x, w, b) - y) * x for x, y in zip(xs, ys)) / n
        db = sum(predict(x, w, b) - y for x, y in zip(xs, ys)) / n
        w -= lr * dw
        b -= lr * db
    return w, b

Test requirements mandate five or more deterministic unit tests in code/tests/:

import unittest
from main import predict, train

class TestLinearRegression(unittest.TestCase):
    def test_predict(self):
        self.assertAlmostEqual(predict(2, 3, 1), 7)

    def test_train_convergence(self):
        xs = [0, 1, 2]
        ys = [1, 3, 5]  # y = 2x + 1

        w, b = train(xs, ys, lr=0.1, epochs=500)
        self.assertAlmostEqual(w, 2, places=1)
        self.assertAlmostEqual(b, 1, places=1)

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

Run these with the language’s standard runner (e.g., python3 -m unittest discover).

Artefact Layer (outputs/)

Reusable AI components—prompts, skills, agents, and MCP servers—ship as markdown files in outputs/. Each file follows the frontmatter schema from LESSON_TEMPLATE.md, enabling other lessons or external systems to import them programmatically.

Assessment Layer (quiz.json)

Comprehension is validated via quiz.json, which must contain exactly six questions: one pre-assessment, three checkpoint questions, and two post-assessment items. The schema requires zero-indexed correct fields:

{
  "lesson": "01-linear-regression",
  "title": "Linear Regression from Scratch",
  "questions": [
    {
      "stage": "pre",
      "question": "What does linear regression aim to model?",
      "options": [
        "A non-linear curve",
        "A straight line",
        "A probability distribution",
        "A decision tree"
      ],
      "correct": 1,
      "explanation": "Linear regression models the linear relationship between variables."
    },
    {
      "stage": "check",
      "question": "Which term controls the step size in gradient descent?",
      "options": ["bias", "learning rate", "epoch count", "feature scaling"],
      "correct": 1,
      "explanation": "The learning rate scales the gradient update."
    }
  ]
}

Optional Extensions (notebook/)

Data-science and experimentation-heavy topics may include a Jupyter notebook at notebook/lesson.ipynb. While not mandatory, notebooks provide interactive exploration layers atop the deterministic main.* implementation.

The Blueprint Files That Govern Structure

Two canonical documents enforce the lesson anatomy across the repository.

AGENTS.md — The Lesson Contract

Located at the repository root, [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specifies the exact frontmatter keys required in docs/en.md (title, type, languages, prerequisites, time) and the JSON schema for quiz.json. It acts as the single source of truth for validation scripts that gate pull requests.

LESSON_TEMPLATE.md — The Folder Blueprint

[LESSON_TEMPLATE.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md) provides the directory skeleton and markdown templates for output artefacts. Contributors copy this template when scaffolding new lessons, ensuring that phases/02-neural-nets/03-backpropagation follows identical structural rules to phases/01-foundations/01-linear-regression.

Real-World Example: Linear Regression

Applying the lesson anatomy to the first foundations phase produces the following tree:

phases/01-foundations/01-linear-regression/
├── code/
│   ├── main.py
│   └── tests/
│       └── test_main.py
├── docs/
│   └── en.md
├── outputs/
│   ├── prompt-linear-regression.md
│   └── skill-linear-regression.md
├── notebook/
│   └── lesson.ipynb
└── quiz.json

This structure satisfies all automation in the repository: the static site generator parses docs/en.md, CI runs code/tests/, and the assessment platform ingests quiz.json without manual configuration.

Summary

• Every lesson is a self-contained directory under phases/<phase>/<lesson>/ following the blueprint in LESSON_TEMPLATE.md.
• Documentation mandates frontmatter (title, type, languages, prerequisites, time) as specified in AGENTS.md.
• Code must include a main.* implementation with header comments linking to docs, plus five or more deterministic tests in code/tests/.
• Reusable AI artefacts (prompts, skills, agents) ship as markdown in outputs/ with structured frontmatter.
• Assessment requires a quiz.json with exactly six questions (1 pre, 3 check, 2 post) using zero-indexed correct answers.
• Validation relies on AGENTS.md as the lesson contract and ROADMAP.md for tracking completion status.

Frequently Asked Questions

What is the required folder structure for a lesson?

Each lesson must reside at phases/<phase-slug>/<lesson-slug>/ and contain docs/en.md, code/main.*, code/tests/, outputs/, and quiz.json. The LESSON_TEMPLATE.md file provides the exact skeleton, while optional notebook/ directories support interactive experimentation.

How does the quiz.json file need to be formatted?

The file must contain exactly six questions following the schema in AGENTS.md: one pre-assessment question, three checkpoint questions, and two post-assessment questions. Each question object requires stage, question, options (array), correct (zero-indexed integer), and explanation fields.

Where are reusable AI artefacts stored within a lesson?

Prompts, skills, agents, and MCP servers live in the outputs/ directory as individual markdown files. These files include YAML frontmatter defining their type and metadata, allowing other lessons or external systems to import them programmatically.

What validates that a lesson follows the correct anatomy?

AGENTS.md serves as the lesson contract, defining the required frontmatter for documentation and the JSON schema for quizzes. Automated tooling in the repository validates pull requests against this contract, ensuring every new lesson maintains the structural integrity required by the curriculum generator and testing pipelines.

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