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

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 under the Commit Structure section. The file specifies that each commit must correspond to a single, self-contained educational unit. 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)
• code/ – Implementation files (e.g., main.py)
• tests/ – Validation suites (e.g., test_main.py)
• 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:

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:

# 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; atomic commits ensure these references remain valid.

Automated Enforcement

The repository validates compliance through 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 and CONTRIBUTING.md mandates this structure for all contributions.
• Each lesson directory contains docs/, code/, tests/, and 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 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 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 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 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.

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