Software has a metaphor problem, and grappling with it is key to unlocking the future of agentic coding.

For the longest time, the dominant metaphor for software has been software-as-physical-buildings. We say that we “build” software, and before we write code, we “architect” it. This metaphor has a lot going for it. A software project, like a building project, is functional, artistic, and collaborative. Another metaphore is the software-as-literature metaphor, hence the terms “writing code” and “programming language”. But when we think about managing software, the building metaphor dominates. We measure functionality delivered, team velocity, etc.

But this metaphor doesn’t capture how rapidly software changes. We expect software projects to release new code pretty often - sometimes multiple times a day. Buildings change too, but very slowly and with a lot of effort. Literature, too, doesn’t actually change that much - most novels don’t get multiple editions, and even blog posts don’t change all that much after they’re published.

This problem is the fault line in agentic coding. Which is a fancy way of asking: how are we supposed to maintain AI-generated code in the long term?

The emerging consensus seems to be that we should aim to create an “agentic loop”, in which the software engineer guides the coding agent through a research-plan-test-implement pipeline. By monitoring the agent’s progress, the engineer ensures the agent doesn’t go off-track, while retaining familiarity with the code base. It’s a reasonable approach to the problem, and as a bonus it produces source-controlled implementation plans.

Still, I think the long-term maintenance question is far from settled. Fundamentally, it’s a matter of preserving what Peter Naur calls the “shared mental model” of a code base, in a way that the model can be readily extended into the future.

The building metaphor is failing us when it comes to encoding and extending a shared mental model - buildings don’t really need constantly-changing shared mental models, because buildings don’t change all that often. In software, the best way we’ve thought to encode shared mental models is to create documentation. We’ve tried that, six ways to Sunday, and it’s never quite sufficient. The agentic loop, and its predecessor like AGENTS.md, are essentially resting on that shaky foundation. (There’s the building metaphor again!)

In a way, we are rediscovering some of the fundamental problems of software, and we’re coming to grips with the fact that we don’t really understand it. It’s time to find a new metaphor for this thing we’ve been practicing for seven-some decades!

Also find this post on LinkedIn!

Image courtesy of Tamara Menzi