# What Is the One Commit per Lesson Directory Rule in AI Engineering From Scratch?

> Learn the one commit per lesson directory rule in AI Engineering From Scratch. Keep your Git history atomic and traceable for a cleaner curriculum.

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

---

**The one commit per lesson directory rule requires that every lesson addition or update be contained in exactly one Git commit touching only that lesson's directory, ensuring the curriculum history remains atomic and traceable.**

The `rohitg00/ai-engineering-from-scratch` repository enforces strict commit hygiene to maintain its modular curriculum structure. This guide explains the **one commit per lesson directory** policy documented in the project's operating manuals and shows how to implement it when contributing new lessons or fixes.

## Where the Rule Is Documented

The commit structure policy is formally defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) under the Commit Structure section. The file specifies that each commit must correspond to a single, self-contained educational unit. [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) mirrors these requirements, providing step-by-step guidance for contributors adding or modifying content.

According to the source code, the rule exists to ensure that every lesson's `docs`, `code`, `tests`, and `quiz` files move through version control as a single logical change.

## Directory Structure and Scope

Lessons follow a strict filesystem hierarchy:

```

phases/NN-phase-slug/MM-lesson-slug/

```

For example, a lesson on attention mechanisms in Phase 7 would reside at `phases/07-transformers-deep-dive/03-attention-mechanisms/`.

Each lesson directory contains:

- `docs/` – Markdown documentation (e.g., [`en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/en.md))
- `code/` – Implementation files (e.g., [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py))
- `tests/` – Validation suites (e.g., [`test_main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/test_main.py))
- [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) – Assessment files

When you commit, **only one lesson directory** may appear in the staged changes. A commit spanning multiple lesson directories violates the policy.

## Creating Compliant Commits

### Adding a New Lesson

Create the directory structure and stage only that lesson's files:

```bash
mkdir -p phases/07-transformers-deep-dive/03-attention-mechanisms/{docs,code,tests}

# Create docs/en.md, code/main.py, tests/test_main.py, and quiz.json

git add phases/07-transformers-deep-dive/03-attention-mechanisms
git commit -m "feat(phase-07/03): add attention mechanisms lesson"

```

### Updating an Existing Lesson

Modify files within a single lesson directory, then commit:

```bash

# Edit phases/07-transformers-deep-dive/03-attention-mechanisms/docs/en.md

git add phases/07-transformers-deep-dive/03-attention-mechanisms
git commit -m "fix(phase-07/03): correct typo in docs/en.md"

```

Both examples adhere to the **one commit per lesson directory** requirement by restricting the `git add` scope to a single lesson folder.

## Why Atomic Commits Matter

This policy delivers several architectural benefits to the curriculum:

- **Atomic changes** – Each commit represents a complete, deployable lesson unit, preventing partial updates that could break the build pipeline.
- **Focused code review** – Reviewers evaluate one lesson at a time, reducing cognitive load and merge conflict potential.
- **CI isolation** – The continuous integration pipeline runs tests specific to the changed lesson only, keeping build times fast and failures localized.
- **Historical traceability** – Git history clearly shows when each lesson was introduced or modified without cross-contamination from unrelated changes.
- **Site generation integrity** – The static site builder relies on consistent markdown link formats in [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md); atomic commits ensure these references remain valid.

## Automated Enforcement

The repository validates compliance through [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py). This CI script runs during pull request checks to verify that commits touch only one lesson directory. Violations block merging, ensuring the history stays clean before integration into `main`.

## Summary

- The **one commit per lesson directory** rule requires atomic commits scoped to a single lesson folder within `phases/`.
- Documentation in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/CONTRIBUTING.md) mandates this structure for all contributions.
- Each lesson directory contains `docs/`, `code/`, `tests/`, and [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) files that must move together in one commit.
- Use scoped `git add` commands targeting only the specific `phases/NN-phase-slug/MM-lesson-slug/` path.
- [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) enforces this policy automatically in CI.

## Frequently Asked Questions

### What happens if I commit changes to multiple lesson directories?

The CI pipeline will reject the pull request. [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) detects cross-directory changes and blocks merging until you split the modifications into separate, lesson-specific commits.

### Can I include README updates in the same commit as a lesson?

No. The [`README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/README.md) file lives at the repository root, outside any lesson directory. Update it in a separate commit after your lesson commit, or the audit script will flag the change as spanning multiple isolated units.

### How should I format commit messages for lesson changes?

Follow the conventional commit pattern shown in the repository: `type(phase-NN/MM): description`. For example, use `feat(phase-07/03):` for new lessons and `fix(phase-07/03):` for corrections. The phase and lesson numbers must match the directory structure exactly.

### Does this rule apply to fixing typos in documentation?

Yes. Even minor edits like typo fixes in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) must follow the **one commit per lesson directory** rule. Stage only the affected lesson's directory and commit with a message like `fix(phase-07/03): correct typo in docs/en.md`.