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

> Understand the typical internal structure of a lesson directory in AI Engineering From Scratch. Explore docs, code, and quiz files for comprehensive learning.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: internals
- Published: 2026-09-02

---

**A lesson directory in the AI Engineering From Scratch curriculum follows a standardized layout containing [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) for documentation, a `code/` directory with implementation and tests, and a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](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` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and the Python implementation at [`code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/01-terminal-native-coding-agent/code/main.py) begins with:

```python

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

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/tests/test_main.py) implements the minimum five-test requirement using standard patterns:

```python
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), `code/` with tests, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) according to the Lesson Contract in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).
- The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) for documentation, a `code/` subdirectory with the implementation, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) for assessment. The Lesson Contract in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.