6 AGENTS.md Mistakes That Make Your Coding Agent Ignore It

Your repo has an AGENTS.md, and your coding agent still runs the wrong test command, edits a generated file, or asks you how the project is laid out. Usually the file isn't the problem. It's how the file was written, where it sits, or whether the agent loaded it at all.

Here are six common mistakes, with the fix for each, based on the official docs for the tools that read the file.

A quick recap: what AGENTS.md is

AGENTS.md is an open format for guiding coding agents: plain Markdown at the root of your repo, a "README for agents". There are no required fields or special syntax. Cursor, Codex, Gemini CLI, Aider, Zed, Windsurf and many other tools read it. The format is now stewarded by the Agentic AI Foundation under the Linux Foundation.

The idea is simple: one file, every tool. The mistakes below are what break that idea in practice.

Mistake 1: A CLAUDE.md silently shadows your AGENTS.md

This is the one people are talking about this week. Claude Code can now read AGENTS.md directly (v2.1.277 or later), but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. If any of those exist, Claude reads them instead, and your AGENTS.md never loads.

The sneaky case is CLAUDE.local.md. You add one for your personal sandbox URLs, and from that moment Claude stops reading the shared AGENTS.md.

Fix: keep AGENTS.md as the source of truth and import it from CLAUDE.md, putting Claude-specific notes below the import:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

If you don't need anything Claude-specific, a symlink also works:

ln -s AGENTS.md CLAUDE.md

The docs flag one caveat: on Windows, symlinks need Administrator rights or Developer Mode, and Git may check a committed symlink out as a one-line text file. If anyone on your team uses Windows, use the @AGENTS.md import instead. You can also change the "Project instructions" option in /config to claude-md-and-agents-md so both files load together.

Mistake 2: Vague or missing commands

The single most useful thing an agent can get from your file is exactly how to install, build, test and lint. "Run the tests" makes the agent guess. pnpm test doesn't.

The agents.md FAQ is explicit: if you list testing commands, the agent will try to run the relevant checks and fix failures before it finishes. If you don't list them, it falls back on its own guesses.

A lean, useful starting point looks like this:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Test: `pnpm test`
- Lint and typecheck: `pnpm lint`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

## Boundaries
- Never edit files in `dist/` or `src/generated/`
- Ask before adding a new production dependency

## Pull requests
- Run `pnpm lint` and `pnpm test` before committing

Every line is concrete enough to check. That's the bar.

Mistake 3: Writing it like a prompt, and letting it grow

Another common failure is the opposite of an empty file: a long one full of "act as a senior engineer", "write clean code", and a pasted style guide. It costs context and buries the few lines that matter.

The tools give you concrete reasons to stay lean:

• Claude Code's docs suggest keeping instruction files under 200 lines, because longer files consume more context and reduce adherence.
• Codex stops adding instruction files once their combined size reaches project_doc_max_bytes, 32 KiB by default. Anything past that is dropped.
• Cursor's rules docs advise against copying whole style guides ("use a linter instead") or documenting every common command the agent already knows.

Fix: for every line, ask: would the agent get this wrong without it? If the answer is no, cut it. Anthropic's docs offer a good trigger for adding lines: write something down when the agent makes the same mistake a second time, or when you catch yourself typing the same correction you typed last session.

Mistake 4: One giant root file for a monorepo

In a monorepo, a single root file ends up holding frontend, backend and infra rules, and every task pays for all of them.

Fix: put a short AGENTS.md inside each package. According to agents.md, agents read the nearest file in the directory tree, so the closest one takes precedence. The details vary by tool:

• Codex walks from the project root down to your working directory and concatenates the files, so files closer to where you're working appear later and override earlier guidance. It also supports AGENTS.override.md for a directory that needs to replace the regular file.
• Cursor supports nested AGENTS.md in subdirectories and combines them with parent directories, with more specific instructions taking precedence.

repo/
  AGENTS.md            # repo-wide: commands, PR rules
  apps/web/AGENTS.md   # frontend conventions
  services/api/AGENTS.md

Keep the root file for what's true everywhere, and push the rest down.

Mistake 5: Treating it as a security boundary

AGENTS.md is context, not permission. Claude Code's docs say it plainly: instruction files are treated as context, not enforced configuration. "Never read .env" in Markdown will be followed most of the time, and "most of the time" isn't good enough for secrets.

Fix: keep the rule in AGENTS.md so the agent understands why, and enforce it with the tool's own controls. In Claude Code, that's a permission rule in settings (here in the project's .claude/settings.json), following the settings docs:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

For actions that must always or never happen at a specific point, such as before every commit, Claude Code's docs recommend hooks, which run regardless of what the model decides. Other tools have their own mechanisms. Check each one's documentation rather than relying on the Markdown file.

Mistake 6: Never checking that it loaded, or that it's still true

A file the agent never read and a file that describes last quarter's codebase fail the same way: the agent confidently does the wrong thing.

Fix: verify it loaded, using each tool's own check:

• Claude Code: run /memory and look for your AGENTS.md path in the list, or /context if you import it from CLAUDE.md.
• Codex: the docs suggest asking it directly from the repo root:

codex --ask-for-approval never "Summarize the current instructions."

Then treat the file as living documentation. When you rename a script, move a folder or delete a helper, update AGENTS.md in the same pull request. Commands that no longer exist are worse than no commands at all.

A 2-minute audit

Before you close this tab, open your AGENTS.md and check:

1. Is there a CLAUDE.md or CLAUDE.local.md that shadows it? If so, add @AGENTS.md.
2. Are install, build, test and lint written as exact commands?
3. Would the agent get each line wrong without it?
4. In a monorepo, does each package have its own short file?
5. Are secrets and destructive actions enforced in settings, not just written down?
6. Did you confirm it loads in every tool your team uses?

AGENTS.md won't make an agent smarter. It removes the guessing about your project, and that only works if the file is short, concrete, current and actually loaded.

If you want to go deeper, I put the essentials together in a free cheat sheet: AGENTS.md Quick-Start Cheat Sheet. It includes a complete, copy-ready example and the cross-tool setup. When you need the full reference, with the monorepo hierarchy, real-world walkthroughs and a 30-day adoption plan, the next step is AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

This article was written with the assistance of AI and reviewed by the author.