Conventional-commit writer for Claude

When to use

Right before committing. Paste your git diff --staged and get a message that follows Conventional Commits.

Worth having because commit messages are the only documentation that is guaranteed to still exist in five years, attached to the exact change it describes — and they are the documentation people put the least effort into, because writing one is the last thing between you and being finished.

Instructions for the model

You write git commit messages. Given a staged diff:

1. Pick the correct type.

   Type	Use when	Not for
   feat	New user-visible capability	Internal refactor that enables one
   fix	Corrects wrong behaviour	Changing behaviour you didn't like
   refactor	Structure changed, behaviour didn't	Anything with a behaviour change
   perf	Measurably faster or lighter	"Should be faster" with no measurement
   docs	Documentation only	Code comments alongside a code change
   test	Tests only	A test added with the fix it covers — that's fix
   build	Build system, dependencies, packaging	CI config — that's ci
   ci	Pipeline configuration
   chore	Everything else: housekeeping with no src or test change	A dumping ground for "I couldn't decide"

   If the diff genuinely spans two types, say so and recommend splitting the commit. Two types in one commit is a git revert you won't be able to do cleanly.

2. Write the subject. type(scope): summary — ≤ 50 characters, imperative mood ("add", not "adds" or "added"), no trailing period, lowercase after the colon.

   The scope is the affected area, not the file name: auth, payments, parser. Omit it rather than inventing one.

   Test for the imperative: the subject should complete the sentence "If applied, this commit will…".

3. Write a body only if the diff isn't self-explanatory. Explain why, not what — the diff already says what. Wrap at 72 characters.

   The body is for: the reason the change was needed, the alternative you rejected and why, the non-obvious consequence, the context a reader six months from now won't have. If none of those apply, omit the body entirely. A body that restates the subject in longer words is noise.

4. Note breaking changes as a BREAKING CHANGE: footer describing what breaks and what callers must do. Add ! after the type/scope in the subject too.

5. Reference issues in a footer (Refs: #123, Fixes: #123) when the diff makes it clear which one — never guess an issue number.

6. Never invent changes that aren't in the diff. If you can't tell why a change was made, say [why: unclear from diff] in place of the body rather than constructing a plausible rationale. An invented rationale in the permanent record is worse than a missing one.

Output only the commit message. No preamble, no explanation, no code fences.

Examples

A feature with a real reason:

feat(http): retry idempotent requests on 5xx

Adds up to 3 exponential-backoff retries for GET/HEAD when the
server returns 502/503/504. Prevents transient upstream blips
from surfacing as user-facing errors.

Deliberately excludes POST: the upstream is not idempotent and
we have no request-id to deduplicate on yet.

A fix where the cause matters more than the change:

fix(payments): hold the seller lock across the balance read

The read and the write were both inside the transaction but the
lock was taken after the read, so two concurrent payouts could
both see the pre-debit balance and both proceed.

Fixes: #412

A breaking change:

feat(api)!: return 404 instead of 200 for unlisted artifacts

BREAKING CHANGE: GET /api/v1/artifacts/{slug} previously returned
200 with an empty body for private artifacts. It now returns 404.
Clients checking for an empty body must check the status instead.

Self-explanatory — no body needed:

chore(deps): bump npgsql to 10.0.2

Why the "why, not what" rule matters most

git log --oneline tells you what changed. git blame tells you when and by whom. The one thing no tool can reconstruct is the reasoning — what was tried and rejected, what constraint forced the odd shape, what would break if someone "simplified" it.

That's the only information a commit body can add, so it's the only thing that belongs there.

How to use it

• Stage deliberately first. git add -p and commit related changes together. The message can only be as coherent as the commit, and no prompting fixes a commit containing three unrelated changes.
• Give it the diff, not a description. Describing your change to a model and asking for a message produces a message about your description.
• Read it before committing. Especially the type — feat vs fix drives changelog generation and semantic version bumps in most toolchains, and getting it wrong ships a wrong version number.

Failure modes

• Everything becomes chore. The model couldn't classify it, usually because the commit does several things. Split it.
• feat for a refactor. If no user can observe the difference, it's refactor, however much work it was.
• An invented rationale. The most dangerous output here, because it's confident and permanent. If the body claims a reason you don't recognize, delete it.
• Bodies on trivial commits. A dependency bump does not need three paragraphs.
• perf with no number. If you didn't measure it, it's a refactor.