What to Do When AI Can't Understand Your Codebase

When an AI coding tool keeps producing wrong or confused output on your codebase, the problem is almost never that the model is not smart enough. It is that your repo is not legible. The model gets a keyhole view: a few files, no map, no history, none of the tribal knowledge that makes the code make sense to your team. A codebase that is hard for a new human to understand is hard for a model in exactly the same ways, plus the model cannot walk over to someone's desk and ask. Fix legibility and the "the AI does not get it" problem mostly dissolves.

The problem is context, not intelligence

A model works from what fits in its context window. If your codebase is a sprawling monolith with no clear entry points, the model sees fragments and fills the gaps with guesses. Those guesses are why it invents functions that do not exist and misses invariants that are load-bearing. It is not being dumb. It is working blind.

The same repo that confuses a model confuses your new hires, for the same reason: the important knowledge is not in the code, it is in people's heads. This is why context window management for AI coding matters more than raw model capability. A brilliant model with the wrong context loses to an average model with the right context.

Make the repo legible

The fixes are the same ones that would help a human, which is the tell that this is a legibility problem, not a model problem.

• Give it a map. A model that has read the whole repo and built an index of what calls what does not have to guess. This is what repo intelligence before a refactor provides, and it is the single biggest lever.
• Write down the conventions. If your naming and patterns are undocumented, the model invents its own. Teach it your codebase conventions explicitly and the invented dialect stops.
• Point at entry points. Do not make the model discover where a request enters. Tell it. Half its confusion is spent figuring out structure you already know.
• Name the invariants. The rules that are not enforced by types but must hold. The model cannot infer "never call this without a lock." Say it.

Shrink the surface you ask about

Even with a map, do not ask the model to reason about the whole system at once. Scope the question. "Change this function's behavior" with the relevant callers loaded beats "refactor the payments system" with nothing loaded. A smaller, well-loaded surface produces better output than a huge, thinly-loaded one every time. This is the same reason scoping the task to succeed works: you are matching the ask to what actually fits in the model's view.

If the codebase is so tangled that you cannot even scope a small piece cleanly, that is a signal about the code, not the model. A repo no model can reason about a piece of is usually a repo your team also struggles with. Using repo intelligence to split a monolith fixes the underlying tangle, and the AI legibility comes along for free.

When the answer is to fix the code first

Sometimes the honest move is to stop trying to make the model understand the mess and reduce the mess. Extract the module you keep asking about. Add the characterization tests that pin its behavior. Untangle the one seam you work at most. You are not doing this for the AI. You are doing it because the code needed it anyway, and now both humans and models can work in it. Auditing the codebase you inherited is where that starts.

This legibility-first approach is how I run legacy work at Bootspring: the model reads and maps the repo before it writes, so it is never working blind. The mapping engine is the same one ReformCode uses to score a repo you did not write.

The takeaway

When AI cannot understand your codebase, it is a context problem, not an intelligence problem. Give the model a map, write down the conventions and invariants, point at entry points, and scope your questions small. If the repo is too tangled for any of that to help, fix the code, because a codebase no model can reason about is one your team struggles with too.