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

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, code/ with tests, 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 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. 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 – 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 – 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.

Front-Matter Requirements in 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:

# 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

The 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 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 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:

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

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

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

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:

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 with front-matter, code/main.<lang> with header comments, code/tests/ with ≥5 unit tests, and quiz.json with exactly six questions.
• outputs/ directory stores reusable artifacts like skills or prompt definitions.
• Automation via scripts/audit_lessons.py and 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 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 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 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.

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