Why One Commit Per Lesson Is Required for AI Engineering From Scratch Contributions

One commit per lesson is required to maintain atomic history, enable granular code reviews, and ensure the CI pipeline runs audit_lessons.py reliably on isolated changes without cross-lesson contamination.

The ai-engineering-from-scratch repository is a comprehensive curriculum containing 435 lessons across 20 phases. When contributing to this open-source learning resource, contributors must follow the strict "one commit per lesson" rule defined in AGENTS.md. This architectural requirement ensures that each lesson's documentation, code, tests, and quiz files remain modular and independently reviewable.

The Hard Rule in AGENTS.md

The contribution guidelines explicitly enforce atomic commits at the lesson level. In [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md#L40‑L41), the Hard rules section states:

1. One commit per lesson directory. Never batch multiple lessons into one commit.

Each lesson lives in its own directory under phases/NN-phase-slug/NN-lesson-slug/ and contains self-contained files including documentation, implementation code, tests, and quiz data. This directory isolation supports the commit granularity requirement.

Architectural Rationale for One Commit Per Lesson

The rule exists to solve specific scalability and maintenance challenges inherent in large educational repositories.

Granular Review Process

Reviewers can focus on a single lesson's complete changes—documentation, code samples, and assessments—without distraction from unrelated lessons. This matches the curriculum’s "lesson-by-lesson" learning model where each unit must be internally consistent and pedagogically sound.

Atomic Git History

Each lesson’s evolution records as an independent commit. If a lesson requires reversion due to errors or outdated content, maintainers can undo that specific change without touching other lessons. This prevents the "cascade revert" problem common in batched commits.

CI Pipeline Stability

The continuous integration system executes scripts/audit_lessons.py against every lesson directory. Isolating changes to one lesson prevents a faulty commit in one directory from causing false-positive failures in unrelated lessons during automated validation.

Merge Conflict Avoidance

Because each lesson occupies a separate directory under phases/, separate commits keep diffs small and localized. This design makes automatic merges far less likely to hit conflicts, especially when multiple contributors work simultaneously on different phases.

Clear Ownership and Traceability

The canonical commit message format feat(phase-NN/MM): <slug> ties every change to a precise lesson. This convention makes it easy to locate the author and rationale for any future maintenance or updates.

How to Structure Your Commits

Follow this workflow to ensure compliance with the one commit per lesson rule.

Creating a New Lesson

# 1. Create the lesson directory structure

mkdir -p phases/03-phase-example/01-new-lesson/{docs,code,outputs}

# 2. Populate lesson files (docs/en.md, code/main.py, quiz.json, etc.)

# 3. Stage ONLY this lesson's files

git add phases/03-phase-example/01-new-lesson

# 4. Commit with the canonical format

git commit -m "feat(phase-03/01): add new-lesson"

# 5. Push and create pull request

git push -u origin my-new-lesson-branch
gh pr create --title "feat(phase-03/01): add new-lesson" \
    --body "Adds lesson 01-new-lesson with documentation, implementation, tests, and quiz."

Making Follow-Up Changes

When fixing errors or updating content, create a new commit that again touches only that specific lesson:

git add phases/03-phase-example/01-new-lesson/docs/en.md
git commit -m "fix(phase-03/01): correct typo in lesson description"

Handling Multiple Lessons in One PR

When adding several lessons in a single pull request, repeat the pattern—one commit per lesson—so the PR contains a linear series of atomic, review-ready commits rather than a single large batch.

Summary

• One commit per lesson is a hard rule defined in AGENTS.md for the ai-engineering-from-scratch curriculum.
• Atomic commits enable independent reversion and prevent cross-lesson contamination in the Git history.
• Isolated validation allows scripts/audit_lessons.py to run reliably in CI without false positives from unrelated changes.
• Canonical commit format uses feat(phase-NN/MM): <slug> to maintain clear ownership and traceability.
• Directory-based isolation under phases/ keeps diffs small and minimizes merge conflicts.

Frequently Asked Questions

What happens if I batch multiple lessons into one commit?

Batched commits violate the AGENTS.md hard rules and will likely be rejected during review. The CI pipeline running audit_lessons.py may also fail to properly validate individual lessons when changes are combined, making it harder to identify which specific lesson contains errors.

Can I fix a typo across multiple lessons in one commit?

No. Even for minor fixes like typo corrections, you must create separate commits for each affected lesson. This preserves the atomic history and ensures that revert operations or blame tracking remain precise and lesson-specific.

Why does the commit message need the phase/lesson number format?

The format feat(phase-NN/MM): <slug> provides immediate context about which lesson changed without examining the file diff. This convention integrates with the curriculum.yml workflow and makes it possible to trace when specific lessons were introduced or modified across the 435-lesson repository.

How does this rule affect the README.md updates?

Updates to README.md that involve adding lesson links must follow the same principle—changes should correspond to the specific lesson being added. Avoid bulk-editing the README for multiple lessons in a single commit, as this could break the generated site navigation and complicates the review process.

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