Why Your Agent Ignores Your AGENTS.md (And How to Fix It)
If your AI coding agent seems to ignore your AGENTS.md, the cause is almost always the same: the file is too long. The instinct when rules are ignored is to add more emphasis, but that is exactly backwards. The file loads into the agent's context on every task, and when it grows too long the rules that matter get buried under the rules that do not — so the agent follows none of them reliably.
Mistake 1: The File Is Too Long
The most common failure by far. A file that tries to be complete buries the important rules under filler. The fix is the one-line test: for every line, ask "if I remove this, will the agent make a mistake?" Keep the yeses, delete the nos. Aim to cut, not to add — a pruned file is often a fraction of its length and far more effective.
Mistake 2: Personality Instructions
"Act as a senior engineer." "Be thorough." "Think carefully." These feel like leadership and change nothing — the agent already does them. Delete them and let the file start with something that actually informs behaviour, like the stack and the commands.
Mistake 3: Restating What Tools Enforce
Describing formatting your formatter handles, or style your linter catches, wastes lines on rules that run anyway. Move enforcement into the tool and keep the file for the judgement calls nothing automated can check.
Mistake 4: Vague Commands
"Run the tests" cannot be executed; "pnpm test" can. Any command written as a description rather than the exact string becomes a guess the agent has to get right. Write the literal command, with the flags and directory it needs.
Mistake 5: Task-Specific Context
Today's ticket or this feature's design doc is not a property of the repository, yet it ends up in AGENTS.md and never leaves. Keep session context in the session as a direct instruction — which always overrides the file anyway — and keep AGENTS.md for what is always true.
The Pattern Behind All of Them
Every common mistake is a version of putting the wrong thing in the file, or letting the right things drown. There is really only one skill to learn: deciding what earns a place and ruthlessly excluding everything else. Master that and you will not so much avoid these mistakes as never make them.