Why AI Coding Agents Ignore Repository Instructions

More than 60,000 repositories now ship an AGENTS.md file to steer their AI coding agents — and a meaningful chunk of those agents never read it. That’s the uncomfortable reality behind why AI coding agents ignore repository instructions: the failure is rarely about the model being disobedient. It’s about precedence rules, feature flags, file formats, and redundant content quietly nullifying your instructions before the first token of code gets generated.

If you’ve written careful build commands and conventions into a repo-level instruction file and your agent still reaches for the wrong test runner, this post is for you. The causes are more mechanical than mysterious, and most of them are fixable once you know where to look.

Why do AI coding agents ignore repository instructions?

The short answer: your file has to survive three gauntlets — discovery, precedence, and content quality — and it can fail at any one of them. Most debugging guides only cover the third.

Discovery is the dumbest failure mode and the most common. The agent simply never loads the file. Precedence is subtler: the file loads, but a higher-ranked instruction source overrides or dilutes it. Content quality is the one everyone writes about — the file loads, gets read, and actively hurts performance because it repeats what the agent already knows.

What I call the execution layer shift is visible here: as code generation itself commoditizes, the differentiation — and the failure modes — move into the operational plumbing around the model. Instruction file handling is exactly that kind of plumbing. It’s unglamorous, vendor-specific, and it decides whether your conventions actually reach the model.

Let’s walk each gauntlet with the evidence.

Is your agent even loading the file?

Sometimes the answer is no, and the agent won’t tell you. The Claude Code saga from September 2026 is the cleanest documented example.

Claude Code 2.1.277, released on September 18, 2026, added native AGENTS.md support — but only as a fallback that loads when no CLAUDE.md exists in the working directory or any directory above it. If both files exist, CLAUDE.md wins and AGENTS.md is ignored entirely. It’s a fallback, not a merge.

Then it got worse. Rohit Raj’s deep dive into the release found the feature was gated behind a remote feature flag (tengu_agents_md_mod) that was off by default at launch. Sessions with telemetry disabled, and users on Amazon Bedrock, Microsoft Vertex, or Foundry, silently received no instructions at all until version 2.1.280 fixed the issue. A post titled “Claude Code reads AGENTS.md only when telemetry is on” hit the Hacker News front page with 480 points because, for a large class of enterprise users, the feature had shipped and done nothing.

The lesson generalizes beyond one vendor. Before you rewrite a single line of your instruction file, verify the load:

1. Run a canary test — put a distinctive, harmless instruction in the file (“always start your first reply with the word ‘acknowledged’”) and see if the agent obeys.
2. Check your delivery path. Cloud provider gateways, telemetry settings, and version lag can all gate instruction loading.
3. Confirm which file actually won if multiple instruction files exist in the directory tree.

Five minutes of verification beats an afternoon of prompt-tuning a file nobody reads.

Where does your file rank in the precedence order?

Even when the file loads, it may sit at the bottom of a hierarchy you didn’t know existed. GitHub Copilot makes this explicit, and the ranking surprises people.

Per Start Debugging’s breakdown of Copilot’s instruction systems, GitHub’s documented precedence places .github/instructions/*.instructions.md at rank 2a, .github/copilot-instructions.md at rank 2b, and AGENTS.md at rank 2c — the lowest of the repository tier. So if you’re relying on AGENTS.md to enforce guardrails in Copilot, it’s the first thing that loses when instructions conflict. We covered the cost side of this enforcement gap in AGENTS.md vs Copilot Instructions.

The same analysis documents two more gotchas. Copilot Chat on github.com ignores glob-matched .instructions.md files and AGENTS.md entirely, reading only the repo-wide .github/copilot-instructions.md. And Copilot Memory — the store Copilot writes for itself — is read by only three surfaces (cloud agent, code review for repo facts, CLI), expires after 28 days of disuse, and doesn’t appear in the deterministic precedence list at all. If you thought Memory was reinforcing your conventions, it mostly isn’t.

The practical rule: put hard rules in the highest-precedence deterministic file your primary tool reads, and treat everything else as advisory. If you run multiple agents against one repo, that means understanding each tool’s hierarchy rather than assuming one file governs all of them.

Is the file itself worth reading?

Here’s the contrarian finding: sometimes agents ignore your instructions because ignoring them is the correct response. The benchmark data cuts both ways.

ETH Zurich data cited in an AGENTS.md best practices guide shows human-written context files deliver a 4% improvement in task resolution rates — real, but modest. The same source notes these files impose a 20% “tax” on inference costs at every execution step, because the instructions ride along in context whether or not they’re relevant to the current task. You’re paying a fifth more on every step for a single-digit gain.

It gets worse for auto-generated files. LLM-generated AGENTS.md files often lower success rates by 0.5% to 2%, because they tend to repeat information already visible in the repository — adding noise that confuses agent reasoning. The failure mode is almost always redundancy. If your repo already has thorough documentation, an instruction file that restates it becomes a burden: the agent either ignores the duplicate content or gets confused by it.

This connects to a broader pattern we’ve tracked in how AI coding agents build context: more context isn’t better context. The files that earn their 20% tax are the ones filling genuine information gaps — non-obvious tooling decisions, specialized CI setups, conventions that can’t be inferred from the file tree. Niche internal repositories benefit most. A well-documented open-source-style repo often doesn’t need the file at all.

So before blaming the agent, audit the file. Delete anything the agent could discover itself. Keep only what’s additive.

Why did instruction file sprawl happen at all?

The multi-file mess wasn’t an accident — it was the default outcome of competing vendors each inventing their own convention.

AGENTS.md originated in OpenAI’s Codex tooling, but it’s no longer an OpenAI house format: it’s now stewarded by the Agentic AI Foundation under the Linux Foundation, with both OpenAI and Anthropic as founding platinum members, per DevOps.com’s coverage. The format is read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, Factory, Jules, and roughly twenty other tools. Claude Code was the conspicuous holdout until 2.1.277.

That holdout period is what created the sprawl. Teams running multiple coding agents on the same repository had to maintain duplicate instruction files — CLAUDE.md for Claude Code, AGENTS.md for everything else — or fake it with symlinks and one-line imports, per InfoWorld’s reporting. Copies drift. An agent ends up following a build command that stopped working a month ago. The “ignored instructions” you observe are sometimes just stale instructions in the file that particular agent happens to read.

One more wrinkle worth knowing: instruction files are trusted-authority surfaces, and convergence on a single file makes that surface more attractive to attackers. If you’re consolidating onto one AGENTS.md, read our piece on hardening AGENTS.md against poisoning before you treat it as governed configuration.

What should you standardize on?

Standardize on one cross-vendor file, keep it minimal, and verify loading per tool. The era of per-vendor instruction files is ending, and the remaining differences are in precedence behavior and delivery-path caveats — not in whether the format is read.

Here’s how the major tools compare as of late September 2026:

Tool	Instruction file behavior	Entry pricing	Best fit
Claude Code	CLAUDE.md wins; AGENTS.md fallback since 2.1.277 (caveats on Bedrock/Vertex/Foundry)	Pro $20, Max $100–$200 per CalculatorAI	Terminal-first teams, scripted agent workflows
GitHub Copilot	AGENTS.md at rank 2c (lowest repo tier); github.com Chat reads only copilot-instructions.md	Pro $10, Business $19/user per Contra Collective	GitHub-centric orgs wanting seat-based predictability
Cursor	Reads AGENTS.md natively	Pro $20, Pro+ $60, Ultra $200 per CalculatorAI	Editor-integrated agent work
OpenAI Codex	AGENTS.md is its native format	Plus $20, Pro $100–$200 per CalculatorAI	Teams already on ChatGPT plans

Notice what the table doesn’t show: a meaningful cost argument for picking one over another. For teams running autonomous agents daily, real spend converges toward a $60–$200 per developer range regardless of which logo is on the plan — sticker price is nearly irrelevant at heavy usage. That frees you to choose on instruction handling and execution-layer fit instead of chasing the cheapest seat.

My recommendation, in order:

1. Consolidate on AGENTS.md as your single source of truth, with CLAUDE.md as a thin import or override only where you need Claude-specific behavior.
2. Curate ruthlessly. Human-written, gap-filling content only. If a line restates what the repo already shows, cut it — you’re paying 20% more inference for the privilege of confusing your agent.
3. Test the load path per tool and per environment, especially if you run agents through cloud provider gateways or with telemetry disabled.
4. Audit precedence quarterly. Vendors are shipping changes to instruction handling monthly, and last quarter’s hierarchy may not be this quarter’s.

The open question I’d leave you with: as instruction files converge into governed, cross-vendor configuration, who on your team owns them? The teams treating AGENTS.md like code — reviewed, versioned, tested — are the ones whose agents actually follow instructions. Everyone else is debugging ghosts.