Comment by mjheadd
19 hours ago
Worth reading alongside recent research on AGENTS.md file effectiveness. The clearest use case for these files isn't describing your codebase, it's overriding default behavior. If your project has specific requirements around tooling (common in government and regulated industries), that's exactly what belongs in the AGENTS.md files.
It still ignores it. I always have to say 'Isn't this mentioned in AGENTS??' and it will concede that it is.
In my experience the problem is how people write them. Descriptive statements get ignored because the model treats them as context it can reason past.
"We use PostgreSQL" reads as a soft preference. The model weighs it against whatever it thinks is optimal and decides you'd be better off with Supabase.
"NEVER create accounts for external databases. All persistence uses the existing PostgreSQL instance. If you're about to recommend a new service, stop." actually sticks.
The pattern that works: imperative prohibitions with specific reasoning. "Do not use Redis because we run a single node and pg_notify covers our pubsub needs" gives enough context that it won't reinvent the decision every session.
Your AGENTS.md should read less like a README and more like a linter config. Bullet points with DO/DON'T rules, not prose descriptions of your stack.
Hah, it's somewhat ironic how this is almost the exact opposite of the prevailing folk wisdom I've read for the last 1-2 years: that you should never use negative instructions with specific details because it overweights the exact thing you're trying to avoid in the context.
Given my own experience futilely fighting with Claude/Codex/OpenCode to follow AGENTS.MD/CLAUDE.MD/etc with different techniques that each purport to solve the problem, I think the better explanation really is that they just don't work reliably enough to depend on to enforce rules.
1 reply →
Have any links?