AI-Engineering-From-Scratch Project Structure: A Complete Guide to the Curriculum Architecture

The ai-engineering-from-scratch repository organizes 20 numbered phases of curriculum content into a self-contained "curriculum-as-code" architecture where each lesson contains standardized code/, docs/, and outputs/ subdirectories, supported by automation scripts, a static site generator, and CI/CD workflows.

The ai-engineering-from-scratch project by RohitG00 is a comprehensive open-source curriculum designed to teach AI engineering through hands-on implementation. Unlike traditional tutorials, this repository treats education as a software project, utilizing a rigid directory structure that separates learning materials from executable artifacts. The project structure emphasizes the "Build It / Use It / Ship It" philosophy defined in AGENTS.md, ensuring every lesson produces tangible, testable outputs.

The Core Curriculum: The phases/ Directory

The phases/ directory contains the meat of the curriculum, organized into 20 numbered phases (e.g., 00-setup-and-tooling, 01-math-foundations, 14-agent-engineering). According to the repository source code, each phase represents a logical progression in the AI engineering journey, from basic tooling to advanced agent engineering.

Within each phase, individual lessons follow a hierarchical naming convention: phases/<NN>-<phase-name>/<NN>-<lesson-name>/. This predictable structure allows automation scripts to traverse the curriculum programmatically. For example, the perceptron lesson resides at phases/03-deep-learning-core/01-the-perceptron/, while agent engineering content sits in phases/14-agent-engineering/.

Standardized Lesson Anatomy

Every lesson in the ai-engineering-from-scratch project structure follows a uniform three-part template that enforces consistency across the curriculum:

• code/ – Contains executable implementations, typically including a main.py entry point where learners build the concept from scratch.
• docs/ – Houses the narrative content, with en.md files explaining theory, learning objectives, and step-by-step instructions.
• outputs/ – Stores generated artifacts from the "Ship It" phase, including prompt templates, reusable skills, agent configurations, or MCP servers produced by the lesson.

This标准化 structure appears throughout the repository, from phases/01-math-foundations/01-linear-algebra-intuition/ to phases/14-agent-engineering/01-the-agent-loop/outputs/skill-agent-loop.md.

Documentation and Governance Files

The repository root contains several high-level metadata files that govern the curriculum and contributor workflow:

• README.md – Serves as the public front page, displaying the phase diagram, lesson counts, and quick-start instructions for clone-and-run workflows.
• AGENTS.md – Acts as the "operating manual" for contributors, defining hard rules such as "one commit per lesson," language allow-lists, and the repository layout philosophy.
• ROADMAP.md – Tracks the completion status of each phase and lesson (marking items as "WIP" or "Done"), which the CI pipeline uses to keep README statistics synchronized automatically.

Automation Scripts and Build Tools

The scripts/ Directory

The scripts/ directory contains utility programs that maintain curriculum integrity and automate repetitive tasks:

• lesson_run.py – The primary workhorse that walks the phases/ tree using iter_lesson_dirs to discover lessons. It compiles all Python files with py_compile for syntax checking and can optionally execute lesson entry points via the execute_lesson function.
• audit_lessons.py – Performs static analysis on lesson contents to enforce repository standards.
• build_catalog.py – Generates a machine-readable catalog consumed by the CI pipeline for status reporting.
• install_skills.py – Installs reusable .claude skills into the user's environment, enabling commands like /find-your-level.
• link_check.py – Detects dead links across the documentation.

The site/ Directory

The site/ directory contains a static-site generator that transforms the curriculum into a browsable web interface. The key file, site/build.js, parses README.md, ROADMAP.md, and the glossary to produce site/data.js, which feeds HTML templates, CSS, and JavaScript assets for visualizing phases and lessons. The generated site is committed by CI on every push to main.

Shared Resources and Top-Level Outputs

As implemented in rohitg00/ai-engineering-from-scratch, the repository maintains shared resources outside individual lessons:

• glossary/ – Contains canonical definitions in terms.md and myths.md that multiple lessons reference. The site generator ingests these to display inline definitions on the public website.
• outputs/ (top-level) – Stores shared artifacts not tied to a single lesson, such as outputs/prompts/ and outputs/skills/, populated by various lessons' "Ship It" steps.
• .github/workflows/curriculum.yml – The CI pipeline that runs audit_lessons.py, updates README lesson counts based on ROADMAP.md, and rebuilds the static site.

Practical Commands for Navigating the Structure

Run a Curriculum-Wide Syntax Check

Use lesson_run.py to verify all Python implementations compile without execution:

python scripts/lesson_run.py

This command uses py_compile to check every phases/**/code/*.py file and reports failures via the syntax_check function.

Execute a Specific Phase

To run the actual implementations for a specific phase (e.g., Phase 14 – Agent Engineering):

python scripts/lesson_run.py --phase 14 --execute

The --execute flag triggers the execute_lesson logic, which runs each lesson's entry file. The script automatically skips lessons declaring extra dependencies via # requires: comments in the source headers, preventing heavyweight imports from breaking the automated run.

Build the Static Site Locally

Generate the web interface from the curriculum data:

npm install
node site/build.js

This creates site/data.js and static HTML files that visualize the complete curriculum structure.

Install Reusable Claude Skills

Integrate the curriculum's custom skills into your Claude environment:

python scripts/install_skills.py

This copies .claude/skills/* folders into your local Claude configuration, making skills like /find-your-level available for interactive use.

Summary

The ai-engineering-from-scratch project structure implements a curriculum-as-code philosophy with these key architectural decisions:

• Modular Lesson Design – Every lesson follows a strict code/, docs/, outputs/ format, ensuring consistent navigation across all 20 phases.
• Automation-First – The scripts/ directory provides robust tooling for syntax checking (lesson_run.py), catalog generation, and skill installation.
• Documentation Hierarchy – Root-level files (AGENTS.md, ROADMAP.md, README.md) govern contribution rules, track progress, and serve learners.
• Integrated Publishing – The site/ generator and .github/workflows/curriculum.yml CI pipeline automatically transform the git repository into a browsable learning platform.
• Shared Knowledge Base – The glossary/ and top-level outputs/ directories centralize terminology and reusable artifacts across lessons.

Frequently Asked Questions

What is the standard structure of a lesson in ai-engineering-from-scratch?

Every lesson follows a three-directory template within phases/<NN>-<phase-name>/<NN>-<lesson-name>/. The code/ directory contains implementations like main.py, the docs/ directory contains narrative content such as en.md, and the outputs/ directory stores generated artifacts like prompts or agent skills. This uniform structure allows the lesson_run.py script to automatically discover and validate lessons across the entire curriculum.

How does the CI/CD system maintain curriculum quality?

The .github/workflows/curriculum.yml pipeline runs automatically on every push to main, executing audit_lessons.py for static analysis and lesson_run.py for syntax checking. It also synchronizes the README's lesson counts with the actual status tracked in ROADMAP.md and regenerates the static site via site/build.js, ensuring the published website always reflects the current repository state.

What is the purpose of the AGENTS.md file?

AGENTS.md serves as the contributor's "operating manual," defining the strict rules for repository interaction. It mandates requirements such as "one commit per lesson," specifies the allowed programming languages for implementations, and codifies the "Build It / Use It / Ship It" philosophy. This file ensures that all contributions maintain the project's pedagogical standards and structural consistency.

How can I run a specific phase of the curriculum locally?

Use the command python scripts/lesson_run.py --phase <number> --execute, replacing <number> with the target phase (e.g., 14 for Agent Engineering). The script identifies lessons using the iter_lesson_dirs function, compiles them for syntax errors, and executes entry points. Lessons with external dependencies marked by # requires: comments are automatically skipped to prevent environment-related failures.

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