Why Does My Agent Ignore AGENTS.md?

Quick answer
First confirm the file is read: check the harness documentation for the paths it loads and whether nested files are supported.
Long files get skimmed. Instructions in the middle of a 500-line document are followed less reliably than a short list.
Preferences (“write clean code”) cannot be checked, so they are easy to violate. Rules (“run npm test before claiming done”) can be.
Conflicting instructions cancel out: a rule in AGENTS.md and a different habit in the prompt leave the agent to choose.
Put the rules that must always apply in AGENTS.md, and move procedures into skills so they load when relevant.

Is the file actually being loaded?

Check the harness documentation for the file names and directories it reads, and whether it reads them from the working directory, the repository root, or only when a new session starts. A file in the wrong place is not ignored; it is never seen.

Then ask the agent to quote the rules it is following. If it cannot, the file is not in context. That one question distinguishes a loading problem from a compliance problem.

Is the file too long to matter?

A short file with five rules is followed more reliably than a long one with forty. Length dilutes each rule, and the ones in the middle get the least attention. If the file needs sections, it probably needs splitting into a short rules file and several skills.

Keep only what changes behaviour: the commands to run, the directories not to touch, the conventions that differ from the default. Anything a competent engineer would assume is noise.

Are the rules checkable?

“Be careful with migrations” is a mood. “Never edit files under migrations/; create a new migration instead” is a rule the agent can follow and you can verify. Replace every adjective with a command, a path, or a prohibition.

The same applies to tone and style. If it matters, point to a file that demonstrates it and name the file. A reference is checkable; a description is not.

What else competes with the file?

The current prompt, the plan, the skill in use, and the agent’s own habits all compete with AGENTS.md. If the prompt says “make the tests pass quickly”, a rule about not weakening tests loses. Make the priority explicit, or remove the conflicting instruction.

Installed mods and user-level files can also change behaviour in ways the repository does not show. When behaviour changes across projects, check what is installed at the harness level.

Where this bites vibecoders
A generated AGENTS.md tends to read like a style guide: “follow best practices”, “write clean, maintainable code”. None of it changes a decision. Rewrite it as commands and prohibitions, then test by asking the agent to list the rules it applied to the last change.

Where AI coding assistants get this wrong

Writing a long document of good intentions instead of a short list of rules.
Placing the file where the harness does not look.
Assuming a rule loads into an already-running session.
Leaving a prompt instruction that contradicts the file.
Describing conventions without pointing to an example file.
Adding a rule after every incident until the file is unreadable.

Checklist

Confirm the file path the harness reads.
Ask the agent to quote the rules it is following.
Keep the file to the rules that change behaviour.
Rewrite preferences as commands and prohibitions.
Remove instructions that conflict with the file.
Move procedures into skills.

FAQ

Does AGENTS.md apply to every AI tool?

It is a shared convention that many harnesses read, and it is hosted by the Agentic AI Foundation, but support and lookup rules differ. Check the documentation for the tool you use, and keep the file at the repository root unless the docs say otherwise.

Should I put the whole style guide in it?

No. Point to the style guide and name the two or three rules that are most often broken. The goal is compliance on the decisions that matter, not a copy of the documentation the agent will not read.

Why does the agent follow the rules for a while and then stop?

That is usually compaction or context pressure, not defiance. Restate the constraint at the checkpoint where the work changes direction, and keep long procedures in a skill so they are reloaded when needed rather than summarised away.

Can I enforce a rule with a hook instead?

Yes, for rules that must hold. A hook that blocks edits to a directory, or runs a formatter after a write, enforces the rule mechanically. Instructions are advisory; hooks and CI are not. Use both for the few rules that really matter.