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

> Explore the AI Engineering from Scratch repository structure. Discover how 511 lessons are organized into 20 phases, with standardized code, docs, and outputs for efficient learning.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** — Landing page containing project overview, badge shields, and the quick-start table indexing all phases
- **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** — Tracks phase-by-phase completion status for all 511 lessons with WIP/Done flags
- **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** — Operating manual specifying contribution rules, repository philosophy, and commit conventions for both human contributors and AI agents
- **[`languages.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) for CI-run validation of lesson integrity
- **`site/`** — Static website source used to build the public documentation site, containing [`build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/build.js) which generates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js)
- **`certifications/`** — Claude-style certification tracks with diagnostic JSON and per-lesson assessment assets
- **`glossary/`** — Centralized terminology definitions in [`terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/model-context-protocol.json), [`agent-skills.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) processes the phase structure to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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:

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

```

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

```bash
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** — Validates lesson structure compliance across all 511 lessons, checking for missing [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) files or empty `code/` directories
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** — Generates the curriculum data file consumed by the frontend, parsing all `phases/` subdirectories to create the navigation tree
- **[`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md)** — Provides canonical definitions for technical terms used across lessons, ensuring consistent terminology
- **[`outputs/index.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** (narrative), and **`outputs/`** (generated artifacts).
- **Top-level metadata files** ([`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)) provide curriculum overview, completion tracking, and contribution guidelines.
- The **`scripts/`** directory contains CI validators like [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) that enforce structural integrity across all lessons.
- Reusable AI components aggregate in the **`outputs/`** directory, indexed by [`outputs/index.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/index.json) for programmatic access.
- **[`languages.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/index.json) for machine-readable discovery.

### How does the repository support AI agent contributions?

The **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** utility automatically enforces these structural standards during CI runs, ensuring agent-generated content maintains curriculum consistency.