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

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 with YAML front-matter, a code/ directory with implementation and at least five unit tests, and a 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 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) to walk the tree and extract metadata programmatically.

The Four Mandatory Components

Inside the lesson directory, you must create:

1. 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, main.ts, 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 – 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 file begins with a front-matter block that tooling parses to generate the curriculum catalog. According to the specification in 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 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 file follows a strict schema documented in 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 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 – Must list every lesson with a markdown link in the format [Lesson Title](phases/<phase-slug>/<lesson-slug>/). The site/build.js script parses these links to generate navigation data; missing links cause lessons to disappear from the site.
• ROADMAP.md – Tracks lesson status (e.g., WIP, Done) and updates whenever a lesson is added or completed.
• 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 – Parses README.md, ROADMAP.md, and glossary/terms.md to produce site/data.js. It expects the specific markdown link format described above.
• 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 – Walks every phases/*/*/ directory to extract metadata from docs/en.md and quiz.json for catalog generation.

Creating a New Lesson Skeleton

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

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, code/ with implementation, code/tests/ with ≥5 tests, and quiz.json.
• The docs/en.md requires YAML front-matter for catalog generation, while quiz.json must contain exactly six questions (1 pre, 3 check, 2 post).
• Repository infrastructure including README.md, ROADMAP.md, and glossary/terms.md enables automated site building and catalog generation.
• The 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 script parses 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 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, 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 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 specification.

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