You tell your coding agent: “Don’t call fetch directly. Use our API client." It fixes the code. Two days later, in a new session, it calls fetch directly again.

Most people then add a line to AGENTS.md (or CLAUDE.md, or .cursorrules): "Never call fetch directly." A few weeks later the file is long, full of "never do X", and the agent still makes the same mistakes.

The agent is not the problem. A text file is just the wrong place for this.

Why AGENTS.md doesn’t stop repeated mistakes

1. Nothing checks it. The agent reads the file at the start. Then it reads code, runs commands and makes plans. After a while, one line in a long file is easy to miss. If the agent ignores it, nothing fails.

2. It only grows. Every correction adds a line. Nobody deletes old ones. Lines start to repeat or contradict each other. The longer the file, the less each line matters.

3. Every rule is loaded everywhere. A rule about database migrations is useless when the agent edits a button. But the file can’t say where a rule applies.

4. You can’t tell if a rule works. You only find out it didn’t when you catch the same mistake again.

5. The reason is missing. “Don’t use library X” doesn’t say why. The agent can’t apply it to a new case, and a few months later nobody knows if it’s still true.

What works: turn the correction into a check

If you had to correct the agent twice, treat it like a bug that came back. A bug that comes back gets a test, not a note.

A line in a file is easy to ignore. A failing check is not.

Write it down right away. When you fix the agent’s code, you know exactly what was wrong and what the right version looks like. That’s the best time to capture it.

Let the computer check it. Use a lint rule, a test or a small script. “Don’t call fetch directly” can be a lint rule (in ESLint, no-restricted-globals). "Every migration needs a rollback" can be a script that fails in CI. Most "never do X" lines can become a check.

Only run it where it matters. A migration rule should only look at migration files. This keeps checks fast and avoids false alarms.

Make the agent run the checks, and explain the reason in the error. Tell the agent to run the checks before it says it’s done. The error should say what’s wrong, why, and what to do instead. The agent sees it on the exact line with the mistake, and the check keeps failing until the code is fixed.

Write down decisions too. Some things a tool can’t check, like “we use Postgres” or “login is handled by the gateway”. Keep these in a short list, each with a reason and the folders it covers. When one changes, replace it. Don’t add a second line that disagrees with the first.

Remove bad checks. If a check fails on correct code, fix it or delete it. If you don’t, the agent learns to ignore checks.

What AGENTS.md is for

Keep it short. Use it to say how to build and test the project, where things are, and which command checks the agent’s work. If a line could be a check, make it a check.

A simple test: if your file has more “never” lines than commands, it’s doing a job your tools should do.

Summary

  • Agents repeat mistakes because nothing enforces a line in a text file.
  • If you correct something twice, add a check.
  • Run each check only on the files it’s about, and put the reason in the error.
  • Keep decisions in a separate list, with reasons.
  • Keep AGENTS.md short and point it to the checks.

Tip

Doing this by hand takes time, which is why people go back to adding lines to AGENTS.md. Some tools do it for you. For example, ingrain turns the fixes you make to your agent’s code into lint rules, runs each rule only on the files it applies to, and keeps a list of decisions with reasons that the agent reads before it edits a file. With a tool or without one, the idea is the same: don’t tell your agent twice. Add a check.


Your AI Agent Keeps Making the Same Mistake. AGENTS.md Won’t Fix It. was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.