# AI-Engineering-From-Scratch Project Structure: A Complete Guide to the Curriculum Architecture > Explore the ai-engineering-from-scratch project structure featuring a curriculum-as-code architecture with standardized directories, automation, and CI/CD for seamless learning. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: architecture - Published: 2026-06-19 --- **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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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/-/-/`. 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) entry point where learners build the concept from scratch. - **`docs/`** – Houses the narrative content, with [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py)** – Performs static analysis on lesson contents to enforce repository standards. - **[`build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/build_catalog.py)** – Generates a machine-readable catalog consumed by the CI pipeline for status reporting. - **[`install_skills.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/install_skills.py)** – Installs reusable `.claude` skills into the user's environment, enabling commands like `/find-your-level`. - **[`link_check.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), parses [`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), and the glossary to produce [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/terms.md) and [`myths.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml)** – The CI pipeline that runs [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py), updates README lesson counts based on [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), and rebuilds the static site. ## Practical Commands for Navigating the Structure ### Run a Curriculum-Wide Syntax Check Use [`lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/lesson_run.py) to verify all Python implementations compile without execution: ```bash 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): ```bash 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: ```bash npm install node site/build.js ``` This creates [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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: ```bash 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/lesson_run.py)), catalog generation, and skill installation. - **Documentation Hierarchy** – Root-level files ([`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md), [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)) govern contribution rules, track progress, and serve learners. - **Integrated Publishing** – The `site/` generator and [`.github/workflows/curriculum.yml`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.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/-/-/`. The `code/` directory contains implementations like [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), the `docs/` directory contains narrative content such as [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md), and the `outputs/` directory stores generated artifacts like prompts or agent skills. This uniform structure allows the [`lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/.github/workflows/curriculum.yml) pipeline runs automatically on every push to `main`, executing [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) for static analysis and [`lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/lesson_run.py) for syntax checking. It also synchronizes the README's lesson counts with the actual status tracked in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) and regenerates the static site via [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), ensuring the published website always reflects the current repository state. ### What is the purpose of the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file? [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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 --execute`, replacing `` 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.