How to Contribute a New AI Lesson to ai-engineering-from-scratch: Commit Conventions & Structure

To contribute a new AI lesson to the ai-engineering-from-scratch curriculum, create a standardized lesson skeleton under phases/XX-phase-slug/NN-lesson-slug/, follow the commit convention feat(phase-NN/MM): add <lesson-slug>, and update both README.md and ROADMAP.md to maintain repository integrity.

Contributing to the ai-engineering-from-scratch repository requires strict adherence to architectural conventions defined in AGENTS.md and CONTRIBUTING.md. Each lesson must live as an isolated commit with a specific conventional format, ensuring the automated CI pipelines and curriculum indexes remain synchronized.

Lesson Structure Requirements

Every new AI lesson must reside in a dedicated directory following the pattern phases/XX-phase-slug/NN-lesson-slug/. According to AGENTS.md lines 15-24, this directory must contain four standard sub-folders:

• docs/ – Documentation files
• code/ – Implementation files
• outputs/ – Optional generated artifacts
• tests/ – Unit tests (typically nested as code/tests/)

The required files include docs/en.md for the lesson guide, at least one runnable implementation in code/main.<lang>, a quiz.json file, and unit tests in code/tests/.

Creating the Directory Skeleton

Use the following bash command to generate the proper structure:

mkdir -p phases/03-transformers-deep-dive/12-new-lesson/{docs,code,code/tests,outputs}

Documentation Standards

The docs/en.md file must begin with standardized front-matter as defined in the Lesson contract within AGENTS.md lines 65-78. This includes:

• Title and hook (one-line summary)
• Type (e.g., Build, Theory)
• Languages supported (Python, TypeScript, Rust, or Julia)
• Prerequisites (previous lesson numbers)
• Time estimate
• Learning objectives

Follow the markdown layout specifications shown in CONTRIBUTING.md lines 40-72 for consistency across the curriculum.

Example front-matter:

# My New Lesson

> One‑line hook that captures the core idea.

**Type:** Build  
**Languages:** Python  
**Prerequisites:** 07‑self‑attention-from‑scratch  
**Time:** ~30 minutes  

## Learning Objectives

- Explain the concept …
- Implement the algorithm …
- Compare with a library implementation …

Code Implementation Requirements

Place your main implementation in code/main.<lang> using Python, TypeScript, Rust, or Julia. As specified in AGENTS.md lines 2-6 and 62-66, prepend a 4-6 line header comment that cites the lesson's docs/en.md path and any RFC or paper sources.

Unit Testing Standards

Create at least five unit tests in code/tests/ that can be executed with the language's standard test runner. According to AGENTS.md lines 8-12, verify functionality with:

python3 -m unittest discover

Quiz Configuration

Every lesson must include a quiz.json file adhering to the exact six-question schema defined in AGENTS.md lines 83-99: one pre-assessment question, three check-in questions, and two post-assessment questions.

Repository Index Updates

Before committing, update the public indexes to ensure the automated site generator (site/build.js) can parse your contribution.

README.md Requirements

Add a new row to the lesson table using the Markdown link format. The parser extracts the URL from this link syntax, as documented in CONTRIBUTING.md lines 7-18 and AGENTS.md lines 53-57:

| 12 | [My New Lesson](phases/03-transformers-deep-dive/12-new-lesson/) | Build | Python |

ROADMAP.md Updates

Add a status glyph to your lesson's row: ✅ for finished, 🚧 for work-in-progress, or ⬚ for planned. This convention appears in CONTRIBUTING.md lines 19-20.

Commit Conventions

The ai-engineering-from-scratch repository enforces a strict "one-commit-per-lesson" rule. Each lesson introduction must use a conventional subject line limited to 72 characters:

feat(phase-NN/MM): add <lesson-slug>

According to AGENTS.md lines 40-42, the commit body should explain why the lesson is added (its educational value), not what files contain. For example:

git add phases/03-transformers-deep-dive/12-new-lesson
git commit -m "feat(phase-03/12): add my-new-lesson"

This format triggers CI automation that rebuilds site/data.js and verifies README counts.

Validation and Submission

Before pushing, execute the audit scripts and lesson-specific tests to ensure everything runs and the README/ROADMAP syntax remains parsable, as required by AGENTS.md lines 15-18.

Once validated, push your branch and create a pull request with the same title as your commit subject. The CI pipeline automatically validates the commit message format and checks that the lesson skeleton meets all structural requirements.

Summary

• Structure: Create lessons under phases/XX-phase-slug/NN-lesson-slug/ with docs/, code/, code/tests/, and optional outputs/ directories
• Documentation: Include standardized front-matter in docs/en.md with title, hook, type, languages, prerequisites, time estimate, and learning objectives
• Code: Implement in code/main.<lang> with 4-6 line header comments citing sources, plus at least five unit tests
• Quiz: Provide quiz.json with the six-question schema (1 pre, 3 check, 2 post)
• Indexes: Update README.md with Markdown link format and ROADMAP.md with status glyphs (✅, 🚧)
• Commits: Use feat(phase-NN/MM): add <lesson-slug> format with 72-character limit and explanatory body
• Validation: Run local audit scripts and tests before submitting PR

Frequently Asked Questions

How do I determine the correct phase and lesson numbers for my contribution?

Check ROADMAP.md to identify the current phase structure and the next available lesson number in your target phase. The numbering scheme follows NN format (e.g., 12) within each phase directory named XX-phase-slug (e.g., 03-transformers-deep-dive). Ensure your lesson number follows sequentially from existing lessons in that phase.

What programming languages are supported for lesson implementations?

The repository accepts implementations in Python, TypeScript, Rust, and Julia. Place your main code in code/main.<lang> with the appropriate extension. The quiz.json and documentation should specify which languages are supported for that particular lesson.

Why does my commit need to be exactly one commit per lesson?

The repository maintains a strict "one-commit-per-lesson" rule to preserve curriculum integrity and enable atomic rollbacks. According to AGENTS.md, this convention ensures that automated CI pipelines can correctly regenerate site/data.js and maintain the lesson index. If you need to make changes after initial submission, amend your commit or create a new single commit for the lesson update.

What happens if I don't update README.md and ROADMAP.md?

The site/build.js script generates the public curriculum site by parsing README.md for lesson links and ROADMAP.md for status tracking. Without these updates, your lesson will not appear in the public index or navigation, and CI checks will fail. The Markdown link format [Lesson Title](path) is specifically required for the parser to extract URLs correctly.

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