Understanding AI Diversions

Google has described an internal cleanup system that identifies outdated project notes that can send coding agents into unrequested work. While the specific system is not publicly available, users of tools like Claude Code can apply similar validation checks to their own project files. Stale instructions often lead an agent away from its assigned task, even if the requested work is eventually completed.

A source-of-truth rule can help resolve conflicts between existing code and older plans, while proper ticket status management preserves room for unfinished work. Implementing a sweep skill that checks project notes against current code and history allows for the identification of potential conflicts for human review, archiving approved removals rather than deleting them outright.

Why Agents Follow Outdated Information

Coding agents typically read project files to plan tasks before execution. Files like CLAUDE.md or documents in a specs folder are loaded into the agent's context, meaning any instructions or notes that no longer match the current state of the application are processed as active requirements.

An old bug note or an abandoned feature plan can trigger work that was never requested. Even if an agent makes a technically correct change based on an old note, it may inadvertently alter code that was intended to remain unchanged or implement a feature that the team planned to build differently.

Google refers to these unintended diversions as side quests. By analyzing developer notes linked to bug records across millions of sessions, Google found that when an agent pursued an outdated note, it was rarely at the explicit request of an engineer.

Data indicated that in about one in seven sessions, agents encountered these notes. In more than 80% of those instances, the agent pursued the note without any specific request to do so.

Of the side quests measured, 41% targeted already-fixed bugs, while 57% pursued open bugs that had not been assigned to the agent. Sessions involving these diversions were significantly less efficient, taking 70% more actions and using 77% more tokens compared to sessions where the agent remained on task.

How Project Instructions Become Stale

Studies have shown that agents frequently prioritize outdated project files over the actual state of the application. When project documentation conflicts with the codebase, agents often default to the written instructions.

The size and complexity of instruction files also play a role. Agents often process the entire file, including irrelevant sections, which increases token costs without improving performance. As rules accumulate, they can become contradictory, forcing the agent to make decisions without further clarification.

Memory systems can also exacerbate the issue. When an agent saves notes that do not expire, it creates a repository of information that may no longer be accurate, especially in projects where the code has evolved significantly.

Context length is another factor. Research suggests that as context grows longer, models become less reliable. Furthermore, long sessions that undergo compaction can sometimes lead to the reappearance of previously completed plans.

Requirements often change faster than documentation. If a project shifts direction, an agent might continue to follow a requirements document that describes an obsolete feature, leading it to mistake a deprecated option for unfinished work.

Rules That Keep Claude on Task

Establishing a source-of-truth rule in project configuration files—such as instructing the agent to trust existing code over conflicting plans—can significantly improve accuracy. In testing, this approach successfully shifted agent behavior to prioritize the codebase.

Ticket status tracking provides necessary nuance. By clearly marking tasks as completed, in progress, or not started, the agent can better interpret features that appear in documentation but are not yet reflected in the code.

Explicit rules regarding scope can also prevent extra work. Instructing an agent on which parts of a project to leave untouched has been shown to reduce the frequency of unauthorized modifications.

For new requests, requiring the agent to compare the task against existing plans before execution allows for conflict detection. If a contradiction is found, the agent can flag the issue for human review rather than proceeding blindly.

Starting a fresh session for each task is also recommended. This prevents the accumulation of failed attempts and stale context from previous tasks from influencing new work.

Implementing a Project Sweep

Google’s approach involved building agents to search for notes related to bugs that had been resolved. By checking bug records and historical code changes, the system could determine if a note was truly obsolete before suggesting its removal.

Human oversight remains critical. In Google's implementation, engineers reviewed proposed removals, accepting over 95% of the suggestions over a six-month period.

Developers can create a similar sweep skill for their own agents. This skill compares project plans against current code and history, reporting potential issues for review rather than automatically modifying files.

The setup can be configured to send claims to a checking agent, ensuring that conflicts are identified and presented for resolution rather than being labeled as outdated without verification.

Once a report is approved, unneeded files can be moved to an archive. Implementing scripts that block the agent from reading these archived files ensures that obsolete information does not re-enter the context.

While automated cleanup systems are not universally available, developers can leverage existing monitoring and loop features to build custom solutions for maintaining project documentation hygiene.

For users of Claude Code, implementing a sweep skill is a practical step toward ensuring that project notes and plans remain accurate and aligned with the actual state of the codebase.