Your AI coding agent doesn't know your project's history

The agent removed the odd-looking retry you added after last spring's outage. It suggested the library your team evaluated and rejected. It "cleaned up" a workaround that exists because a vendor API misbehaves on Tuesdays. None of that is the model being careless. It simply doesn't know what your team knows.

AI coding tools read the code in front of them. Most of what makes a codebase make sense, the decisions, trade-offs and history, isn't in the code. This guide covers how to put that context where agents can actually use it.

The "almost right" problem

Developers have noticed. In the Stack Overflow 2025 Developer Survey, the most common frustration with AI tools, named by 66% of developers, was "AI solutions that are almost right, but not quite", and 45.2% said debugging AI-generated code takes more time. Among developers asked about AI agents, 86.9% were concerned about the accuracy of the information.

Experienced developers on mature codebases may feel this most. In METR's randomized study from early 2025, 16 experienced open-source developers working on large, mature repositories took 19% longer on tasks when they were allowed AI tools, even though they had expected a 24% speedup. The authors suggest implicit repository requirements were one factor: the things a long-time maintainer just knows. METR itself notes these early-2025 results are now dated and has published a newer update, so treat it as a signal about where AI struggles, not as a verdict on today's tools.

The pattern is consistent: the model is fluent in code in general and blind to your code's reasons.

What the agent can and can't see

Think about what a coding agent has access to in a typical session: