AI Rules for Commit Message Format

Commit Message Format Rules for AI Tools

The conventional commits format: the most widely adopted standard for AI-generated commit messages. AI rule: 'Commit messages follow conventional commits: type(scope): description. Types: feat (new feature), fix (bug fix), refactor (code change that neither fixes nor adds), test (adding tests), docs (documentation), chore (build/tooling). Scope: the module or feature affected (auth, payments, ui). Description: imperative mood, lowercase, no period, under 72 characters.' The AI: generates commit messages that are consistent, parseable, and informative.

Why format matters for AI-generated commits: AI tools like Claude Code can create commits automatically as part of multi-step workflows. Without commit message rules: the AI generates generic messages ('update code', 'add changes', 'fix stuff'). With rules: the AI generates descriptive, conventional messages ('feat(notifications): add preference toggle endpoint with zod validation'). The commit history: readable, searchable, and useful for changelogs. The rule: one line in CLAUDE.md that transforms the entire git history quality.

Common AI commit message mistakes that rules prevent: messages that are too vague ('update files'), too long (entire paragraphs in the subject line), wrong tense ('updated' instead of 'update'), or missing scope. AI rule additions: 'Subject line: imperative mood (add, not added or adds). Maximum 72 characters. No period at end. Body: wrap at 80 characters. Explain WHY, not WHAT (the diff shows what changed).' These specifics: eliminate the most common AI commit message quality issues. AI rule: 'Commit message rules are the highest-impact one-line addition to CLAUDE.md. One rule transforms every commit in the project's history from generic to informative. The effort: 1 minute to write. The return: every commit, forever.'

Scope and Type Conventions

Defining scopes for your project: AI rule: 'Commit scopes match the top-level source directories: auth, api, ui, db, config, tests. For cross-cutting changes: use the most affected module. For infrastructure: use infra. For CI/CD: use ci.' The AI: uses the correct scope because it knows the project's scope vocabulary. Without defined scopes: the AI invents scopes ('fix(thing): update the stuff') or omits them entirely. The scope list: a simple enumeration in CLAUDE.md that produces dramatically better commit messages.

Type selection rules: the AI sometimes struggles to choose between feat, fix, and refactor. AI rule: 'feat: adds a capability that did not exist before (a new endpoint, a new UI component, a new configuration option). fix: corrects a bug (something that was supposed to work but did not). refactor: changes implementation without changing behavior (same tests pass before and after). If unsure: prefer feat for additions, fix for corrections, refactor for rewrites.' The decision tree: eliminates type ambiguity. The AI: selects the correct type consistently.

Breaking changes and versioning: AI rule: 'Breaking changes: add BREAKING CHANGE: in the commit body (not subject). Also add ! after the type: feat(api)!: rename user endpoint to accounts. The body explains: what changed, why, and how to migrate. Breaking changes trigger a major version bump in semantic versioning.' The AI: properly documents breaking changes when it modifies public APIs. The changelog generator: picks up BREAKING CHANGE commits automatically. The team: never ships an undocumented breaking change. AI rule: 'Scope and type conventions give structure to commit history. The scope: tells you where the change happened. The type: tells you what kind of change it is. Together: the commit subject is a complete summary that a developer can understand without reading the diff.'

Commit Body Content Standards

When to require a commit body: AI rule: 'Commit body required for: feat commits (explain what the feature does and why), fix commits (explain what was broken and how it was fixed), and any commit touching more than 5 files (explain the scope of changes). Body not required for: single-file refactors, test additions, documentation updates, and config changes.' The rule: ensures bodies appear where they add value and are skipped where they add noise.

Body content structure: AI rule: 'Commit body structure: 1) What changed (1-2 sentences). 2) Why it changed (the motivation — a bug report, a feature request, a performance improvement). 3) How to verify (run this test, check this endpoint, verify this UI state). Wrap at 80 characters. Separate subject from body with a blank line.' The structured body: makes commits self-documenting. A developer reading the git log: understands the change, its motivation, and how to verify it without opening the PR.

AI-specific body content: for AI-generated code, consider adding a note in the commit body about the generation process. AI rule: 'For AI-generated commits: add a line "Generated with [tool] and reviewed by [developer]." This is optional but helps with codebase archaeology — when someone reads the commit 6 months later, they know the code was AI-generated and reviewed, not hand-written.' The transparency: builds trust in the git history. The archaeology: helps future developers understand the code's origin. AI rule: 'Commit body standards ensure that the git log is useful long after the PR is merged. The subject: answers WHAT. The body: answers WHY and HOW TO VERIFY. Together: the commit is a self-contained record of the change.'

Automating Commit Message Quality

Git hooks for commit message validation: AI rule: 'Use commitlint with conventional commits config in a pre-commit hook. Reject commits that do not match the format: type(scope): description. The hook: catches malformed messages before they enter the history.' The hook: works for both AI-generated and human-written commits. The enforcement: automatic and consistent. Note: the AI should know about the hook so it generates compliant messages: 'Commit messages are validated by commitlint — follow conventional commits format exactly.'

Changelog generation from commits: AI rule: 'Changelogs are auto-generated from conventional commits. feat → Features section. fix → Bug Fixes section. BREAKING CHANGE → Breaking Changes section. Keep commit messages user-facing (describe the impact, not the implementation). Bad: "refactor auth middleware to use new token parser." Good: "feat(auth): add support for OAuth 2.0 social login providers."' The AI: writes commits that serve double duty — useful in git log AND useful in the changelog. The changelog: auto-generated without manual editing.

Multi-commit feature development: AI rule: 'For features requiring multiple commits: use consistent scopes. First commit: feat(notifications): add notification preferences schema. Second: feat(notifications): add notification preferences API endpoint. Third: feat(notifications): add notification preferences UI component. Fourth: test(notifications): add integration tests for preferences flow. The scope: ties related commits together. The types: show the progression from schema to API to UI to tests.' The AI: generates a coherent commit narrative for multi-step features. AI rule: 'Automation transforms commit message rules from discipline into infrastructure. The commitlint hook: prevents bad messages. The changelog generator: rewards good messages. The automation: makes following the rules easier than breaking them.'

Commit Message Rules Quick Reference

Quick reference for AI coding commit message rules.

• Format: type(scope): description — conventional commits, under 72 characters, imperative mood
• Types: feat (new capability), fix (bug correction), refactor (same behavior), test, docs, chore
• Scopes: match top-level directories (auth, api, ui, db) — define the vocabulary in CLAUDE.md
• Breaking changes: feat(api)!: description + BREAKING CHANGE: in body with migration guide
• Body required for: feat commits, fix commits, and changes touching 5+ files
• Body structure: what changed, why it changed, how to verify — wrap at 80 characters
• AI attribution: optional 'Generated with [tool], reviewed by [developer]' line in body
• Automation: commitlint hook for validation, conventional-changelog for auto-generation