Context Rot: When Your AI Agent Learns the Wrong Project

Dhruv Saija — Thu, 12 Nov 2026 08:53:21 +0000

Originally published on dhruvsaija.in.

The most dangerous instruction for a coding agent is not the one you forgot to write. It is the one that used to be true.

A repository can carry a build command that no longer builds, a deployment path that no longer reaches production, or a rule that describes an architecture nobody uses. To a human, those are familiar documentation bugs. To an agent, they are instructions.

A recent paper gives this pattern a name: context rot—the drift between persistent AI context and an evolving codebase.

Documentation drift is old. Agents change the failure mode.

Every project carries old truths. A README names a service that no longer exists. A runbook keeps an environment variable from a previous deployment. A setup guide points at a directory that moved two reorganisations ago. Until recently, this was mostly an onboarding tax. A new engineer would try the command, hit an error, and ask a question.

Persistent agent context changes that. Coding-agent tools now explicitly load project instructions, scoped rules, and durable memory from the repository. Claude Code documents this model through project files such as CLAUDE.md, AGENTS.md, and scoped rules.

That is useful because an agent should not need to rediscover the build command, the system boundary, or the test workflow from scratch every time. But it creates a harder problem: stale context is no longer a neglected note that a human may ignore. It becomes an input to the next change.

The difference between missing and stale context

Missing context creates uncertainty. A good agent can inspect the repository, run a safe check, or ask for a decision. Stale context does the opposite. It hands the system a confident answer before the answer has been earned.

That is why stale context can be more dangerous than absent context. The command may still run. The integration may still exist. The deploy target may still look plausible. Nothing has to be obviously broken for the change to be wrong. It only has to be wrong at a boundary the local diff cannot reveal.

A composite failure mode

Imagine a repository whose agent instructions say that the production web app lives in apps/web, deploys from the main branch, and uses a particular environment variable as its canonical URL. All three statements were correct when the instructions were written.

Six months later, the project has been reorganised. The app now lives in web, production deploys through a different workflow, and the canonical URL has changed. The instruction file was never updated. An agent receives a request to change the site header, reads the repository context, and confidently edits the old path, validates the wrong build target, and reports a clean result.

Nothing in that sequence requires the agent to hallucinate. It followed the project knowledge it was given. The failure came earlier: a fact was stored, trusted, and allowed to outlive its usefulness.

This is a composite scenario, not a claim about a specific incident. Its point is that stale context produces a particularly awkward class of failure: the output can be technically tidy, locally verified, and still wrong about the system it is meant to change.

The context rot test: three questions before an agent trusts a fact

The practical response is not more context. It is context that can answer three questions before an agent is expected to trust it.

First: where is the source of truth? If an instruction says how to build, it should point to the package script or build configuration—not become a competing copy of it.

Second: how can it be verified? A critical fact should have a command, test, CI check, permission boundary, or review step that can expose drift. Prose is useful for explaining why a constraint exists. It is a weak place to store rules that must always be true.

Third: what updates or removes it when the system changes? An instruction with no maintenance path is a future liability. If nobody owns it, the agent will eventually inherit an old decision as if it were current architecture.

Keep context small enough to maintain

Do not turn AGENTS.md into a catch-all archive of conventions, exceptions, and historical decisions. A file nobody can safely update becomes another source of context rot.

Better context is compact and scoped. A repository guide can describe the project map and non-negotiable boundaries. Local instructions can describe subsystem-specific conventions. Build scripts and CI can carry verification rules. Access controls can make clear which actions need a human decision. Each layer should do the work it is best suited for.

What changes in practice

The point is not to make an agent autonomous. It is to make the next change easier to explain, verify, and own. When a project boundary changes, update the context that describes it. When a command changes, remove the old command. When something cannot be verified, state the uncertainty instead of presenting a clean but unreliable summary.

That is ordinary engineering discipline. The difference is that the next person reading the project map may be an agent that can turn a stale assumption into a polished pull request before anyone has asked whether the assumption is still true.

DEV Community: Dhruv Saija