Repository Structure of AI Engineering from Scratch: A Complete Guide to the 20-Phase Curriculum

The AI Engineering from Scratch repository organizes 511 lessons into 20 sequential phases under the phases/ directory, with each lesson containing standardized code/, docs/, and outputs/ subdirectories, alongside automation scripts in scripts/ and generated artifacts in outputs/.

The rohitg00/ai-engineering-from-scratch repository functions as a self-contained, executable curriculum for learning AI engineering fundamentals. Its hierarchical structure separates educational content from build automation, website assets, and reusable AI components, enabling both human learners and AI agents to navigate the codebase programmatically.

Top-Level Directory Layout

The repository root contains high-level documentation and organizational directories that govern the entire curriculum. According to the source code, these entry points provide the primary navigation mechanism for the 511 lessons spanning 20 phases.

Critical path files define the curriculum metadata:

• README.md — Landing page containing project overview, badge shields, and the quick-start table indexing all phases
• ROADMAP.md — Tracks phase-by-phase completion status for all 511 lessons with WIP/Done flags
• AGENTS.md — Operating manual specifying contribution rules, repository philosophy, and commit conventions for both human contributors and AI agents
• languages.json — Maps programming languages to file extensions, enabling the polyglot lesson structure (Python, TypeScript, Rust, Julia)

Infrastructure directories handle automation and delivery:

• phases/ — Core curriculum containing 20 numbered phases (00 through 19) ranging from Phase 0 — Setup & Tooling to Phase 19 — Capstone Projects
• scripts/ — Automation utilities including audit_lessons.py for CI-run validation of lesson integrity
• site/ — Static website source used to build the public documentation site, containing build.js which generates site/data.js
• certifications/ — Claude-style certification tracks with diagnostic JSON and per-lesson assessment assets
• glossary/ — Centralized terminology definitions in terms.md referenced across all lessons
• outputs/ — Generated reusable artifacts organized into prompts/, skills/, agents/, and mcp-servers/ subdirectories
• learning-paths/ — JSON manifests (e.g., model-context-protocol.json, agent-skills.json) describing specialized learning routes

The Core Curriculum: Understanding the phases/ Directory

The phases/ directory implements a strict hierarchical convention that ensures consistent lesson discoverability. Each phase follows the naming pattern phases/<NN>-<phase-name>/, where <NN> is a zero-padded two-digit number (00-19).

Phase 0 covers setup and tooling fundamentals, while Phase 19 contains capstone projects requiring integration of all prior concepts. Between these endpoints, phases progress through mathematical foundations, neural network architectures, optimization techniques, and deployment strategies.

Standard Lesson Structure

Every lesson within a phase adheres to a uniform three-directory layout defined in the repository's architectural specification:

phases/<NN>-<phase-name>/<NN>-<lesson-name>/
├── code/      # Runnable implementations (Python, TypeScript, Rust, Julia)

├── docs/
│   └── en.md  # Lesson narrative and explanations in English

└── outputs/   # Produced prompts, skills, agents, or MCP servers

The code/ subdirectory contains executable source files demonstrating the concept. The docs/en.md file provides the pedagogical narrative. The outputs/ subdirectory stores artifacts generated by completing the lesson, such as reusable prompts or Model Context Protocol (MCP) server configurations.

This standardization enables automated tooling to programmatically discover, validate, and execute any lesson without hardcoding paths.

Supporting Infrastructure and Automation

Beyond the curriculum content, the repository contains specialized directories for build processes and artifact management.

The scripts/ directory houses CI utilities. The file scripts/audit_lessons.py runs continuous integration checks to verify lesson integrity, ensuring that every lesson directory contains the required code/, docs/, and outputs/ subdirectories and that referenced files are executable.

The site/ directory contains the static site generator. The Node.js script site/build.js processes the phase structure to generate site/data.js, which powers the searchable curriculum interface on the public documentation website.

The outputs/ directory at the repository root serves as a registry for reusable AI components. Unlike the per-lesson outputs/ folders (which contain lesson-specific artifacts), this top-level directory aggregates cross-cutting artifacts:

• outputs/prompts/ — Reusable system prompts derived from multiple lessons
• outputs/skills/ — Codex-compatible skill definitions installable via npx skills add
• outputs/agents/ — Pre-configured agent templates
• outputs/mcp-servers/ — Model Context Protocol server implementations
• outputs/index.json — Machine-readable index of all generated artifacts

Practical Navigation Examples

The consistent structure enables straightforward command-line interaction with the curriculum. Below are common entry points for learners and automation systems.

Clone the repository and execute a foundational linear algebra lesson:

git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
python3 phases/01-math-foundations/01-linear-algebra-intuition/code/vectors.py

Install curriculum-wide skills for a Codex-compatible host and launch the interactive tutor:

npx skills add rohitg00/ai-engineering-from-scratch
start-learning

Run the pre-flight checker for the beginner environment setup lesson:

python3 phases/00-setup-and-tooling/01-dev-environment/code/verify.py --route beginner

Key Configuration and Entry Points

Several files serve as critical junction points for tooling and automation:

• scripts/audit_lessons.py — Validates lesson structure compliance across all 511 lessons, checking for missing docs/en.md files or empty code/ directories
• site/build.js — Generates the curriculum data file consumed by the frontend, parsing all phases/ subdirectories to create the navigation tree
• glossary/terms.md — Provides canonical definitions for technical terms used across lessons, ensuring consistent terminology
• outputs/index.json — Machine-readable manifest of all artifacts in outputs/, enabling programmatic discovery of reusable prompts and skills
• certifications/claude/ — Contains track manifests and diagnostic JSON for alternative certification pathways overlaying the core curriculum

Summary

• The AI Engineering from Scratch repository organizes 511 lessons into 20 sequential phases (00-19) under the phases/ directory.
• Each lesson follows a strict three-part structure: code/ (implementations), docs/en.md (narrative), and outputs/ (generated artifacts).
• Top-level metadata files (README.md, ROADMAP.md, AGENTS.md) provide curriculum overview, completion tracking, and contribution guidelines.
• The scripts/ directory contains CI validators like audit_lessons.py that enforce structural integrity across all lessons.
• Reusable AI components aggregate in the outputs/ directory, indexed by outputs/index.json for programmatic access.
• languages.json and learning-paths/ enable polyglot lesson execution and specialized curriculum routes like Model Context Protocol mastery.

Frequently Asked Questions

How many phases are in the AI Engineering from Scratch curriculum?

The repository contains 20 phases numbered 00 through 19, starting with Phase 0 (Setup & Tooling) and culminating in Phase 19 (Capstone Projects). The ROADMAP.md file tracks completion status across all 511 lessons distributed among these phases.

Where are the lesson instructions and code located?

Lesson instructions reside in phases/<NN>-<phase-name>/<NN>-<lesson-name>/docs/en.md, while runnable code lives in the sibling code/ directory. This standardized path structure allows automation scripts to programmatically pair documentation with implementations across all supported languages (Python, TypeScript, Rust, Julia).

What is the purpose of the outputs/ directory?

The outputs/ directory stores generated artifacts including reusable prompts, skills, agents, and MCP servers. Each lesson contains a local outputs/ folder for lesson-specific results, while the repository root outputs/ directory aggregates cross-cutting artifacts and maintains index.json for machine-readable discovery.

How does the repository support AI agent contributions?

The AGENTS.md file serves as the operating manual for AI agents and human contributors, specifying commit conventions, repository philosophy, and validation requirements. Additionally, the scripts/audit_lessons.py utility automatically enforces these structural standards during CI runs, ensuring agent-generated content maintains curriculum consistency.

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