There’s a complaint I hear in every team meeting about AI coding tools, usually from a senior engineer: “The AI doesn’t understand our codebase.” Sometimes this is followed by “so it’s not useful.” Sometimes by “so we need a different tool.” Sometimes by “so we need to wait for better models.”
Each of those follow-ups treats the complaint as a single thing. It isn’t. “AI doesn’t understand our codebase” can mean four different things, and the right response to each is different.
Meaning 1: “The AI doesn’t have my codebase loaded”
The most common version. The complaint is that the AI’s suggestions are based on generic patterns rather than the specifics of the codebase. The complainant is right; the AI literally doesn’t have the relevant files in context.
The fix isn’t a better tool. It’s loading the right context. Cursor’s @-references, Aider’s /add, Cline’s file picker — all of them require explicit context loading. Tools that promise to “automatically understand” your codebase usually mean “we’ll search and load relevant files,” which works when their search is good and fails when it isn’t.
The behavior change required is: before prompting, decide what files the model needs to see, and load them explicitly. This is the discipline that separates “AI saves me time” from “AI produces irrelevant junk.”
Meaning 2: “The AI doesn’t follow our conventions”
Different complaint, often phrased the same way. The AI has the right files in context, produces functionally correct code, but the code doesn’t match the team’s style. Naming, formatting, architectural patterns, library preferences — all wrong.
The fix is conventions files. Cursor Rules, Aider’s CONVENTIONS.md, Windsurf’s rules, Cline’s instructions. None of these are perfect, all of them help significantly when written carefully. A 50-line conventions file specific to your team’s standards changes the output substantially.
This is the highest-ROI investment for teams adopting AI tools and the one most teams skip. Two hours of writing conventions, weekly maintenance of about 15 minutes, applies to every prompt every team member ever runs. The amortized return is enormous.
Meaning 3: “The AI doesn’t know our domain”
A different complaint again, sometimes confused with the first two. The AI has the codebase in context and knows the conventions, but it doesn’t understand what the business does. It doesn’t know that “MRR” means monthly recurring revenue in your context, that “the merchant” refers to a specific actor in the workflow, that “recurring” is a specific contract type with specific rules.
This isn’t a context-loading problem. The information genuinely isn’t in the code in a form the AI can extract. It’s in your product docs, your customer support knowledge base, your team’s conversations.
The fix is partial — give the AI domain context explicitly. A DOMAIN.md document explaining your business in the form of definitions, ten or twenty key terms with what they mean in your context. Or a glossary file. Or just a paragraph in your prompt template.
This works better than no context but not as well as a human who’s been at the company for two years. Some understanding gaps don’t close because the information doesn’t exist in writing anywhere.
Meaning 4: “The AI is hitting its actual limits”
The case that’s harder to fix. Sometimes the complaint is accurate at a structural level: the codebase has cross-cutting invariants that aren’t explicit anywhere, the architecture has implicit rules that emerge from interactions, the system has runtime behavior that no static analysis can predict.
A model can be given perfect access to all the files, perfect conventions, perfect domain context, and still fail to understand a sufficiently complex codebase. Not because the model is dumb but because the codebase’s behavior isn’t fully described by any static artifact.
The fix here isn’t a tool change. It’s recognizing that some kinds of work are the human’s job, and the AI is a tool for parts of the work, not all of it. Architecture decisions in legacy systems. Performance optimization. Anything that requires knowing how the system actually behaves under load.
For these, AI is at best a thinking aid — a sounding board for hypotheses you’ve formed, not a generator of correct answers. Treating it as the latter when it’s the former is what produces “AI can’t do my job” frustration.
Diagnosing which meaning applies
When someone on your team says “AI doesn’t understand our codebase,” ask:
Does the AI have access to the relevant files? If no, fix the context loading. If yes, move on.
Are the AI’s outputs functionally correct but stylistically wrong? If yes, write conventions. If outputs are functionally wrong, move on.
Are the AI’s outputs wrong in domain-specific ways — using wrong terms, misunderstanding business rules? If yes, add domain context. If wrong in code-level ways, move on.
Is the AI failing on tasks that require understanding system behavior at runtime? If yes, this is the AI’s actual limit. Stop expecting a fix from the tool side; treat AI as a partial helper for these tasks, not a replacement.
Most “AI doesn’t understand” complaints are one of the first three. They’re solvable with discipline and configuration. The fourth meaning is real but rarer than people invoke it.
What teams that complain less actually do
The teams I’ve seen develop a healthy relationship with AI tools share some habits:
They write conventions. Not because they’re told to but because they’ve internalized that AI defaults aren’t their team’s style and explicit alignment is faster than perpetually fixing it.
They explicitly load context. They don’t expect the tool to find relevant files; they @-reference them, attach them, paste them.
They have a domain glossary. Either as a literal file or as a habit of explaining domain terms in prompts.
They reach for AI for the right tasks. They don’t ask AI for architectural decisions. They don’t ask AI to predict runtime behavior. They use AI for code-level work where AI is genuinely strong.
The teams that complain most often skip these habits. Their AI use is undirected: paste a prompt, see what happens, complain when the output is bad. The output is bad because the input was vague; the AI did its job within the constraints of its context, and the context was insufficient.
The polite reframe
When a senior engineer in your team complains that AI doesn’t understand the codebase, the polite reframe is: “What context did you give it?” Not as gotcha — as diagnostic. Often the answer reveals which of the four meanings is actually in play, and the right fix becomes obvious.
For meaning 1: load more files. For meaning 2: write conventions. For meaning 3: add domain context. For meaning 4: stop using AI for that.
All four are reasonable answers. The wrong answer is the generic “the AI is bad,” which fixes nothing and discourages habit changes that would help.
If your team has been frustrated with AI tools, walk through this checklist before changing tools, models, or vendors. Most of the frustration resolves at one of the first three steps. The fourth case is real but uncommon, and the work to identify it is the same work that fixes the more common cases.