I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff.
This was helpful when humans were the only ones reading the history. But for agents its useless.
You may not have seen enough good repos. The following is an example commit from freebsd
https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903...
A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more details in the body. I strongly believe that people who write the WHAT again don’t know that there’s a diff attached to the commit and think of them a separatete objects. GitHub and VSCode do not really help in that regard.
But also, if you look at large projects like Linux or FreeBSD, commits there explain why as well.
To that end you will want to provide a validating parser and then start rejecting commits whose messages don’t validate. If your validator has even one or two bugs you’re going to see all goodwill evaporate, and for what? So that you could read:
bug(fix)[8177] Add missing paren
Add missing paren
…
Fixes http://bugs.com/8177
It was enraging - I'm trying to provide references to explain the motivation of my changes, all my prose is nicely formated, but the bulleted list of references I've provided is rejecting my commit.
I generally think it's in the category of a social problem not a technical problem - communicate the expectations but don't dogmatically enforce them
The example of using one library over another, especially if research has gone into which to choose, regularly involves say finding a good article that compares the alternatives.
I’ll say though that I usually include links to more notable references, I won’t usually commit refs to a libraries own docs and more obvious stuff; revealing and keeping references to resources found that went towards getting it done are what I keep and add to commit body.
Maybe there’s spaces for useful references to be added to the spec/conventions. Personally I usually show links like this after the body message.
Example of the commit body:
refs(oath-library):
www.something.com/picking-a-thing
This gives product owners the ability to embellish as they wish and reduces the need of the dev to repeat themselves.
But, perhaps the IDE could retrieve the details of the jira card, and help pre-generate the commit message from it.
If only tickets would be part of the repository itself from the beginning, that would be much simpler IMO.
Giving agent scoped access to ticket system. Whis is this obvious answer not the obvious solution?
Your 'intent' is 'users need social login'? That does not make sense.
Your intent is 'Getting more users by lowering barriers to sign up', a business goal. That business goal might have hierarchical children – for example, Jira epics – such as 'offer social sign-in', or 'declutter landing page.'
Also, the commit mentions 'Google before GitHub', but how can a commit (a snapshot of the repository) know the future? What if your product manager decides Google is fine enough and GitHub/Apple aren't needed?
I wish our profession would stop trying to reinvent issue tracking in git every week.
By having a structured context of the key session discoveries, decisions, rejected items (if there were past commits with decisions that had been rejected, etc..) you achieve a type of contextual storage of the reason, thus after a month, when a team member wants to start working on a task that you have touched, and now forgot since you are doing ai-assisted coding and pr throughput is to sky right now, your collegue at least will know the rational behind the decission and working with his agent, the agent will produce more reliable code not introducing something for the sake of solving the task.
Important point.
But it says more about OP’s perspective on product-driven development than this “contextual commits”.
The idea that OP does not follow up on is whether these codified commit messages with a very shallow summary of the LLM context improve anything compared to the normal commit messages that Claude will generate.
I suspect they’re equally insufficient since even a compacted context seems less diffusing and it’s still a lot bigger than these.
> I wish our profession would stop trying to reinvent issue tracking in git every week.
I would love to have good git-powered issue tracking. I haven’t seen it yet.
Agentic coding keeps reinventing coding.
That was my first thought.
> And then it hit me - the commit body has always been there. Completely underutilised.
Wait. What? This is the standard?
> Here is an example of how a Contextual Commit looks:
The format is key-value stuff. You can already use trailers for that. The syntax here doesn’t work with that stuff.
If you have already readh the “conventional commits” (pronounce with a sneer) specification you have already seen them. They’re called footers because they also didn’t know about trailers.
> No new tools. No infrastructure. Just better commits.
Okay, let’s cut right to the point..
The scope in parentheses is doing real work. `rejected(oauth-library)` lets you do `git log --grep="rejected(auth"` to find every rejected auth decision across history.
If you flatten it to a trailer token you either lose the scope or encode it awkwardly as `Rejected-auth-oauth-library: value`, which doesn't grep cleanly and doesn't parse naturally.
I'm 99% sure that grep won't find your commit because you rejected "oauth-library" and grepping for "auth" rejection. Given that LLM will make up category name, it will just get worse unless there is deterministic enforcement.
All of this really feels like people that never wrote code starting doing it via agents and started reinventing already solved issues.
Rejected: (auth-library) ...
?