Why does my AI agent ignore project instructions?

An AI agent usually ignores project instructions because the instruction is buried in a long file, contradicted by something else it reads, dropped as the session's context fills up, or too general to turn into an action. In most cases the agent did not decide to disobey; the instruction was either not in front of it when it mattered or did not say anything specific enough to follow. 'Write clean, well-tested code' cannot be checked, so it cannot visibly be broken. 'Every new endpoint gets a test in tests/api' can. The practical fix is to move important rules closer to the task, make them checkable, and enforce the ones that really matter with a tool rather than a sentence. This page gives a quick diagnosis to find which of the four causes you have, the fix for each, and a way to stop rules drifting out of sight again. Why a single instruction file has limits is covered in CLAUDE.md and its alternatives.

Check first: does the agent know the rule at all?

The fastest test is to ask. At the start of a session, before any edits, ask the agent to list the project rules that apply to the task in front of it. Do not name the rule you are worried about.

If the rule is missing from its answer, the instruction is not reaching it, or it is not registering as relevant. Check that the file you wrote it in is one the tool actually loads for this directory, and look at where in the file it sits. A rule on line 300 of a long instruction file, between a style note and a deployment note, competes with everything around it.

If the rule is in its answer but it still breaks it, the problem comes later: a contradiction, a long session or a rule too vague to apply. Note when the break happened. Early in a fresh session points to a contradiction or vagueness. Late in a long one points to context loss.

This takes two minutes and saves a lot of rewording of instructions that were never the issue.

Contradictions and vague rules

Agents resolve conflicts the way people do: they follow the most specific or most recent signal. If the instruction file says 'use the repository pattern for database access' but half the existing code queries the database directly, the code is often the stronger signal, because it is right there in the file being edited. The same happens when a task description says one thing and a general rule says another.

To find contradictions, search for the rule's subject across every instruction source: the project file, nested files in subdirectories, the task text and comments in the code. Decide which one wins and delete or amend the other. If old code is the contradiction, say so explicitly: 'Legacy modules query directly. Do not copy that pattern into new code.'

Vague rules fail differently. 'Keep functions small' or 'follow best practices' give the agent nothing to check against, so it will believe it complied. Rewrite each one as something observable: a size, a location, a named pattern, a command that must pass. If a rule cannot be rewritten that way, it is probably a preference, and it belongs in review rather than in instructions.

Rules that fall out of context

In a long session, early material gets summarized or pushed out to make room, and instructions loaded at the start are exactly that material. The symptom is a rule followed for the first hour and broken after it, often right after the tool compacts the conversation. Context window limits explains the mechanism; the fixes are practical.

Keep sessions shorter. One task per session, ended with a written handoff, keeps the instruction file near the start of a fresh context instead of far behind.

Put task-critical rules in the task. If a change must not touch the public API, write that in the task description where the agent reads it at the moment of work, not only in a project-wide file. A short task context that carries the relevant rules is more reliable than a long file that carries all of them; bounded task context covers how to assemble one.

Restate after compaction. If you must continue a long session, ask the agent to reread the rules once the tool has summarized the conversation, and to confirm which ones apply to the current step.

Enforce what matters, prevent the drift

Some rules are important enough that you should not depend on the agent remembering them. Turn them into checks. A rule about import boundaries becomes a lint rule. 'No new dependencies without approval' becomes a script that diffs the lockfile. 'Tests live next to the module' becomes a CI check. The agent can still break the rule, but the break is caught the same way every time, and the check can be part of the task's definition of done; tasks agents can finish shows how to write that in.

For the rest, keep the instruction file short and current. When a rule is broken, ask whether it was unclear, buried, contradicted or obsolete. Delete obsolete rules; they teach the agent that the file is partly wrong, which weakens the rest. Group what remains by when it applies, so the agent finds the database rules when it is editing database code.

Finally, give each important rule its reason in one line. 'Use integer cents for money because float rounding broke invoices' is far more likely to be applied to a new case than 'use integer cents'. Reasons also make it easier to tell when a rule has expired.

QUESTIONS

Why does my agent follow a rule at first and then stop?

Usually because the session got long. Instructions loaded at the start are among the first things summarized or pushed out when context fills. Ending the session at a task boundary and starting fresh from a short handoff is the most reliable fix. If you must continue, ask the agent to reread the rules after the tool compacts the conversation.

How long should a project instruction file be?

Short enough that every rule in it is current and specific. There is no fixed number, but a file that mixes style notes, deployment steps and project history will bury the rules that matter. Move task-specific rules into tasks, turn critical rules into automated checks, and delete anything obsolete.

Should I repeat important instructions in every prompt?

Only the ones that apply to that task, and preferably in the task description rather than typed by hand each time. Repeating everything adds noise. Repeating the two rules that matter for this change, next to the change, is effective. Rules that must never be broken are better enforced by a lint rule or a script.

RELATED GUIDES

• How to create a project card in BRAIN FLUID Desk

RELATED HARNESS PAGES

• CLAUDE.md alternatives CLAUDE.md alternatives compared: what a project instruction file does well, where it stops, and what a project harness like BRAIN FLUID adds.
• Context window limits for coding agents Context window limits for coding agents: what fills the window in real work, what gets dropped first and how it turns into mistakes.
• Bounded task context Bounded task context: give an agent the slice of a project one task needs, chosen by relationship, capped in size, with omissions stated.
• How to write a task an AI coding agent can finish How to write a task an AI coding agent can finish: one outcome, a scope, dependencies, completion criteria and the check that proves them.
• What gets lost when an agent summarizes a long session What gets lost when an agent summarizes a long session: which details survive, which vanish, and how to protect constraints and exact values.
• Organizing a repository so AI agents can navigate it Organizing a repository so AI agents can navigate it: a short README map, one test command, consistent layout, small modules, clear entry points.