In 1985, Peter Naur published Programming as Theory Building. The core idea: the real artifact of programming isn’t the source code. It’s the theory the programmers hold in their heads. The mental model of why the system is the way it is, what it’s trying to do, and what will and won’t work inside it.

To rephrase Naur’s point: a programmer’s ability to modify a codebase depends directly on their ability to understand it, and the why behind it. Without the theory, you’re just tinkering with source code, likely missing the how&why that makes the code the most useful, and relying on hope.

Forty years later, that paper reads less like a historical artifact and more like a warning label for how we’re building software right now.

If your coding agent is the programmer, it needs the theory too

In a world where coding agents are handling most (if not all…) of the implementation work, then they are programmers in Naur’s model too. Which means an agent’s ability to implement a modification depends directly on its theory of your software’s world. You can already see the point I’m making… the theory is in your head, not the agent’s.

You might reasonably say: “It’s fine… Claude can just go figure out whatever it needs. It’ll grep the repo, read the files, infer the patterns.”

True. It can. And it will. Three problems that stood out to me as I re-read Naur this past week were that 1) theory is more than just what is included in the source code, and often more than what’s included in most team’s docs, 2) every instance of Claude, every new session, every parallel agent, every teammate’s chat window, may discover something slightly different… all your agents are working from a different source of truth, and 3) if you have the theory to verify against and your agents are throwing thousands of lines of diffs at you each day, there’s no reasonable way for you to actually review for alignment.

Just-in-time documentation is not an effective solution

The “let the agent figure it out” approach has real costs:

• Every session pays the discovery tax. Tokens, time, and reasoning effort spent re-deriving facts that were already known and written down somewhere (or should have been).
• Discoveries disagree. Two agents looking at the same ambiguous codebase will reach different conclusions about intent. Both conclusions will feel confident. Only one (at most) is right.

When that happens.. now drift between expectations and reality become inevitable, and you end up feeling like you’re playing whack-a-mole. If you need consistency, reliability, and trust in your system, this is inefficient, chaotic, and maybe even a nonstarter.

That’s not a coding agent problem. It’s a process problem and a data problem.

Human teams solved a version of this problem decades ago by writing things down. Architecture docs. ADRs. Decision logs. RFCs. Onboarding guides. These were a way to capture a shared, stable theory of the system that new programmers could load into their heads without having to reverse-engineer it from scratch. Then they’d use their theory to guide their design, implementation, and review.

Theory building comes before theory verification

Effectively using a theory to guide software development means two things: theory building and theory verification. As mentioned above, we’ll get into the verification side in a follow-up post. The point here is that you have to start with theory building otherwise there’s nothing to verify against.

Table stakes is live technical documentation: descriptive docs about the system as it is today.

Once you have that, you can add on top guiding principles, goals, and constraints — the things that define your trajectory and your boundaries. The “why we did it this way” and the “why we won’t do it that way.”

It’s the same kind of theory and context you’d hand to a new teammate on day one. It may not feel like all this big-picture stuff is relevant to your agent, but we know it makes them better. In our own studies, we’ve seen agents use 45% fewer tokens and score higher on code review when using gjalla than without.

When agents have access to the theory, and a way to check their work against it, humans (the ones who actually hold the theory in their heads) judge the output as more aligned. Not because the model got smarter. Because it had more the guiding theory that humans have always had.

Ok… so?

The theory you hold will never be 100% translatable to your coding agents, but I’d argue we wouldn’t want that anyway. You are the one will customer intuition, with taste, with motivations and with goals. Those things aren’t things you want to handoff to your agents, but they are things you should try to make accessible as a source of truth to your agents. If you need consistency and reliability, and don’t want to play whack-a-mole, this is the first step.

Naur was right in 1985. He’s more right now. The programmers have changed. The need for a shared theory hasn’t.