Typical Internal Structure of a Lesson Directory in AI Engineering From Scratch

A lesson directory in the AI Engineering From Scratch curriculum follows a standardized layout containing docs/en.md for documentation, a code/ directory with implementation and tests, and a quiz.json file for assessment.

The rohitg00/ai-engineering-from-scratch repository organizes its curriculum into self-contained lesson directories that enforce strict structural conventions. Understanding the typical internal structure of a lesson directory helps contributors maintain consistency and allows learners to navigate materials efficiently. Each lesson adheres to the Lesson Contract defined in AGENTS.md, ensuring every directory contains the mandatory components required for a complete educational unit.

Core Components of the Lesson Directory Structure

Documentation Standards (docs/en.md)

Every lesson must include a docs/en.md file at the root of its directory. This file contains the human-readable lesson description, YAML front-matter metadata, and explicit learning objectives. According to the Lesson Contract in AGENTS.md, this documentation serves as the canonical source that implementation files must reference in their header comments.

Executable Implementation (code/)

The code/ directory houses the lesson's executable implementation, typically named main.py, main.ts, main.rs, or main.jl depending on the target language. As specified in the repository standards, every implementation file must begin with a header comment citing the corresponding docs/en.md source path and any relevant technical specifications.

Unit Testing Requirements (code/tests/)

Lessons must include a code/tests/ subdirectory containing a minimum of five unit tests. The test suite validates the implementation using the language's standard test runner, such as python -m unittest for Python or npx tsx --test for TypeScript. This requirement ensures code quality and provides learners with verification mechanisms.

Structured Assessment (quiz.json)

Each lesson directory contains a quiz.json file encoding exactly six questions: one pre-question, three check-questions, and two post-questions. This JSON schema follows the rigid structure defined in the Lesson Contract, providing automated assessment capabilities.

Optional Artifacts (outputs/)

Some lessons include an outputs/ directory for shipping reusable artifacts. These may include skill markdown files, trained model checkpoints, or generated prompts that extend the lesson's utility beyond the immediate tutorial.

Real-World Directory Layout

The capstone project 01-terminal-native-coding-agent in phases/19-capstone-projects/ demonstrates the practical application of these standards:

phases/19-capstone-projects/01-terminal-native-coding-agent/
├── docs/
│   └── en.md
├── code/
│   ├── main.py
│   └── tests/
│       └── test_main.py
├── outputs/
│   └── skill-terminal-coding.md
└── quiz.json

This structure maps directly to the Lesson Contract requirements, with the lesson description residing at docs/en.md and the Python implementation at code/main.py as implemented in rohitg00/ai-engineering-from-scratch.

Code Conventions and Header Requirements

Implementation files must reference their documentation source. For example, phases/19-capstone-projects/01-terminal-native-coding-agent/code/main.py begins with:

# ------------------------------------------------------------

# Lesson: Terminal-Native Coding Agent

# Source: docs/en.md

# ------------------------------------------------------------

def main():
    # ... lesson logic here ...

    pass

if __name__ == "__main__":
    main()

The corresponding test file at code/tests/test_main.py implements the minimum five-test requirement using standard patterns:

import unittest
from code.main import main

class TestMain(unittest.TestCase):
    def test_basic_behavior(self):
        self.assertIsNone(main())

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

Summary

• Every lesson directory must contain docs/en.md, code/ with tests, and quiz.json according to the Lesson Contract in AGENTS.md.
• The docs/en.md file serves as the canonical documentation source cited in code headers.
• Implementation files require standard header comments referencing their documentation source.
• The code/tests/ directory must contain at least five unit tests using language-specific standard runners.
• Optional outputs/ directories store reusable artifacts like model checkpoints or skill definitions.

Frequently Asked Questions

What files are mandatory in every lesson directory?

Every lesson directory must contain docs/en.md for documentation, a code/ subdirectory with the implementation, and quiz.json for assessment. The Lesson Contract in AGENTS.md strictly mandates these components, while an outputs/ directory remains optional for shipping artifacts.

How many tests must each lesson include?

Each lesson must include a minimum of five unit tests located in code/tests/. These tests must run using the language's standard test runner, such as python -m unittest for Python or equivalent tools for TypeScript, Rust, or Julia implementations.

Where is the lesson structure defined in the repository?

The lesson structure is formally defined in the Lesson Contract within AGENTS.md at the repository root. This document specifies the directory layout, file naming conventions, and metadata requirements that all lessons in the phases/ directory must follow.

Can a lesson exist without a quiz.json file?

No, the quiz.json file is mandatory and must follow a strict schema containing exactly six questions: one pre-question, three check-questions, and two post-questions. This standardized assessment format ensures consistent evaluation across all lessons in the curriculum.

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