# How AI Engineering Curriculum Lessons Are Organized with Code, Docs, and Outputs Directories

> Discover how this AI engineering curriculum organizes lessons using docs, code, and outputs directories for a streamlined Learn Build Reference workflow. Explore the rohitg00/ai-engineering-from-scratch repository structure.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-07-31

---

**The repository structures every lesson under `phases/<phase-slug>/<lesson-slug>/` with three mandatory subdirectories—`docs/` for explanations, `code/` for implementations, and `outputs/` for reusable artifacts—enabling a consistent Learn → Build → Reference workflow across the entire curriculum.**

The `rohitg00/ai-engineering-from-scratch` repository implements a rigorous lesson-centric layout that standardizes how educational content is packaged, tested, and reused. Each lesson follows a strict three-directory contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), ensuring that automated tooling can discover, validate, and publish curriculum modules without manual metadata entry.

## The Three-Pillar Directory Structure

Every lesson resides at `phases/<phase-slug>/<lesson-slug>/` and must contain three core subdirectories. This convention applies universally, from foundational tutorials to advanced capstone projects.

### docs/ Directory

The `docs/` subdirectory holds the human-readable lesson explainer in [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md). This file uses frontmatter to declare machine-readable metadata including the **lesson type**, **programming language**, **prerequisites**, and **estimated completion time**.

For example, in [`phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md), the frontmatter defines the lesson as a capstone project while the body content explains the safety gate concept and learning objectives.

### code/ Directory

The `code/` subdirectory contains the minimal, self-contained implementation and test suite. Files follow the naming convention `main.<lang>` (e.g., [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.js)) and include a header comment citing the corresponding lesson documentation.

A `tests/` subdirectory accompanies the implementation to validate correctness. According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification, all code must run directly without external configuration—executing `python3 main.py` from within the directory must terminate cleanly. The capstone example at [`phases/19-capstone-projects/87-end-to-end-safety-gate/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/87-end-to-end-safety-gate/code/main.py) demonstrates this pattern with a runnable safety gate demonstration.

### outputs/ Directory

The `outputs/` subdirectory stores the lesson's reusable artifact—categorized as a **skill**, **prompt**, **agent**, or **MCP server**—formatted as Markdown or JSON. These artifacts serve as importable references for downstream lessons, enabling the curriculum to build upon previous work incrementally.

For instance, [`phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/87-end-to-end-safety-gate/outputs/skill-end-to-end-safety-gate.md) publishes the safety gate skill in a standardized format that subsequent lessons can import and extend.

## The Learn → Build → Reference Cycle

The three directories collectively enforce a pedagogical workflow that progresses from theory to practice to reusable asset:

1. **Learn** – Students read [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) to understand concepts and objectives.
2. **Build** – Students implement or run the `code/` to see concepts in action.
3. **Reference** – The system publishes `outputs/` artifacts that other lessons import, creating a dependency chain of reusable AI components.

This cycle ensures that every lesson produces tangible, referenceable assets rather than disposable exercises.

## Programmatically Discovering Lessons

Because the structure is strictly enforced, you can enumerate all lessons programmatically by checking for the mandatory [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file:

```python
from pathlib import Path

root = Path("phases")
for lesson_path in root.rglob("*/*"):
    if (lesson_path / "docs" / "en.md").exists():
        print(f"Lesson: {lesson_path}")
        print(f"  • Docs   : {lesson_path / 'docs' / 'en.md'}")
        print(f"  • Code   : {list((lesson_path / 'code').glob('main.*'))}")
        print(f"  • Outputs: {list((lesson_path / 'outputs').glob('*'))}")

```

This pattern enables automated CI pipelines to validate that every lesson contains its required components and that all code executes successfully.

## Executing and Importing Lesson Components

To run a lesson's demonstration locally, navigate to its `code/` directory and execute the main file:

```bash
cd phases/19-capstone-projects/87-end-to-end-safety-gate/code
python3 main.py   # Executes the safety‑gate demo and writes outputs/gate_trace.json

```

Downstream lessons can import artifacts from previous lessons by reading the Markdown or JSON files from the `outputs/` directory:

```python
from pathlib import Path

skill_path = Path(__file__).parents[2] / "87-end-to-end-safety-gate" / "outputs" / "skill-end-to-end-safety-gate.md"
skill_md = skill_path.read_text()

# `skill_md` can now be used as documentation or parsed for configuration data.

```

## Summary

- **Standardized Paths**: Every lesson follows `phases/<phase-slug>/<lesson-slug>/` with mandatory `docs/`, `code/`, and `outputs/` subdirectories.
- **Self-Documenting**: The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file combines human-readable explanations with YAML frontmatter for machine parsing.
- **Runnable Code**: The `code/` directory contains executable implementations and tests that run without external dependencies.
- **Reusable Artifacts**: The `outputs/` directory publishes skills, prompts, agents, or MCP servers that downstream lessons can import.
- **Contract-Driven**: The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file formally defines this structure, enabling automated testing and site generation across the entire `rohitg00/ai-engineering-from-scratch` curriculum.

## Frequently Asked Questions

### What file defines the metadata for each lesson?

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file contains YAML frontmatter that specifies the lesson type, programming language, prerequisites, and estimated duration. This metadata enables automated tooling to categorize and filter lessons without parsing unstructured text.

### Can lesson code be executed independently of the curriculum platform?

Yes. According to the repository contract defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), code in the `code/` directory must be self-contained and runnable directly. Executing `python3 main.py` from within the lesson's `code/` directory performs the demonstration and exits cleanly without requiring external configuration.

### What types of artifacts are stored in the outputs/ directory?

The `outputs/` directory contains reusable AI components formatted as Markdown or JSON, specifically categorized as **skills**, **prompts**, **agents**, or **MCP servers**. These artifacts function as importable libraries that subsequent lessons in the curriculum can reference and extend.

### How does the curriculum enforce consistency across hundreds of lessons?

The repository relies on a strict directory contract documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). Automated scripts and CI pipelines validate that every lesson directory contains the required `docs/`, `code/`, and `outputs/` subdirectories with properly formatted content, preventing structural drift as the curriculum scales.