# Folder Structure for Contributing New Lessons to ai-engineering-from-scratch

> Learn the folder structure for contributing new lessons to rohitg00/ai-engineering-from-scratch. Find requirements for docs, code, outputs, quiz.json, and roadmap entries.

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

---

**TLDR:** Every new lesson lives under `phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/` and must contain three sub-folders—`docs/` for the narrative, `code/` for implementations and tests, and `outputs/` for artifacts—plus mandatory [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) and registration entries in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md).

The `rohitg00/ai-engineering-from-scratch` repository enforces a strict folder structure for contributing new lessons to maintain consistency across its 20-phase curriculum. As defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and the "The shape of a lesson" section of the README, this convention ensures that every lesson follows the same organizational pattern, making the codebase navigable for both human contributors and automated agents.

## The Standard Three-Folder Layout

Each lesson directory requires three top-level sub-folders that separate content from executable code and generated artifacts.

### docs/

The `docs/` folder holds the lesson narrative in [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md), which must include YAML front-matter specifying the title, type, supported languages, prerequisites, estimated time, and learning objectives. This file serves as the canonical source for lesson metadata and instructional content.

### code/

The `code/` folder contains the implementation logic and test suite. You must provide a `main.<lang>` entry point (supporting Python, TypeScript, Rust, or Julia) with a header comment citing the lesson's documentation path. A `tests/` subdirectory must contain at least five unit tests validating the implementation.

### outputs/

The `outputs/` folder stores reusable artifacts generated during the lesson, such as skill definitions, prompt templates, agent configurations, or MCP server manifests. While optional during initial development, this folder must exist to accommodate generated files that extend the lesson's utility.

## Naming Conventions and Path Structure

The repository uses zero-padded two-digit indices to preserve lexical ordering. The full path follows this pattern:

```

phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/

```

For example, the second lesson in the first phase resides at `phases/01-math-foundations/02-vectors-matrices-operations/`. The `<NN>` prefix ensures that file explorers and shell commands list lessons in chronological order, while the hyphenated slugs provide human-readable context.

## Mandatory Files for Contribution

Beyond the directory structure, four specific files must exist before a lesson is considered complete according to the **New-Lesson Onboarding** guide in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).

### Documentation with Front-Matter

Create [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with standard front-matter that includes the title, type (e.g., "Build"), languages, prerequisites, time estimate, and bullet-list learning objectives.

```markdown

# Vectors, Matrices & Operations

> Learn the algebra that powers every neural net.

**Type:** Build  
**Languages:** Python, Julia  
**Prerequisites:** 01-linear-algebra-intuition  
**Time:** ~30 minutes

## Learning Objectives

- Compute dot products and matrix multiplications
- Derive broadcasting rules
- Implement basic linear-algebra utilities from scratch

```

### Implementation and Test Code

Place your primary implementation in `code/main.<ext>` with a header comment referencing the documentation path. Include a comprehensive test suite in `code/tests/` with a minimum of five unit tests.

```python

# =============================================================================

# Lesson: Vectors, Matrices & Operations

# Path: phases/01-math-foundations/02-vectors-matrices-operations/docs/en.md

# =============================================================================

```

```python
import unittest
from ..main import dot, matmul

class TestLinearAlgebra(unittest.TestCase):
    def test_dot(self):
        self.assertEqual(dot([1, 2, 3], [4, 5, 6]), 32)

    def test_matmul(self):
        a = [[1, 2], [3, 4]]
        b = [[5, 6], [7, 8]]
        self.assertEqual(matmul(a, b), [[19, 22], [43, 50]])

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

```

### Assessment Configuration

Include a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file in the lesson root following the six-question schema to validate learning outcomes. This file drives the automated assessment system and ensures students have mastered the material before proceeding.

## Central Index Registration

After creating the folder structure and content, you must register the lesson in two central index files to make it discoverable.

Update [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) by adding a row to the appropriate phase's lesson table that links to your new directory:

```markdown
| 02 | [Vectors, Matrices & Operations](phases/01-math-foundations/02-vectors-matrices-operations/) | Build | Python, Julia |

```

Update [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to track the lesson's development status, typically marking it as WIP (Work In Progress) initially and updating to ✅ upon completion.

## Step-by-Step Creation Workflow

To scaffold a new lesson programmatically, use this bash command structure, replacing the placeholders with your specific phase and lesson identifiers:

```bash
mkdir -p phases/01-math-foundations/02-vectors-matrices-operations/{docs,code,outputs}
touch phases/01-math-foundations/02-vectors-matrices-operations/quiz.json
mkdir phases/01-math-foundations/02-vectors-matrices-operations/code/tests

```

This command creates the required directory hierarchy in a single operation, establishing the `docs/`, `code/`, and `outputs/` folders while preparing the [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file and test directory for immediate population.

## Summary

- The canonical path is `phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/` with zero-padded indices.
- Every lesson requires three sub-folders: `docs/` for narratives, `code/` for implementations, and `outputs/` for artifacts.
- Mandatory files include [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with front-matter, `code/main.<lang>`, `code/tests/` with five+ unit tests, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json).
- Registration in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) (lesson table) and [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) (status tracking) is required for visibility.
- The complete specification lives in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) under the **New-Lesson Onboarding** section.

## Frequently Asked Questions

### What are the exact sub-folders required for a new lesson?

Every lesson must contain three sub-folders: `docs/` for the markdown narrative (specifically [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md)), `code/` for runnable implementations and tests, and `outputs/` for generated artifacts like skills, prompts, or agent configurations. This structure is enforced across all 20 phases of the curriculum.

### How do I name the lesson directory correctly?

Use the pattern `phases/<NN>-<phase-slug>/<NN>-<lesson-slug>/` where `<NN>` is a zero-padded two-digit number (e.g., `01`, `02`). The slugs should be short, hyphenated descriptors like `math-foundations` or `vectors-matrices-operations` that preserve lexical order when sorted alphabetically.

### What content must the docs/en.md file contain?

The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must include YAML front-matter with the title, type (e.g., "Build"), supported languages, prerequisite lessons, estimated time, and learning objectives. It also contains the narrative explanation of the lesson concepts and serves as the primary documentation source.

### How do I register a new lesson so it appears in the curriculum?

You must edit two files: add a row to the lesson table in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) linking to your lesson path, and add a status line in [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) to track whether the lesson is WIP or complete. Without these entries, the lesson remains invisible to the curriculum index.