DEV Community

Mokhles Elheni
Mokhles Elheni

Posted on

Stop Adding "Never Do X" to AGENTS.md. Write a Check Instead.

Every team using coding agents hits this at some point.

You correct the agent. It says sorry and fixes the code. A few days later, in a new session, it makes the exact same mistake. So you open AGENTS.md and add one more line:

NEVER call fetch directly. Always use apiClient.

A month later that file has dozens of lines like this, and the agent still gets them wrong now and then. Writing the rule in bigger letters doesn't help.

Here is what I do instead.

The problem with "never do X" lines

AGENTS.md (or CLAUDE.md, .cursorrules, and so on) is a text file the agent reads once at the start of a session. That has a few limits:

  • Nobody checks it. If the agent forgets a line, nothing fails. You only find out in code review, if you notice.
  • It gets long. Each correction adds a line, and old lines are rarely removed. The more lines there are, the easier it is to miss one.
  • It has no idea where a rule applies. A rule about SQL migrations is loaded when the agent edits CSS.
  • It often skips the reason. "Don't use moment.js" without "because we moved to date-fns to cut bundle size" is hard to apply to new cases.

None of this is the agent's fault. A note is just a weak way to enforce a rule.

Turn the correction into a check

If you had to tell the agent something twice, write a check for it. The agent can ignore a sentence. It can't ignore a failing check.

Two ways to handle the same correction

Here is the fetch example as an ESLint rule:

// eslint.config.js
export default [
  {
    files: ["src/**/*.ts"],
    ignores: ["src/api/client.ts"],
    rules: {
      "no-restricted-globals": ["error", {
        name: "fetch",
        message: "Use apiClient from src/api/client.ts. It adds auth headers and retries.",
      }],
    },
  },
];
Enter fullscreen mode Exit fullscreen mode

Three things make this work better than the line in AGENTS.md:

  1. It fails. The agent can't finish while the error is there.
  2. It only runs where it matters. files and ignores limit it to the right code, so there are no false alarms in the API client itself.
  3. The message says why and what to do. The agent gets the fix at the exact line with the mistake.

Not every rule fits a linter. For those, a small script works fine:

# fail if a migration has no rollback
for f in db/migrations/*.up.sql; do
  [ -f "${f%.up.sql}.down.sql" ] || { echo "$f has no .down.sql rollback"; exit 1; }
done
Enter fullscreen mode Exit fullscreen mode

Then add one line to AGENTS.md: "Before you finish, run npm run check and fix what it reports." That one line does more than fifty "never" lines.

Keep decisions separate

Some rules aren't about code style, like "we use Postgres" or "auth lives in the gateway". A linter can't check those well. Keep them in a short list, each with:

  • the decision,
  • the reason,
  • the folders it applies to.

When a decision changes, replace the old one. Don't add a new line that contradicts it.

Clean up

Checks are code, so treat them like code. If a check fails on correct code, fix it or remove it. Otherwise the agent learns that checks can be ignored, and you're back where you started.

What's left in AGENTS.md

Not much, and that's good:

  • how to build and test,
  • where the main parts of the code live,
  • the command that runs all the checks.

If a line could be a check, move it into a check.

A tool for this

Writing these checks by hand works, but it's slow, so most people go back to adding lines to a file. Some tools now automate the loop. ingrain is one example: it learns lint rules from the corrections you make to your agent's code, limits each rule to the files it applies to, and keeps a list of decisions with reasons that the agent reads before editing a file.

Use a tool or write the checks yourself. The rule is the same: if you said it twice, make it a check.

Top comments (0)