How to Add a New Lesson to AI Engineering from Scratch: Complete Contributor Guide

To add a new lesson to the AI Engineering from Scratch curriculum, you must create a structured directory under phases/ containing documentation, implementation code, unit tests, and a quiz file, then update the curriculum indexes and validate your changes with the audit script.

The rohitg00/ai-engineering-from-scratch repository organizes its educational content into a strict directory structure defined in AGENTS.md. Each lesson follows a lesson contract that ensures consistency across the phases, making it discoverable by the build system and testable by CI pipelines.

Understanding the Lesson Structure

Every lesson in the curriculum lives in its own directory under phases/NN-phase-slug/MM-new-lesson/, where NN represents the phase number and MM the lesson number within that phase.

Directory Layout

Create the following skeleton to satisfy the repository’s structural requirements:

• docs/ – Contains the lesson documentation in Markdown
• code/ – Houses the main implementation file
• code/tests/ – Stores unit tests for the implementation
• outputs/ – Optional directory for reusable artifacts like skills or prompts

The repository supports implementations in Python, TypeScript, Rust, and Julia, with each language requiring specific file extensions in the code/ directory.

Required Files

A complete lesson requires four mandatory files:

1. docs/en.md – Lesson description with standardized frontmatter
2. code/main.<lang> – Core implementation with a 4-6 line header comment citing the documentation path
3. code/tests/test_main.<lang> – Unit tests using the language’s standard test framework
4. quiz.json – Six-question assessment following the schema (1 pre-assessment, 3 check-for-understanding, 2 post-assessment)

Step-by-Step Implementation

Follow this exact workflow to ensure your lesson passes automated validation in scripts/audit_lessons.py.

1. Create the Lesson Skeleton

Use mkdir to generate the nested directory structure. For example, to create lesson 43 in phase 14:

mkdir -p phases/14-agent-engineering/43-new-lesson/{docs,code,code/tests,outputs}

This command creates all necessary subdirectories in one operation, including the optional outputs/ folder for artifacts.

2. Write Documentation

Populate docs/en.md with the required frontmatter block. The file must include the title, hook, type, languages, prerequisites, time estimate, and learning objectives:

# My New Lesson Title

> A one-line hook that sparks curiosity

**Type:** Build
**Languages:** python
**Prerequisites:** 14-agent-engineering/42-agent-workbench-capstone
**Time:** ~30

## Learning Objectives

- Implement a simple agent loop
- Demonstrate prompt engineering basics
- Write unit tests for the agent

The prerequisites field must reference existing lessons using the phase/lesson slug format to maintain curriculum dependencies.

3. Implement the Code

Create code/main.py (or the appropriate language file) beginning with a standardized header comment that links back to the documentation:

# Lesson: My New Lesson Title

# Docs: phases/14-agent-engineering/43-new-lesson/docs/en.md

# Implements a trivial echo agent for illustration

def agent(prompt: str) -> str:
    return f"Echo: {prompt}"

The header comment must span 4-6 lines and cite the exact documentation path for traceability.

4. Add Unit Tests

Populate code/tests/test_main.py with at least five test cases using the standard library’s testing framework:

import unittest
from main import agent

class TestAgent(unittest.TestCase):
    def test_echo(self):
        self.assertEqual(agent("hello"), "Echo: hello")

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

Run tests locally before committing:

cd phases/14-agent-engineering/43-new-lesson/code
python3 main.py && python3 -m unittest discover tests -v

5. Create the Quiz

Write quiz.json following the strict six-question schema. The file must contain exactly one pre-assessment question, three check-for-understanding questions, and two post-assessment questions:

{
  "lesson": "43-new-lesson",
  "title": "My 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":""}
  ]
}

Each question object requires the stage, question, options array, correct index, and explanation fields.

6. Update Curriculum Indexes

You must modify three index files to register the new lesson:

• README.md – Insert a markdown table row linking to the lesson directory: [Lesson Title](phases/NN-phase-slug/MM-new-lesson/)
• ROADMAP.md – Add a row tracking the lesson status (e.g., WIP or Done)
• glossary/terms.md – Add entries for any new terminology introduced

These updates ensure the lesson appears in the public curriculum index and build pipeline.

Validation and Testing

Before submitting, execute the audit script to check for contract violations:

python3 scripts/audit_lessons.py

This script validates directory structure, file presence, quiz schema compliance, and documentation frontmatter. Fix any reported errors to prevent CI failures.

Commit only the new lesson directory and the three modified index files using conventional commit format:

git add phases/14-agent-engineering/43-new-lesson/ README.md ROADMAP.md glossary/terms.md
git commit -m "feat(phase-14/43): add new-lesson-slug"

CI Pipeline Integration

When you open a pull request, the CI pipeline automatically executes three jobs:

1. audit – Re-runs scripts/audit_lessons.py to verify contract compliance
2. readme-counts-sync – Synchronizes lesson counts in README.md
3. site-rebuild – Regenerates site/data.js for the documentation website

These automated checks ensure that every merged lesson is immediately available and correctly indexed.

Summary

• Create the directory skeleton under phases/ with docs/, code/, code/tests/, and optional outputs/ subdirectories
• Write docs/en.md with mandatory frontmatter including prerequisites and learning objectives
• Implement code/main.<lang> with a standardized header comment linking to documentation
• Provide ≥5 unit tests in code/tests/ using the language’s standard framework
• Structure quiz.json with exactly six questions (1 pre, 3 check, 2 post)
• Update README.md, ROADMAP.md, and glossary/terms.md to register the lesson
• Validate locally with python3 scripts/audit_lessons.py before committing

Frequently Asked Questions

What is the lesson contract in AI Engineering from Scratch?

The lesson contract is a set of structural and content requirements defined in AGENTS.md that governs how lessons must be organized. It mandates specific directory layouts, frontmatter fields, test coverage minimums, and quiz schemas to ensure every lesson works with the automated build and validation systems.

Which programming languages can I use for lesson implementations?

The repository currently supports Python, TypeScript, Rust, and Julia. You must place the main implementation in code/main.<ext> using the appropriate extension, and the test file must use the language’s standard testing framework (e.g., unittest for Python).

How many unit tests are required for a new lesson?

You must write at least five unit tests in code/tests/test_main.<ext> according to the contributor guidelines. The CI pipeline will fail if the test directory is missing or contains fewer than five test cases.

What happens if the audit script finds errors?

If scripts/audit_lessons.py reports contract violations—such as missing frontmatter, incorrect directory structure, or malformed quiz JSON—you must fix these issues before submitting your pull request. The CI pipeline runs this script automatically and will block merging until all violations are resolved.

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