How to Write Good Commit Messages for a Fix, Feature, or Mixed Change

A short commit message can be more useful than a detailed one. After an AI-assisted build session, the choice depends on what changed and what you will need to understand later. Learning how to write good commit messages starts with deciding whether the commit represents one clear action, a decision that needs context, or several changes that should be separated before you save them.

Does this commit make one obvious change?

If the diff does one thing, lead with that thing. “Fix invite form validation” is easier to scan than “Updates” or a sentence recounting every prompt you used. Use a verb and a specific object so future you can recognize the change in a history view.

Open the diff before you write the message. AI coding tools can touch nearby files you did not intend to change, and a label based only on your original prompt may misdescribe the result. When the diff matches one focused task, a concise subject line is enough. Commit it with a message such as “Prevent duplicate invite submissions.”

Did you make a choice that the diff cannot explain?

Some changes have a reason that code alone will not preserve. Perhaps you kept a simple form flow instead of adding a new dependency, or changed how an internal tool handles an empty result. The subject should still say what changed. Add a brief message body explaining why when that reasoning would save you a future investigation.

For instance, the subject might be “Keep search filters in the page URL.” The body can say, “Preserves the selected view when someone shares a link.” That is enough context to evaluate the choice later. If the implementation also affects permissions or database writes, review and test those behaviors before committing. A well-written message cannot make an unchecked change safe.

Does the diff contain unrelated changes?

A single AI session can fix a bug, rename components, and adjust styling. One message cannot make that history easy to navigate. Separate the changes into commits when they stand on their own, then name each by its result. If you cannot separate them cleanly because the work is unfinished, pause and inspect the diff before recording it as a finished change.

For a small SaaS build, that might mean committing “Fix account settings save error” separately from “Tighten settings page spacing.” The distinction helps when you need to find the regression later. It also forces a useful check that the styling edit did not quietly alter the save flow.

Are you recording a partial build or a finished result?

A work-in-progress commit can be useful when you need a recoverable point before switching tasks. Say what state you are saving instead of presenting it as a complete feature. “Start CSV import flow” sets a different expectation from “Add CSV import,” especially if parsing and error handling still need work.

Before you stop, note the remaining task in plain language. A commit records the code state; a separate project note can hold the next action and any prompt that solved a difficult issue. That distinction makes it easier to resume without stuffing your entire todo list into the commit message.

To record tested state and the next action outside your commit, use this checklist for handoff notes between AI coding sessions.

What should you write before your next build session ends?

Review the diff, name the result, and add a reason only when the change needs one. If you see unrelated work, split it before choosing a message. You should be able to read the subject later and know which change to inspect.

Keep the unfinished work and useful prompts next to that code history with a project journal in VibeCrumbs. Your commit can stay focused while your next session has a clear place to begin.