# Recommended Lesson Folder Structure and File Organization Pattern in AI Engineering from Scratch

> Learn the recommended AI engineering lesson folder structure and file organization for rohitg00/ai-engineering-from-scratch. Discover how we ensure automated validation and site generation.

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

---

**Each lesson in the AI Engineering from Scratch repository follows a strict curriculum-first layout under `phases/<phase-number>-<slug>/<lesson-number>-<slug>/`, containing mandatory [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/` with tests, [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json), and `outputs/` directories to ensure automated validation and seamless site generation.**

The `rohitg00/ai-engineering-from-scratch` repository houses **435 lessons** distributed across **20 learning phases**. To maintain consistency at scale, the project enforces a specific **lesson folder structure and file organization pattern** documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and validated by CI checks. This architecture ensures every lesson remains isolated, versionable, and automatically discoverable by build scripts.

## The Canonical Directory Hierarchy

The repository root contains phase directories that segment the curriculum into logical milestones. Each phase directory holds individual lesson folders following a strict naming convention.

### Phase and Lesson Naming Convention

Lessons reside under `phases/<phase-number>-<phase-slug>/<lesson-number>-<lesson-slug>/`. For example, `phases/19-capstone-projects/87-end-to-end-safety-gate/` follows the strict numbering scheme required by the automation scripts in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py). This hierarchical path allows the curriculum to scale while maintaining logical groupings.

### Mandatory Subdirectories and Files

Each lesson directory must contain exactly these components:

- **[`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** – The lesson explainer with YAML front-matter defining metadata
- **`code/`** – Implementation directory containing the main source file and test subdirectory
- **`code/tests/`** – Unit test suite with a minimum of five test cases
- **[`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)** – Structured assessment file containing exactly six questions
- **`outputs/`** – Storage for reusable artifacts produced by the lesson (skills, prompts, or MCP servers)

## File Content Specifications

Beyond physical presence, files must adhere to strict content schemas defined in the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).

### Front-Matter Requirements in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)

The documentation file must include a `**Languages:**` field in its front-matter that exactly matches the programming languages used in the `code/` directory. Supported languages include **Python**, **TypeScript**, **Rust**, and **Julia**. The front-matter also declares prerequisites, estimated time, and learning objectives.

### Header Comment Standards in `code/main.<lang>`

Every implementation file must begin with a header comment citing the lesson title and the path to its documentation. For example, in [`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):

```python

# Lesson: End-to-End Safety Gate

# Docs: phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md

```

### Quiz Schema in [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must follow a fixed schema containing exactly six questions: one pre-assessment, three checkpoint questions, and two post-assessment questions. Each question object requires `stage`, `question`, `options`, `correct` index, and `explanation` fields.

## Automated Validation and Site Generation

The repository leverages [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) to enforce structural compliance during CI. This script validates front-matter consistency, ensures test directory presence, and verifies quiz schema adherence. Additionally, [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) consumes this standardized layout to generate the public-facing curriculum site without manual intervention.

## Creating a New Lesson Skeleton

To scaffold a compliant lesson, execute these shell commands replacing `NN`, `MM`, and slugs with appropriate identifiers:

```bash
mkdir -p phases/NN-phase-slug/MM-new-lesson/{docs,code/tests,outputs}

cat > phases/NN-phase-slug/MM-new-lesson/docs/en.md <<EOF

# <Lesson Title>

> <One-line hook>

**Type:** Build
**Languages:** python
**Prerequisites:** None
**Time:** ~30

## Learning Objectives

- Implement core functionality
- Validate with unit tests
EOF

```

```bash
cat > phases/NN-phase-slug/MM-new-lesson/code/main.py <<'PY'

# Lesson: <Lesson Title>

# Docs: phases/NN-phase-slug/MM-new-lesson/docs/en.md

def hello():
    return "Hello, world!"
PY

```

```bash
cat > phases/NN-phase-slug/MM-new-lesson/code/tests/test_main.py <<'PY'
import unittest
from ..main import hello

class TestHello(unittest.TestCase):
    def test_hello(self):
        self.assertEqual(hello(), "Hello, world!")

if __name__ == "__main__":
    unittest.main()
PY

```

```bash
cat > phases/NN-phase-slug/MM-new-lesson/quiz.json <<'JSON'
{
  "lesson": "MM-new-lesson",
  "title": "<Lesson Title>",
  "questions": [
    {"stage":"pre","question":"...","options":["a","b","c","d"],"correct":0,"explanation":""},
    {"stage":"check","question":"...","options":["a","b","c","d"],"correct":1,"explanation":""},
    {"stage":"check","question":"...","options":["a","b","c","d"],"correct":2,"explanation":""},
    {"stage":"check","question":"...","options":["a","b","c","d"],"correct":1,"explanation":""},
    {"stage":"post","question":"...","options":["a","b","c","d"],"correct":3,"explanation":""},
    {"stage":"post","question":"...","options":["a","b","c","d"],"correct":0,"explanation":""}
  ]
}
JSON

```

Validate the lesson locally before committing:

```bash
cd phases/NN-phase-slug/MM-new-lesson/code
python3 main.py && python3 -m unittest discover tests -v

```

## Summary

- **One lesson per directory** under `phases/<phase>-<slug>/<lesson>-<slug>/` ensures isolation and version control clarity.
- **Mandatory files** include [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with front-matter, `code/main.<lang>` with header comments, `code/tests/` with ≥5 unit tests, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) with exactly six questions.
- **`outputs/` directory** stores reusable artifacts like skills or prompt definitions.
- **Automation** via [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) and [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) depends on this strict structure for CI validation and site generation.
- **Multi-language support** includes Python, TypeScript, Rust, and Julia, declared explicitly in documentation front-matter.

## Frequently Asked Questions

### What programming languages are supported in the lesson code directory?

The repository supports **Python**, **TypeScript**, **Rust**, and **Julia**. The chosen language must be declared in the `**Languages:**` field of [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter and implemented in `code/main.<lang>` with accompanying tests in `code/tests/`.

### How many unit tests must each lesson include?

Each lesson must include **at least five unit tests** within the `code/tests/` subdirectory. The CI validation script [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) checks for test file presence, and local validation requires tests to pass using the language's standard runner (e.g., `python3 -m unittest`).

### What is the required format for the quiz.json file?

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must contain **exactly six questions** following a strict schema: one pre-assessment question, three checkpoint questions, and two post-assessment questions. Each question object requires `stage`, `question`, `options` array, `correct` index, and `explanation` fields.

### Where should reusable artifacts like skills or prompts be stored?

Reusable artifacts generated by the lesson—such as skill markdown files, agent configurations, or MCP server definitions—must be stored in the **`outputs/`** directory within the lesson folder. This convention allows automated tooling to discover and index these assets for the curriculum site.