Mind the Gap: overcoming meat-metal divergence when coding with LLMs

After spending the better part of the past year building with AI, I’ve found that one problem matters more than almost any other: keeping my mental model of a project in sync with what was actually built. When my mental modal is right, things go well and projects can be iterated on smoothly.

When my mental model is wrong, however, things go south quickly. My subsequent requests are based on assumptions that no longer match reality, causing all sorts of problems for your friendly sycophantic AI.

The problem comes down to a fundamental truth of software engineering: no matter how good the plan, the implementation will need to adjust on the fly to account for things that weren’t predicted ahead of time. Software development has long since adapted to this reality: implementation is iterative, and plans change when they meet reality.

AI-driven development needs to reflect this too, except the speed at which agents build means you need to put nearly as much effort into understanding what was actually built as you put into the upfront design.

AIs are designed to attempt to succeed even against the odds and will talk themselves into all kinds of crazy contortions to achieve some approximation of what’s being asked. After all, as Claude likes to say, "You're absolutely right!" so how could it let you down? See the Hugging Face Incident as an example of that succeed-against-all-odds behavior writ large.

If I ask Claude to use transactions to update account information, but the account is stored in nested JSON inside an S3 object, the crazy way an LLM will attempt to solve that problem will likely break your brain - and your codebase.

If you miss the mid-session note about a half-completed workaround Claude made in the previous phase, then build the rest of your backend and core unaware of that workaround, things will get very bad very quickly.

But this doesn't mean that we're back to reviewing all the code. It does mean that effective, targeted status updates aren't just a nicety but a fundamental piece of AI Native Software Engineering that needs significant thought.

A lot of times when the LLM does something crazy - like build an entire fake API server to make up for the fact that the development server was down for a bit - it doesn't think it was crazy. And it will even tell you exactly what and why it did it.

The key is to make spec divergence a first-class part of the high-level summary. By default, agents want to tell you everything they did. What you actually need to know is the small portion of what they did that changes your mental model of the system.

This has led me to a 3-pronged approach to handle what I'm calling meat-metal divergence:

1. 1 -
   Establish the expected baseline. Spell out the architecture and approach clearly and succinctly at the top of the design document. Both the developer and the agent need to actually internalize it. I’ve found ASCII architecture diagrams particularly effective here.
2. 2 -
   Durably document divergence. At the end of each phase, have a review agent explicitly record anything that changed from the agreed-upon design - including workarounds, substitutions, incomplete implementations, and assumptions made along the way. Document everything. No judgement calls here.
3. 3 -
   Reconcile. Have a post-phase user-gate agent compare the resulting implementation against the design and surface the differences that materially affect the developer’s mental model. The developer then needs to understand and mentally-incorporate those changes before moving on.

These 3 steps as part of the build process are the only things I've found are effective in keeping my brain in sync with what's actually being built (reading the code would obviously do that too, but there's way too much of that these days).

When I do realize I’ve lost the plot, the recovery mechanism is straightforward: fire off a handful of targeted agents asking questions like “What is the current state of X?”, “Does X actually work like Y?”, and “Where does the implementation of Z differ from the design?” It’s essentially a forced resynchronization of my mental model with the codebase.

In AI-native software development, you don’t need to keep all the code in your head, but you do need to ensure you keep what’s in your head properly synchronized with the code. Mind the gap.