How Lessons Are Documented in AI Engineering from Scratch: The 5-Component Structure

TLDR: The AI Engineering from Scratch curriculum enforces a strict, reproducible documentation standard where every lesson contains five mandatory components—metadata in docs/en.md, reference code in code/, unit tests in code/tests/, a structured quiz.json, and optional outputs/—all governed by the lesson contract defined in AGENTS.md.

The rohitg00/ai-engineering-from-scratch repository implements a self-documenting curriculum architecture that ensures every lesson is testable, reproducible, and pedagogically consistent. Each lesson lives within a phase directory (e.g., phases/01-foundations/05-linear-algebra/) and follows a rigid folder structure defined by the lesson contract in AGENTS.md. This system allows learners and contributors to understand, execute, and validate any lesson in isolation while maintaining coherence across the broader AI engineering roadmap.

The Five-Component Lesson Structure

Every lesson in the AI Engineering from Scratch curriculum is organized into five distinct components that separate intent from implementation and verification from assessment.

1. Lesson Metadata – docs/en.md

The docs/en.md file serves as the canonical source for lesson documentation and website rendering. This file contains front-matter metadata following the strict template defined in AGENTS.md, requiring specific fields:

• Title: The lesson headline
• Hook: Engagement statement
• Type: Classification (e.g., foundations, capstone)
• Languages: Supported programming languages
• Prerequisites: Required prior knowledge
• Time: Estimated completion duration
• Learning Objectives: Bullet list of measurable outcomes

For example, in phases/19-capstone-projects/01-terminal-native-coding-agent/docs/en.md, this metadata drives both the curriculum website and learner expectations.

2. Executable Code – code/

The code/ directory houses the reference implementation (main.<lang>) written from first principles, deliberately avoiding black-box library calls where possible. This directory contains the actual executable content that learners run to complete the lesson, with implementations provided in the languages specified in the lesson metadata.

3. Verification Suite – code/tests/

Each lesson ships with at least five unit tests located in code/tests/ to validate the reference implementation. These tests are executed using the language's standard runner, such as:

python3 -m unittest discover

The test suite ensures that implementations remain functional across different environments and provides immediate feedback to learners when their code deviates from expected behavior.

4. Assessment Framework – quiz.json

Every lesson includes a quiz.json file that follows a strict six-question schema:

• 1 pre-check question
• 3 check-stage questions
• 2 post-check questions

This structured quiz drives learner self-assessment and integrates with the curriculum CI pipeline to enforce comprehension before progression.

5. Reusable Artifacts – outputs/

When lessons produce reusable artifacts—such as prompt templates, skill files, or model checkpoints—these are placed in the optional outputs/ directory. This separation ensures that generated assets remain accessible for downstream lessons without cluttering the source code.

The Lesson Contract in AGENTS.md

The AGENTS.md file at the repository root defines the lesson contract that binds all components together. This contract enforces consistency across the entire curriculum, specifying:

• The required directory structure
• Front-matter schema validation rules
• Testing requirements (minimum five unit tests)
• Quiz schema constraints

By adhering to this contract, contributors can scaffold new lessons that integrate seamlessly into the existing AI Engineering from Scratch learning path.

Minimal Lesson Scaffold

Below is the standard directory structure for a new lesson in the curriculum:

phases/XX-phase-slug/YY-new-lesson/
├─ docs/
│  └─ en.md                 # front-matter + narrative content

├─ code/
│  ├─ main.py               # reference implementation

│  └─ tests/
│     └─ test_main.py       # ≥5 unit tests

├─ quiz.json                # 6-question assessment

└─ outputs/                 # optional reusable artifacts

Summary

• Every lesson in rohitg00/ai-engineering-from-scratch follows a rigid five-component structure: docs/en.md, code/, code/tests/, quiz.json, and optional outputs/.
• The AGENTS.md file defines the lesson contract that enforces metadata schema, testing requirements, and directory conventions.
• Lessons must include at least five unit tests in code/tests/ to verify implementations.
• The quiz.json file follows a strict six-question format (1 pre-check, 3 check-stage, 2 post-check) for assessment.
• This architecture makes the curriculum self-documenting, testable, and extensible for both learners and contributors.

Frequently Asked Questions

What metadata fields are required in the docs/en.md front-matter?

According to the AGENTS.md specification, the docs/en.md file must include Title, Hook, Type, Languages, Prerequisites, Time, and a Learning Objectives list. These fields populate the curriculum website and establish clear expectations for learners before they begin the lesson.

How many unit tests must each lesson include?

The lesson contract requires at least five unit tests in the code/tests/ directory. These tests validate the reference implementation and are executed by the language's standard test runner, ensuring that the lesson code remains functional across different environments and use cases.

What is the structure of the quiz.json assessment file?

The quiz.json file follows a strict six-question schema consisting of 1 pre-check question, 3 check-stage questions, and 2 post-check questions. This structure enforces learner comprehension at specific milestones and integrates with the curriculum's CI pipeline to validate understanding.

Where are lesson outputs and artifacts stored?

Reusable artifacts generated during a lesson—such as prompt templates, skill files, or model checkpoints—are stored in the optional outputs/ directory. This separation keeps generated assets organized and accessible for downstream lessons while maintaining a clean separation from source code and documentation.

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