vidimitrov

"Expertise" is a completely different beast from "knowledge".

Expecting to gain it from a model only through prompting is similar to expecting to become capable of something only because you bought a book on the topic.

That’s cool. But how does it work in agentic environment? Do you get any benefit from it? Or it’s intended only for humans to read?

The “deterministic enforcement” is exactly what this enables but its not the responsibility of the spec to say that. Its harnesses or IDEs or you own implementation that will enforce that.

Issue trackers are full of intent and decisions, that's true, but that's not the point here... It's about a storage that agents can use natively without the need of callings external APIs or MCPs.

And there is a slight difference between what you capture in issue trackers and what happens in reality in coding sessions.

This looks very good. Thanks for sharing. I can only imagine how much discipline it takes to write these kinds of commits manually.

The format is optimised for agent querying and human readability in `git log`, not for `git interpret-trailers` compatibility. Those are different use cases.

Trailers were not suitable for the use case.

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.

The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT.

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.

A few examples are the ability to query historical data and using each action line as a signal for other tooling to build on top but there are many others… you can check what Conventional Commits did in the past and what they unlocked only by introducing structure to commit subjects

That’s exactly the direction I went with. Working on a spec for exactly this - planning to post it here soon:

https://github.com/berserkdisruptors/contextual-commits

Nope - though I’ll take it as a compliment either way. It’s a problem I’ve been sitting with for a while, so the answer came out more formed than I expected. You disagree?

He admits the real hole himself: "this doesn't catch spec misunderstandings. If your spec was wrong to begin with, the checks will pass."

But there's a second problem underneath that one. Acceptance criteria are ephemeral. You write them before prompting, Playwright runs against them, and then where do they go? A Notion doc. A PR comment. Nowhere permanent. Next time an agent touches that feature, it's starting from zero again.

The commit that ships the feature should carry the criteria that verified it. Git already travels with the code. The reasoning behind it should too.

Level 4 is where I see the most interesting design decisions get made, and also where most practitioners take a shortcut that compounds badly later.

When the author talks about "codifying" lessons, the instinct for most people is to update the rules file. That works fine for conventions - naming patterns, library preferences, relatively stable stuff. But there's a different category of knowledge that rules files handle poorly: the why behind decisions. Not what approach was chosen, but what was rejected and why the tradeoff landed where it did.

"Never use GraphQL for this service" is a useful rule to have in CLAUDE.md. What's not there: that GraphQL was actually evaluated, got pretty far into prototyping, and was abandoned because the caching layer had been specifically tuned for REST response shapes, and the cost of changing that was higher than the benefit for the team's current scale. The agent follows the rule. It can't tell when the rule is no longer load-bearing.

The place where this reasoning fits most naturally is git history - decisions and rejections captured in commit messages, versioned alongside the code they apply to. Good engineers have always done this informally. The discipline to do it consistently enough that agents can actually retrieve and use it is what's missing, and structuring it for that purpose is genuinely underexplored territory.

At level 7, this matters more than people expect. Background agents running across sessions with no human-in-the-loop have nothing to draw on except whatever was written down. A stale rules file in that context doesn't just cause mistakes - it produces confident mistakes.

* * *