1. The repository as an incomplete account of itself
A software repository is exceptionally good at storing implementation. It stores exactly what instructions the machine will execute. It has never been good at storing the understanding of those instructions.
The decisions, the constraints, the rejected alternatives and the mapping to reality usually live somewhere else: in a wiki, in a ticketing system, in chat history, or entirely in the heads of the people who built it.
When a human developer looks at a piece of code, they bring all of that external context with them. When an AI agent looks at the same code, it sees only what is written in the files.
2. The authority problem
When an agent searches a repository for context, it finds notes, proposals and old plans. A repository has no structural way to distinguish a proposal from a binding decision.
If an agent finds architecture-v2-proposal.md, nothing tells it whether that proposal was accepted, rejected, or half-implemented and abandoned. It reads the text, assumes it represents the desired state, and confidently writes code against constraints the team dropped six months ago.
Concrete example. An agent finds a draft API specification and implements a client against it, unaware that the team decided in a Slack thread to stick with GraphQL.
3. The staleness problem
Files in a repository rot silently. A README.md might still describe a deployment process from 2022. Because nothing forces documentation to be reviewed when the underlying reality changes, stale files simply accumulate.
Agents read stale files at face value. They have no human instinct for “this looks suspiciously old, I should ask someone.” They read the old deployment process and attempt to execute it.
A file that is wrong looks exactly like a file that is right. Presence is the only signal an ungoverned repository gives.
4. The fragmentation problem
As teams try to solve the context problem, they start leaving instructions for their agents. But there are many agent tools — Claude, Cursor, Copilot, Cline — and so there are many instruction files.
A developer updates .cursorrules and forgets to update CLAUDE.md. The repository now contains conflicting truths, and two developers using different tools are guided toward different architectural patterns inside the same codebase.
5. The accumulation problem
The default way to fix agent context is to write more of it. Teams create enormous CONTEXT.md files holding every architectural rule, domain concept and historical decision.
This fails twice. It blows out the agent’s context window, raising cost and reducing reasoning quality — the needle-in-a-haystack problem. And it creates a maintenance burden so large that the team stops updating it, so notes pile up faster than anyone prunes them.
6. The departure problem
Institutional memory is usually bound to people rather than to the repository. When the lead engineer leaves, the context leaves with them.
Agents amplify that loss. Without the human who knew which files to ignore and which unwritten rules mattered, the remaining team leans harder on agents — which are themselves leaning on the incomplete, stale and fragmented repository state.