I noticed something recently that I have not been able to stop thinking about.

Every engineer in our team has quietly built their own set of instructions for their AI tools. CLAUDE.md files, cursor rules, AGENTS.md, whole folders of skills. Little markdown files that say how to structure a migration, how to write a commit message, which patterns we avoid and why. Real judgement, written down properly for the first time in years.

None of it is shared. None of it is versioned. None of it survives the person leaving.

That is not a tooling problem. It is a much stranger thing than that, and it took me a while to name it.

What is actually in those files

For twenty years the knowledge that made an engineering team good was tribal. It lived in code review, in pairing, in the senior engineer who had been there six years and knew why we did not touch that service on a Friday. It transferred through people, slowly, by sitting next to the right person.

That knowledge is now being written down. Not because we finally got disciplined about documentation, but because an agent will not work well without it. The incentive changed, and suddenly everyone is documenting their judgment.

And here is the strange part. These files are not documentation in the old sense. Documentation waits for a reader. An agent reads them and acts on them every session, over and over. Which means every engineer on the team now carries a private, executable definition of good engineering. Twenty engineers, twenty definitions, all of them running.

We spent two decades getting rigorous about versioning our code. The thing that now writes a large amount of that code sits in a file on someone's laptop with no owner, no history and no review.

The fear is real, but we have misread it

A lot of engineers are uncomfortable with AI-generated code. The usual explanation is that they are protecting their craft or worried about their jobs.

I do not think that is it. In my team at least, the same engineers who hesitate to sign off agent code in review are often heavy users of it in their own work. The discomfort does not track usage. It tracks ownership.

They are being asked to own an artefact they did not reason about. Ownership moved up a layer, to the instructions, and most of us never gave them that layer to own. So they are left reviewing a stranger's code and being told to sign their name on it.

Give an engineer authorship of the instruction layer and the relationship changes. They are no longer reviewing a stranger. They are checking whether their own standard holds. That is a different job, and it is a much better one.

Fragmentation is the healthy phase

The instinct when you see twenty different setups is to centralise. One blessed repo, one house style, everyone conforms.

Resist that. Individual experimentation is how you find out what actually works. Standardise too early and you end up with a three-thousand-line style document that makes the output worse rather than better.

The failure is not that everyone has their own. The failure is that a pattern that clearly works for one engineer has no way of becoming something the whole team inherits.

The problem is not fragmentation. It is that there is no promotion path.

Three kinds of knowledge, not one

Here is where I got stuck for a while. I kept trying to fit everything into one artefact, and it kept feeling wrong. It is not one thing. It is three, and they behave completely differently.

Facts. What is true. The data model, the endpoints, the state machines, which flows exist and what happens when they run. The source of truth is the system itself: its code, schemas, contracts and configuration. Nobody should be authoring a second description of this by hand, because the moment they do, it starts drifting from reality.

Procedures. How we build. Standards, methodology, review process, what a pull request looks like, how we approach a migration. The engineering team is the source of truth. Human-written, deliberately opinionated, and slow to change. This is what those private files mostly contain today, and it is what skills are for: procedures packaged so an agent can execute them.

Intent. What we are trying to achieve. What the product is for, what it should always strive to be, and what we refuse to compromise on. Product leadership is the source of truth. It cannot be derived from the code, because the code is what we managed to build, and intent is what we meant.

Three layers, three different sources of truth, three different ways of going wrong. Treating them as one artefact was the mistake.

The part that does not exist yet

The mechanics of the procedures layer are mostly solved. Put the files in a repo, review them like code, give them owners. The governance is not solved. What earns promotion from personal practice to team standard, who decides, and how you keep the shared version from bloating into the style document nobody follows. That is the promotion path again, and it is organisational work, not tooling.

The intent layer is a writing problem. Hard, but not technically hard. Someone senior has to put into words what this product is for, properly, in a way an agent can read and a new engineer can argue with. I will come back to whose job that is.

The facts layer is the one I have not seen solved.

What I want is a knowledge base that regenerates from the codebase itself. Not a document somebody maintains. Something derived, so that after a change reaches production, the system description updates with it.

But I do not think you regenerate the whole thing every time. Most changes do not alter the shape of the system, and if you regenerate everything, you lose the signal. You cannot see what structurally changed because everything changed.

The version I keep coming back to is invalidation, not regeneration. I do not want documentation that constantly rewrites itself. I want documentation that knows when it might be wrong. A change to a rate calculation should not regenerate the description of the whole platform. A removed endpoint, a changed state transition, a moved domain boundary- those should mark the matching knowledge stale and surface as a diff a human actually looks at.

Because a generated description that quietly drifted is worse than no description at all. The agent will not hesitate. It will confidently build on something that stopped being true three sprints ago.

The tools I have seen circle this without landing on it. Some regenerate a wiki for the whole repo on demand, which is the lose-the-signal problem again. Some watch the code and flag human-written docs as stale, which assumes a human wrote the docs in the first place. I have seen pieces of it. I have not seen the version I want.

Where it gets interesting

If you have derived facts on one side and written intent on the other, you can compare them.

Facts tell us what the system does. Intent tells us what we meant it to do. The system does X; we said it should do Y. That gap is not a bug in either layer, and it is not documentation drift. It is product debt, surfacing on its own, without anyone having to remember to look for it.

That is the version of this I actually want. Not better management of what gets generated. A system where the gap between what we built and what we meant becomes visible by default.

The layer I owe my engineers

Now look at who owes what.

The facts layer can be derived, and it is the one nobody enjoyed writing anyway. Let it be derived.

The procedures layer belongs to engineers, and they have already half written it. It is sitting in those private files. Craft did not disappear; it got written down, and writing it down is harder than holding it in your head, because now it has to be defensible to someone else.

The intent layer belongs to product leadership. That is my function, and if I am honest, it is a debt we have mostly never paid. We write strategy decks and roadmaps for executives, and almost nothing an agent could read or an engineer could hold us to. The layer your agents are missing is the one my function never wrote down.

So the useful division is this. Engineers own the promotion path for procedures, because their judgement is being promoted. Leadership owes them the intent, written properly. Both layers get versioned and stay open to challenge. Neither writes the other's layer. The proportion of the job that is judgement went up on both sides.

Where I have landed

We are at the point where this has to come together. Every engineer holding their own private instruction layer worked fine as an experiment. It does not work when it is how the software gets built.

So we are versioning the procedures; I am writing down the intent, and I am still looking for the right answer to the facts.

If you have solved the third one, I would really like to hear about it.

‍