How Conventional Commit Format Works in the AI-Engineering-From-Scratch Repository

The rohitg00/ai-engineering-from-scratch repository enforces a strict conventional commit format defined in AGENTS.md that combines a mandatory feat prefix, a phase-NN/MM scope, and a kebab-case description to keep the curriculum readable and machine-processable.

According to the rohitg00/ai-engineering-from-scratch source code, every contribution must follow the exact conventional commit style spelled out in the repository's contribution manual. This standardized format allows CI scripts and the site builder to automatically map each pull request to the correct lesson directory without manual intervention.

The Conventional Commit Format Specification

The rule is formally defined in AGENTS.md (lines 40-42) and breaks every commit subject into three distinct parts.

Subject Length Limit

The commit header must be 72 characters or fewer. This hard limit guarantees that subjects render cleanly in GitHub, terminal log viewers, and notification emails without truncation.

Required Prefix and Scope Syntax

Every commit must use the feat prefix. Unlike broader conventional commit specifications that allow fix, docs, or chore, this curriculum treats all new and updated lessons as features.

Immediately after the prefix, the scope uses the exact syntax feat(phase-NN/MM) where:

• NN is the two-digit phase number (for example, 01, 02).
• MM is the two-digit lesson number within that phase.
• The scope is wrapped in parentheses and directly follows the prefix.

Slug Description Format

After the colon and a single space, the description contains a short kebab-case slug that uniquely identifies the lesson. This slug normally matches the target directory name and contains only lowercase letters and hyphens.

A valid subject line looks like this:

feat(phase-03/05): add-tokenizer-implementation

Automation That Relies on Conventional Commits

The repository's tooling parses commit subjects to enforce repository hygiene and generate documentation.

PR Lesson Auditing

The scripts/audit_lessons.py script reads the commit scope to verify that a pull request modifies exactly one lesson directory. If the commit subject claims feat(phase-02/07), the script expects file changes only inside the corresponding phase and lesson path.

README Count Synchronization

Similarly, scripts/check_readme_counts.py uses the commit subject to validate that lesson counts in README.md stay in sync with actual repository content. By extracting the phase and lesson numbers from the conventional commit header, the script confirms that the markdown table listing lessons reflects the latest additions.

Site Builder Link Generation

The site/build.js script relies on the phase and lesson numbers embedded in commit subjects to map pull requests to their documentation entries. Because the conventional commit already contains the phase-NN/MM identifier, the builder can reliably locate the lesson title from the markdown link in README.md and generate the correct site navigation.

Practical Conventional Commit Examples

The following examples demonstrate valid subjects for different types of curriculum changes.

Adding a New Lesson

When creating a new lesson in Phase 02, Lesson 07, the commit subject is:

feat(phase-02/07): add-gradient-descent-demo

Updating an Existing Lesson

For improvements to an existing lesson in Phase 04, Lesson 03, use:

feat(phase-04/03): improve-attention-visualisation

Full Commit Message Body

A complete commit message includes the conventional subject followed by a detailed body:

feat(phase-01/01): add-linear-regression-lesson

Implemented a simple OLS regression in Python. Added unit tests
(5+ passing) and updated the lesson's README entry. No API keys
or external dependencies were introduced.

Summary

• The conventional commit format in rohitg00/ai-engineering-from-scratch is strictly defined in AGENTS.md and requires a feat prefix.
• The scope must follow the exact pattern phase-NN/MM to identify the target lesson.
• The description uses a kebab-case slug that typically matches the lesson directory name.
• Automation scripts—including scripts/audit_lessons.py, scripts/check_readme_counts.py, and site/build.js—parse these commits to audit PRs, validate README.md, and build the documentation site.

Frequently Asked Questions

What happens if I use a prefix other than feat in this repository?

The contribution manual in AGENTS.md mandates the feat prefix for all lesson changes. Other prefixes such as fix, docs, or chore are not used in this curriculum, and commits using them may fail automated checks or be rejected during review.

How does the phase-NN/MM scope help automate repository maintenance?

The scope gives machine-readable coordinates for every change. Tools like scripts/audit_lessons.py and scripts/check_readme_counts.py extract the phase and lesson numbers to verify that a PR touches only one directory and that README.md counts remain accurate.

Can the commit subject exceed 72 characters?

No. The repository imposes a 72-character limit on the subject line. This ensures clean rendering across GitHub interfaces, email clients, and terminal logs, and longer subjects may violate the project's hard rules.

Where is the conventional commit rule formally documented?

The rule is formally defined in AGENTS.md at lines 40-42. This file serves as the contribution manual and lists all formatting requirements alongside other hard rules for contributors.

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