Writing Commit Messages and PR Descriptions with AI

Let's admit something first: the vast majority of developers' commit messages are garbage. fix bug, update, wip, 111, final final v2—we've all written them. PR descriptions aren't much better: either completely blank or a single line like "tweaked the login."

This isn't an attitude problem; it's an economics problem. The payoff of a good commit lies in the future (troubleshooting a production incident six months later, onboarding new hires, writing the changelog at release), while the cost is paid now (I just want to push and go home). Humans are naturally short-sighted, and AI happens to compress that "present cost" to near zero. This article explains how to use AI to turn commit messages and PR descriptions from a burden into an afterthought.

1. Why commit messages and PR descriptions deserve real attention

In one sentence: git log is a project's most honest chronicle, and the PR description is the preface to each chapter. Code gets refactored, documentation goes stale, and architecture diagrams lie—but commit history faithfully records "who, when, and why this line of code changed."

It has three irreplaceable values:

• Traceability: when production blows up, git bisect or git log -S pinpoints a commit; a message that explains "why it changed" can save your evening, while a fix bug makes you tear your hair out.
• Collaboration: reviewers read a PR by looking at the description before the diff. A clear description doubles review efficiency and saves you from re-explaining the motivation in the comments.
• Releases: release notes, changelogs, and external announcements all originate from commits and PRs. If the source is bad, everything downstream is fabricated.

The reality: everyone understands these truths, but facing a deadline nobody wants to spend three minutes organizing their words. So the solution isn't "educate developers" but lower the cost of writing them to near zero—which is exactly AI's job.

2. AI-generated commit messages: let the diff speak for itself

The core mechanism behind AI-generated commits is plain: feed the staged diff to the model and have it output a spec-compliant message. The key isn't "AI"—it's "spec-compliant."

The de facto industry standard is Conventional Commits, which looks like this:

<type>(<scope>): <subject>

<body>

<footer>

• type: feat / fix / perf / refactor / docs / test / chore / build / ci / style / revert
• scope: the affected module (optional but strongly recommended), e.g. auth, checkout, db
• subject: imperative mood, present tense, no longer than 50 characters, no trailing period
• body: explains "why" rather than "what changed" (the diff already shows what changed)
• footer: use BREAKING CHANGE: for breaking changes, and Closes #123 to link issues

The prompt given to the AI roughly follows this pattern (pseudocode):

You are a senior engineer. Below is a git diff. Please generate a Conventional Commits-format commit message.
Requirements:
1. type must be chosen from [feat,fix,perf,refactor,docs,test,chore,build,ci,style,revert]; do not invent.
2. Infer scope from the affected module; omit if uncertain.
3. subject no longer than 50 characters, imperative mood, no trailing period.
4. body explains motivation and impact; may be omitted for simple changes.
5. If there is an API/behavior incompatibility, the footer must start with BREAKING CHANGE:.
6. Output only the message itself; do not explain.

<diff>
{{ diff content }}
</diff>

The real diff is the anchor—without it the AI can only guess; with it, the message it generates is more disciplined than what most people write by hand. For example, if you change the token-refresh logic in src/auth/jwt.ts, the AI will produce fix(auth): proactively refresh the token before it expires to avoid concurrent-request 401s—ten times more informative than struggling to come up with "fix token."

There are plenty of ready-made tools: aicommits (open-source CLI, npm i -g aicommits), opencommit, or simply asking Claude Code / Cursor to read git diff --cached and generate one. The underlying mechanism is the same: diff in, message out.

3. AI-generated PR descriptions: four required blocks

PR descriptions matter more than commit messages because they have to convince someone to merge your code. I use a fixed template, and the AI fills it in accordingly:

## Motivation
Why make this change? What problem does it solve? Link the issue / design doc.

## Main changes
- What changed (high-level summary, don't restate the diff)
- Any behavior change

## How it was tested
- How was it verified? Which tests were run? Which scenarios were manually validated?

## Risks / Breaking changes
- What might be affected? Any incompatibilities?
- Rollback plan

These four blocks correspond to the four questions in a reviewer's mind: why change, what changed, is it reliable, will it break things. None can be missing.

AI's value here isn't just "writing text"—it's forcing structure. A PR description you dash off easily omits the "risks" section, but the AI dutifully fills it in every time—even "this change has no breaking risks" beats a blank, because it forces you to think for a second.

The input to the AI should be the PR's full diff (gh pr diff or git diff main...feature), plus the PR title and a brief summary of the linked issue. The output is the structured template above.

4. Integrate it into git hooks, CLI, and CI

A prompt alone is useless—it has to run automatically "at the right moment." Three integration points:

1. git hook: auto-generate via prepare-commit-msg

The prepare-commit-msg hook fires before the editor opens—perfect for pre-filling the message. The script looks roughly like this (place it in .git/hooks/prepare-commit-msg, or manage it with husky/lefthook):

#!/bin/sh
COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

# For merge / squash / cherry-pick and similar scenarios, pass through directly
[ -n "$COMMIT_SOURCE" ] && [ "$COMMIT_SOURCE" != "template" ] && exit 0

DIFF=$(git diff --cached)
[ -z "$DIFF" ] && exit 0

# Call AI to generate, write the result to COMMIT_MSG_FILE
echo "$DIFF" | ai-commit > "$COMMIT_MSG_FILE"

# Open the editor for you to review, instead of committing directly

Note one detail: this hook only pre-fills—the editor still opens and you have a chance to edit. This matters: AI is an assistant, not autopilot; more on this below.

2. CLI: manual trigger, good for trying it out

If you don't want to modify hooks right away, you can run it manually with a CLI first:

git add -p
git diff --cached | ai-commit | git commit -F -   # Use the output directly as the message

Or more simply, in Claude Code just say "write a commit based on the current staged diff," and it will give you the message; you commit after confirming.

3. CI: auto-comment on PR creation

At the team level, CI is the most useful. When a new PR is opened, run a job that reads the PR diff, generates a structured description, and posts it as a comment (rather than overwriting the author's body—this is just polite):

# .github/workflows/ai-pr-description.yml
name: AI PR Description
on:
  pull_request:
    types: [opened]

jobs:
  describe:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Generate and comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          gh pr diff ${{ github.event.pull_request.number }} > pr.diff
          DESCRIPTION=$(ai-pr-describe < pr.diff)
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "$DESCRIPTION"

A new hire opens a PR on day one and CI automatically fills in a decent description—the team's review experience immediately levels up.

5. Quality control: don't give AI free rein

The root cause of AI commit failures is always the same: making things up without the diff. A few iron rules protect quality:

1. Must be based on the real diff. Don't generate without a diff—better to leave it blank. This is the fundamental defense against hallucination.
2. Strict format constraints. Whitelist the type, cap the subject length, make the body optional. Validate with a schema; reject anything that doesn't fit.
3. Human-editable, and must remain editable. AI output is always a draft; the editor/comment area must leave room for the author to modify it. I've seen teams set the hook to "commit directly without opening the editor after generation," and after launch hallucinated messages slipped into the main branch—at a loss.
4. Split large changes into multiple commits, then generate for each. One commit stuffed with refactor + new feature + bugfix can only get a vague feat: major overhaul from the AI. The right approach is git add -p to break the change into fine-grained pieces and feed each atomic commit to the AI individually—this is where it performs best.

6. Pitfalls: hallucination, over-detail, missing breaking changes

After using it for a while, you'll hit three pitfalls:

• Hallucination: the AI occasionally "completes" changes that aren't in the diff, e.g. the message says "also fixed the cache-invalidation logic," but the diff never touched the cache. Countermeasure: when reviewing, compare the message against the diff, and delete anything that isn't in the diff.
• Over-detail: listing every filename and variable, turning the body into a natural-language translation of the diff. A good message explains "why," not "which lines changed." Adding "do not restate the diff" to the prompt helps.
• Ignoring breaking changes: this is the most dangerous. The AI tends to report good news and bury bad news, downplaying incompatible changes like removed fields or changed return values as refactor: clean up the interface. Countermeasure: heavily penalize in the prompt—"any change that might affect callers must be flagged in the footer with BREAKING CHANGE; false positives are acceptable, false negatives are not."

In one sentence: AI-generated commits and PR descriptions must be reviewed, as carefully as you review code.

7. Advanced: auto-generate release notes from a set of commits

Once commits are standardized, the biggest dividend pays out at release time. Feed all the commits between two tags to the AI:

git log v1.4.0...v1.5.0 --pretty=format:"%s%n%b" > commits.txt
ai-changelog < commits.txt > RELEASE_NOTES.md

Let the AI aggregate dozens of commits into human-readable prose:

## v1.5.0

### New features
- Support resumable uploads; large file uploads can resume after interruption

### Fixes
- Fix intermittent 401s caused by a token-refresh race under high concurrency

### Breaking changes
- In the `getUser()` return structure, the `name` field is renamed to `displayName`; existing code needs to adapt

This is the flywheel of Conventional Commits + AI: spend 5 extra seconds per commit generating a standardized message, and save two days of changelog writing at release time. Discipline at the source, dividends downstream.

Summary

• Commit messages and PR descriptions are a project's most underrated documentation, valuable for traceability, collaboration, and releases; the pain point is "high present cost." AI compresses that cost to near zero—one of the highest-ROI applications of AI in coding.
• The mechanism is plain: real diff in, spec-compliant message out. The anchor is the diff; the spec is Conventional Commits.
• PR descriptions have four fixed blocks: motivation, main changes, how it was tested, risks/breaking changes. AI's value isn't just writing—it's forcing structure.
• Three integration points: pre-fill via the prepare-commit-msg hook, manual trigger via CLI, and CI auto-commenting on PR creation.
• The iron rule is review: anchor on the real diff to prevent hallucination, enforce strict formats, keep it human-editable, and split large changes. AI is an assistant, not autopilot.

A closing line: letting AI write commits isn't laziness—it frees engineers' mental energy from "organizing words" for the "why change" that really deserves thought. Discipline at the source, dividends downstream—this investment always pays off.