# Required Directory Structure and Files for a Curriculum Lesson in AI Engineering From Scratch

> Discover the essential directory structure and files needed for an AI Engineering From Scratch curriculum lesson. Learn about docs en.md, code, and quiz.json requirements.

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

---

**A curriculum lesson in the AI Engineering From Scratch repository must reside under `phases/<phase-slug>/<lesson-slug>/` and contain four mandatory components: [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with YAML front-matter, a `code/` directory with implementation and at least five unit tests, and a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file with six assessment questions.**

The AI Engineering From Scratch repository enforces a strict lesson contract to power automated catalog generation, CI validation, and site building. Understanding the required directory structure and files for a curriculum lesson ensures your contribution passes the [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) checker and appears correctly in the generated navigation. Every lesson follows a predictable layout that enables language-agnostic tooling to extract metadata, validate test coverage, and render the curriculum site.

## Core Lesson Directory Layout

### Path Convention

Every lesson lives at `phases/<phase-slug>/<lesson-slug>/` where `phase-slug` represents the curriculum phase (e.g., `01-math-foundations`) and `lesson-slug` identifies the specific lesson (e.g., `99-new-lesson`). This nesting enables the **catalog builder** ([`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py)) to walk the tree and extract metadata programmatically.

### The Four Mandatory Components

Inside the lesson directory, you must create:

1. **[`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)** – The lesson explainer with front-matter defining title, hook, type, languages, prerequisites, and learning objectives.
2. **`code/`** – Contains the implementation file ([`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts), [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs), or `main.jl`) and a `tests/` subdirectory.
3. **`code/tests/`** – Houses unit tests runnable via standard library test runners, containing **at least five** tests.
4. **[`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json)** – JSON file describing exactly six questions: one pre-assessment, three check-ins, and two post-assessment.

## Required Files Deep Dive

### docs/en.md (Lesson Documentation)

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file begins with a front-matter block that tooling parses to generate the curriculum catalog. According to the specification in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), this metadata includes the lesson title, one-line hook, type (Build, Theory, or Integration), supported languages, prerequisites, and learning objectives.

### code/ Directory (Implementation and Tests)

The `code/` directory holds the primary implementation. Each language implementation must start with a short header comment citing the lesson’s [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and any relevant specifications. The `tests/` subdirectory must contain at least five unit tests that run with the language’s standard test runner, such as `python -m unittest discover` or `npx tsx --test`.

### quiz.json (Assessment Schema)

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file follows a strict schema documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). It must contain exactly six questions structured as: one pre-assessment question, three check-in questions, and two post-assessment questions. Each question object includes the stage, question text, options array, correct answer index, and explanation.

## Optional Artifacts

If the lesson produces a reusable artifact—such as a **skill**, **prompt**, **agent**, or **MCP server**—place it in the optional `outputs/` directory. For example, [`outputs/skill-my-feature.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/skill-my-feature.md) stores a reusable skill definition that other lessons or external tools can reference.

## Repository-Wide Infrastructure

Several root-level files coordinate the lesson ecosystem:

- **[`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md)** – Must list every lesson with a markdown link in the format `[Lesson Title](phases/<phase-slug>/<lesson-slug>/)`. The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses these links to generate navigation data; missing links cause lessons to disappear from the site.
- **[`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md)** – Tracks lesson status (e.g., *WIP*, *Done*) and updates whenever a lesson is added or completed.
- **[`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md)** – Central canonical definitions referenced by multiple lessons to maintain consistent terminology across the curriculum.

## Automation and Validation

The repository relies on automated tooling to maintain quality:

- **[`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 [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md) to produce [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). It expects the specific markdown link format described above.
- **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** – CI-run invariant checker that validates every lesson directory against the contract, verifying file presence, correct naming conventions, and test counts.
- **[`scripts/build_catalog.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_catalog.py)** – Walks every `phases/*/*/` directory to extract metadata from [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) for catalog generation.

## Creating a New Lesson Skeleton

Use the following bash commands to scaffold a compliant lesson structure:

```bash
mkdir -p phases/01-math-foundations/99-new-lesson/{docs,code/tests,outputs}

cat > phases/01-math-foundations/99-new-lesson/docs/en.md <<'EOF'

# New Lesson Title

> One‑line hook

**Type:** Build
**Languages:** Python
**Prerequisites:** None
**Time:** ~30 minutes

## Learning Objectives

- Explain the concept
- Implement the algorithm
- Write tests
- Run the demo
EOF

cat > phases/01-math-foundations/99-new-lesson/code/main.py <<'EOF'

# Implements the new lesson – see docs/en.md for details

def main():
    print("Hello, curriculum!")
if __name__ == "__main__":
    main()
EOF

cat > phases/01-math-foundations/99-new-lesson/code/tests/test_main.py <<'EOF'
import unittest
from main import main

class TestMain(unittest.TestCase):
    def test_output(self):
        # Basic sanity check

        self.assertTrue(True)

if __name__ == '__main__':
    unittest.main()
EOF

cat > phases/01-math-foundations/99-new-lesson/quiz.json <<'EOF'
{
  "lesson": "99-new-lesson",
  "title": "New 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":""}
  ]
}
EOF

```

## Summary

- Lessons must live at `phases/<phase-slug>/<lesson-slug>/` with exactly four mandatory components: [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/` with implementation, `code/tests/` with ≥5 tests, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json).
- The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) requires YAML front-matter for catalog generation, while [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) must contain exactly six questions (1 pre, 3 check, 2 post).
- Repository infrastructure including [`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 [`glossary/terms.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/glossary/terms.md) enables automated site building and catalog generation.
- The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) CI validator enforces the contract, ensuring every lesson runs to completion without hanging on missing dependencies.

## Frequently Asked Questions

### What happens if I forget to add the lesson to README.md?

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) to generate navigation data for the curriculum site. If you omit the markdown link in the format `[Lesson Title](phases/<phase-slug>/<lesson-slug>/)`, the lesson will not appear in the generated site, though the [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validator will still verify the local directory structure.

### How many tests must a lesson include?

Every lesson must include **at least five** unit tests in the `code/tests/` directory. These tests must run with the language's standard-library test runner, such as `python -m unittest discover` for Python or `npx tsx --test` for TypeScript, ensuring self-terminating demos that validate implementation correctness.

### Can I use a language other than Python for the implementation?

Yes. The repository supports multiple implementation languages including **Python**, **TypeScript**, **Rust**, and **Julia**. Place the primary implementation file at `code/main.<lang>` (e.g., [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts), [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs), or `main.jl`) and ensure the tests use the corresponding language-specific test framework.

### What is the purpose of the quiz.json file?

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file defines the six-question assessment that accompanies each lesson, consisting of one pre-assessment, three check-in, and two post-assessment questions. This schema enables automated quiz rendering and progress tracking throughout the curriculum, as documented in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification.