One Lesson Per Commit: How the AI Engineering Curriculum Enforces Granular Git History

The rohitg00/ai-engineering-from-scratch repository enforces a strict one-lesson-per-commit policy through explicit rules in AGENTS.md, a mandatory conventional commit format featuring phase identifiers, and automated validation via scripts/audit_lessons.py.

The rohitg00/ai-engineering-from-scratch project maintains a rigorous one lesson per commit convention to ensure every change remains atomic, reviewable, and traceable to a specific curriculum module. This policy is codified in the repository's contribution guidelines and reinforced through both human-readable documentation and machine-enforced automation. By isolating each lesson to its own commit, the project preserves a clean git history that maps directly to the physical directory structure under phases/.

The Hard Rule in AGENTS.md

The foundation of the policy rests in AGENTS.md, which contains an explicit hard rule governing contributions. According to lines 45-46 of the file, the requirement states: "One commit per lesson directory. Never batch multiple lessons into one commit."

This directive makes it physically impossible to bundle unrelated curriculum changes without violating the documented contract. Contributors must treat each lesson as an isolated unit of work, ensuring that rollbacks, cherry-picks, and blame operations target exactly one learning module.

Conventional Commit Format

To make the rule machine-readable and maintainable at scale, every commit must follow a strict conventional format limited to 72 characters in the subject line. The required pattern is:

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

Or for bug fixes:

fix(phase-NN/MM): <slug>

The components enforce granular tracking:

• feat or fix – Indicates whether the commit adds new curriculum content or corrects existing material.
• phase-NN/MM – Identifies the phase number (NN) and lesson index (MM), directly correlating to the directory structure.
• <slug> – A short, kebab-case identifier describing the lesson content (e.g., attention-mechanism).

Phase and Lesson Identifiers

The parenthetical phase-NN/MM segment serves as the critical link between version control and the filesystem. A commit subject like feat(phase-07/03): tokenizer explicitly maps to the directory phases/07-nlp/03-tokenizer/. This one-to-one correspondence allows automated tooling and human reviewers to instantly verify that a commit touches exactly one lesson directory.

Commit Body Guidelines

The body of the commit message must explain why the lesson is being added or updated, not what the code does. This constraint encourages purposeful, isolated changes and naturally prevents the accidental bundling of unrelated modifications. When contributors must articulate the pedagogical reason for a change, they are less likely to combine multiple lessons into a single commit.

Automated Enforcement in CI

Manual conventions require automated backup to prevent policy drift. The repository implements this through .github/workflows/curriculum.yml, which defines an audit job triggered on every push and pull request.

This job executes scripts/audit_lessons.py, a validator that parses the PR's commit history and cross-references each commit against the filesystem. The script verifies that every commit modifies files within exactly one lesson directory under phases/NN-phase-slug/MM-lesson/. If the audit detects a commit touching multiple lesson directories—or failing to match the conventional format—the CI pipeline fails and blocks the merge.

Correct and Incorrect Commit Examples

The following examples demonstrate compliant and non-compliant commits for the one lesson per commit rule.

A valid commit adding lesson 03 in phase 07:

git add phases/07-nlp/03-tokenizer/
git commit -m "feat(phase-07/03): tokenizer"

A valid commit fixing a bug in lesson 12 of phase 14:

git add phases/14-vision/12-convolution/
git commit -m "fix(phase-14/12): correct padding bug"

An invalid commit bundling multiple lessons, which the CI will reject:

git add phases/05-ml/01-linear-regression/ phases/05-ml/02-logistic-regression/
git commit -m "feat(phase-05): add regression lessons"

Summary

• The one lesson per commit rule is explicitly defined in AGENTS.md as a hard requirement that forbids batching multiple lessons.
• Commits must use the conventional format type(phase-NN/MM): slug to ensure machine readability and direct mapping to lesson directories.
• The scripts/audit_lessons.py validator, invoked by the audit job in .github/workflows/curriculum.yml, automatically enforces the policy on every pull request.
• Commit bodies must explain pedagogical intent rather than implementation details, naturally isolating changes to single lessons.

Frequently Asked Questions

What happens if I accidentally commit multiple lessons in one commit?

The CI pipeline will fail the audit job when scripts/audit_lessons.py detects that a single commit touches multiple lesson directories. You must split the changes into separate commits—one per lesson directory—and push them individually to pass the automated validation.

Can I use commit types other than feat and fix for lessons?

While the examples in AGENTS.md focus on feat for new lessons and fix for corrections, the critical requirement is the phase-NN/MM identifier and the one-directory constraint. However, using standardized conventional commit types ensures consistency and clear intent for curriculum auditors.

How does the audit script verify one lesson per commit?

The scripts/audit_lessons.py utility parses each commit's diff to enumerate modified files, then checks that all changes reside within a single lesson directory matching the pattern phases/NN-phase-slug/MM-lesson/. If a commit spans multiple such directories or fails to reference the correct phase/lesson numbers in the subject line, the script exits with a non-zero status and reports the violation.

Where is the one lesson per commit convention documented?

The primary documentation resides in AGENTS.md at the repository root, specifically around lines 45-46. This file serves as both the contributor guideline and the specification for the automated enforcement tools that validate every proposed change to the curriculum.

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