How the AI Engineering from Scratch Curriculum Structures Its Lessons: A Complete Guide

The AI Engineering from Scratch curriculum organizes content into sequentially numbered phases containing self-contained lessons, each with mandatory documentation, reference implementations, unit tests, and quizzes, enforced by automated CI pipelines.

The rohitg00/ai-engineering-from-scratch repository structures its educational content through a rigid, modular architecture defined in AGENTS.md. This design ensures every lesson in the AI Engineering from Scratch curriculum functions as a reproducible, self-contained learning unit with standardized components and strict quality controls.

Repository-Wide Layout and Conventions

The curriculum follows a strict hierarchical structure centered on phases and lessons. According to the AGENTS.md source file, the repository enforces specific organizational rules that guarantee consistency across all learning materials.

Directory Hierarchy

All content lives under the phases/ directory, following a predictable pattern:

phases/
  NN-phase-slug/
    NN-lesson-slug/
      docs/
        en.md                # lesson description & objectives

      code/
        main.<lang>          # reference implementation

        tests/
          test_main.*        # unit tests

      outputs/               # optional reusable artifacts

      quiz.json              # 6-question assessment

Each phase uses sequential numbering (for example, 01-foundations, 19-capstone-projects), with lessons numbered within their parent phase (such as 01-linear-algebra, 02-gradient-descent). The glossary/terms.md file provides shared terminology across all lessons.

Version Control Standards

The AI Engineering from Scratch curriculum enforces strict git hygiene through two policies:

• One commit per lesson: Every lesson addition or modification is isolated to a single atomic commit
• Conventional commit messages: Follow the format feat(phase-05/03): add attention-mechanism

Additionally, every fenced code block must include a language tag, and the quiz.json schema requires exactly six questions.

The Lesson Contract

Every lesson directory must contain five mandatory components validated by CI jobs in .github/workflows/curriculum.yml. The audit_lessons.py script enforces this contract before any pull request can merge.

Documentation Standards

The docs/en.md file must include front-matter specifying:

• Title and hook
• Lesson type and supported languages
• Prerequisites and estimated completion time
• Specific learning objectives

Reference Implementation

The code/main.<lang> file contains a minimal working implementation (typically 4-6 lines) preceded by a header comment citing the lesson's documentation path and any external specifications.

Testing Requirements

The code/tests/ directory must contain at least five deterministic unit tests runnable via standard language commands. For Python lessons, use python3 -m unittest discover; for TypeScript, use npx tsx --test.

Assessment Structure

The quiz.json file follows a fixed schema requiring exactly six questions categorized as pre-assessment, check-in, or post-assessment.

Optional Artifacts

Lessons may include an outputs/ directory containing reusable artifacts such as skill markdown files, prompts, or agent definitions.

Curriculum Flow and Tracking

The curriculum progression is managed through specific governance files that track completion status and generate public documentation.

Status Tracking with ROADMAP.md

The ROADMAP.md file maintains a phase/lesson status matrix using symbols like ✅ for complete and 🚧 for work-in-progress, providing at-a-glance visibility into curriculum development status.

Automated Website Generation

The site/build.js generator parses markdown links in README.md to construct the public lesson catalog. Missing links trigger build failures, ensuring every lesson remains discoverable and properly indexed.

Dependency and Philosophy Constraints

The curriculum maintains a strict dependency policy aligned with its "build-it-use-it" philosophy. Only a curated allowlist of third-party packages (such as numpy and torch for Python) is permitted. All other functionality must be implemented from scratch, reinforcing fundamental understanding of AI engineering principles.

Example Lesson Structure

Below is the concrete directory structure for a matrix multiplication lesson in phase 3:

phases/03-math-basics/01-matrix-multiplication/
├─ docs/
│  └─ en.md               # front-matter + description

├─ code/
│  ├─ main.py             # 4-6 line implementation

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

├─ outputs/
│  └─ skill-matrix-mul.md # optional reusable skill

└─ quiz.json              # 6-question quiz

The reference implementation in main.py includes a mandatory header comment:

# Lesson: Matrix Multiplication (phases/03-math-basics/01-matrix-multiplication/docs/en.md)

Tests execute via standard runners:

python3 -m unittest discover -s code/tests -v

Summary

• The AI Engineering from Scratch curriculum organizes content into sequentially numbered phases containing self-contained lessons
• Each lesson follows a strict contract requiring docs/en.md, code/main.<lang>, minimum five unit tests in code/tests/, and a six-question quiz.json
• The AGENTS.md file governs repository-wide conventions including directory structure, file naming, and commit message formats
• CI pipelines in .github/workflows/curriculum.yml validate all lessons via audit_lessons.py before merge
• The ROADMAP.md matrix tracks lesson status while site/build.js ensures public discoverability through README.md link validation

Frequently Asked Questions

What files are required in every lesson directory?

Every lesson must contain docs/en.md for documentation, code/main.<lang> for the reference implementation, code/tests/test_main.* with at least five unit tests, and quiz.json with exactly six questions. An optional outputs/ directory may contain additional artifacts like skill definitions or prompt templates.

How does the curriculum enforce quality standards?

The repository uses automated CI jobs defined in .github/workflows/curriculum.yml that run audit_lessons.py to validate the lesson contract. Additionally, the site/build.js generator fails builds if README.md links are missing, ensuring all lessons are properly cataloged and accessible.

What is the dependency policy for implementations?

Only a curated allowlist including packages like numpy and torch is permitted. All other functionality must be built from scratch according to the AGENTS.md specifications, reinforcing the curriculum's foundational learning approach and "build-it-use-it" philosophy.

How are lessons numbered and organized?

Lessons reside within numbered phases (e.g., 01-foundations) and are sequentially numbered within their phase (e.g., 01-linear-algebra). The ROADMAP.md file tracks completion status using emoji indicators for quick visual reference across the entire curriculum.

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