Skip to content
Back to blog
•4 min read

I Thought We Had All This Understood

An agent offered me a choice we had already made and written down. Pulling that thread led to an old habit of the trade: the people who build a system are the ones who understand it.


Some months into building a system with coding agents, an agent offered me a choice I had already made. The decision was written down, with its reasons, the options we had rejected and how we made the decision, in an architecture decision record meant to save whoever comes next from rediscovering why.

My reply was "I thought we had all this understood."

The "we" in that sentence was doing a lot of work. The session I had worked with was long gone; however, the decision itself had survived in documentation and an architecture decision record. What had not carried over was the working context that made the decision look obvious: the constraints we found along the way, the approaches that seemed reasonable until they were not, and the sense of which questions were already settled.

This comes up a lot, and is usually put down to agent memory or some compaction forgetfulness, but I think it also shows how much rested on an older habit of the trade: the people who built a system came to instinctively understand it by building it.

My memory is a sieve, and so is the agent's

There are many ways people try to preserve this context: saving transcripts, summarising sessions, writing decision records, and loading it all at the start of the next session. And much of that is definitely worth doing!

But there are still gaps.

Some of the gaps were my fallible brain forgetting a key detail, and others were agents proposing changes that contradicted decisions we had already made, or forgetting hard-earned lessons along the way. I knew what was right without remembering why, the documents remembered why without knowing what mattered, and the agent then rebuilt what knowledge it could from history and documents, but missed some of what mattered.

Thoughts from the 80s

Continuity of context and continuity of understanding are related, and they come apart. Peter Naur made a version of this argument in 1985, in Programming as Theory Building(opens in a new tab). He held that the understanding behind a program lives with the people who built it, and that "the program text and its documentation has proved insufficient as a carrier of some of the most important design ideas", and that rebuilding it from the documentation alone is "strictly impossible".

In the exchanges I have been describing, the understanding and context needed was in no single place (and honestly, with AI I'm tending to work on many things at once, so my share of it was patchy). Some of that understanding was with me, some was in what we had written down, and some the agent reconstructed each time from documentation that seemed clear enough when I wrote it. A decision record, or a full transcript, is cheap to keep, but both are lossy. Whether either can reproduce the ability to reason well about the system and join the dots is a separate question, and I do not think anyone knows the answer yet.

Before and now

In the before times, when an engineer made a change, an organisation usually got two things. The software changed (hopefully for the better), and someone learnt something about it.

With coding agents, the one doing the work still builds up a working context, and much of what it does never appears in the diff. It reads code, follows a dependency, finds a constraint nobody wrote down, tries an approach that fails, and uses all of that to work towards the outcome. Then the session finishes. Throwing back to Programming as Theory Building, it's a small version of an engineer leaving a team whenever a session ends and taking their context with them, several times a day. Acknowledging though, that an agent onboards much faster than a new team member!

Who knew

There was no "we" that had all this understood. There was me, the documents, and an agent that would be gone by the next session, and none of us had the whole story.

The habits of the trade assume the understanding comes free with the building. With agents it doesn't, so something has to hold it on purpose. I thought we had all this understood.