AGENTS.md Not Loading? How to Debug It in 2026

Search “how do I know if Codex has loaded my AGENTS.md file” and you’ll find almost nothing written about it directly. Search GitHub instead and you’ll find dozens of open and recently-closed issues, across nearly every agentic coding tool, reporting the same category of bug: the instruction file is sitting right there in the repo, and the agent behaves as if it isn’t.

This is not one bug. It’s a structural problem with how instruction files work: they’re plain text injected into a prompt, not a config schema the tool validates. When it doesn’t apply, most tools give you no error — just an agent that quietly does its own thing. This guide is a tool-by-tool checklist for finding out why, sourced from each vendor’s own documentation and their public issue trackers.

”Not loading” and “not being followed” are different bugs

Anthropic’s own configuration-debugging docs make this split explicit, and it’s the most useful mental model for every tool here, not just Claude Code: first confirm the file was read into context at all, and only then worry about whether the instructions in it are being followed.

These have different causes and different fixes:

• Not loaded — wrong filename, wrong directory, file too large and truncated, an override file shadowing it, or the tool launched from outside the directory it scans. Fix: file placement and naming.
• Loaded but not followed — the file is in context, but the instruction is vague, contradicts another instruction, or is competing for attention in a long session. Fix: rewrite the instruction, or move it to a hook/lint rule that’s enforced instead of suggested.

Skipping this split is why people spend an hour rewriting an instruction ten different ways when the real problem is the file never made it into the prompt.

Quick reference: does your tool even read AGENTS.md?

Details and sources for each row below.

Claude Code: it isn’t reading AGENTS.md, by design

Get the premise right first: this isn’t a bug to fix, it’s documented behavior. Anthropic’s memory docs are direct about it: Claude Code reads CLAUDE.md, not AGENTS.md. If you only have an AGENTS.md in the repo, Claude Code has nothing to load.

The fix is a one-line import at the top of CLAUDE.md:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Or, if you don’t need Claude-specific additions, a symlink does the same job:

ln -s AGENTS.md CLAUDE.md

(We’ve covered the three integration patterns — import, symlink, and /init behavior — in full in our dedicated Claude Code × AGENTS.md guide. This section is specifically about verifying it actually took.)

Verification: run /context in a session and look under Memory files. If your CLAUDE.md isn’t listed, Claude never saw it — full stop, no amount of instruction rewriting will help. /memory opens the files directly if you need to check contents. /doctor catches invalid settings files and duplicate installs that can silently break loading.

Current gotchas straight from Anthropic’s own troubleshooting table:

• A CLAUDE.md in a subdirectory is not loaded at session start — it loads on demand, the first time Claude reads a file in that directory with the Read tool. If your instructions live two folders down and Claude hasn’t opened a file there yet, they’re not in context.
• The built-in Explore and Plan subagents skip CLAUDE.md entirely. Custom subagents you define yourself load it the same way the main session does — but Explore/Plan don’t. Restate anything critical directly in the prompt you hand them.
• After /compact, the project-root CLAUDE.md is re-read from disk and re-injected automatically. Nested CLAUDE.md files are not re-injected — they reload the next time Claude touches a file in that subdirectory. If an instruction “disappeared” mid-session, check whether it lived in a nested file.
• For a clean-room test, claude --safe-mode disables all customization (CLAUDE.md, skills, hooks, MCP, plugins) so you can confirm the bug is configuration-related before you go hunting file by file.

OpenAI Codex CLI: precedence is well-documented, but two live bugs break the model

Codex’s own AGENTS.md guide lays out the discovery order clearly: at the global level it checks ~/.codex/AGENTS.override.md first, then ~/.codex/AGENTS.md. At the project level, it walks from your git root down to your current directory, checking AGENTS.override.md, then AGENTS.md, then any names configured in project_doc_fallback_filenames, at every level. Files concatenate root-to-leaf, so instructions closer to your working directory win on conflict. There’s also a documented 32 KiB combined size ceiling (project_doc_max_bytes) — Codex stops adding files once it hits that limit, and empty files are skipped outright.

Verification: the simplest check that doesn’t depend on any specific CLI flag — ask the agent to quote a distinctive line from your AGENTS.md in its first response. If it can’t, the file didn’t make it into context.

Two gotchas currently open on openai/codex, both from this repo’s own tracker:

• Issue #30789 (filed July 2026): AGENTS.md discovery stops at a git submodule boundary — the superproject’s AGENTS.md gets silently skipped once Codex is working inside a submodule. If your project uses submodules, don’t assume the root file still applies once you’re a few directories deep into one.
• Issue #25747 (filed June 2026): the Windows desktop app running under WSL mode reads the Windows-side AGENTS.md instead of the one in your WSL filesystem. If you edit AGENTS.md inside WSL and don’t see the change reflected, this is why.

Historically, there’s also a well-known report (#4466) of AGENTS.md being ignored after upgrades and a related one (#2927) about instructions being dropped after /compact. Both were closed by maintainers as resolved, but users reported recurrence months later — worth checking your Codex version if you hit either symptom, since this class of regression has resurfaced more than once.

Cursor: reads AGENTS.md, but the verification story is thin

Cursor documents AGENTS.md as a direct alternative to its own .cursor/rules format — drop it in the project root (nested subdirectory support has also shipped) and it’s read alongside Team → Project → User rules. Unlike Claude Code and Codex, Cursor doesn’t publish a slash command or CLI flag specifically for confirming an AGENTS.md file loaded, and the exact precedence between AGENTS.md and .mdc rule files at the same directory level isn’t spelled out in the docs as of this writing.

Practical verification, absent an official command: ask the agent to restate a specific, unusual instruction from your AGENTS.md — the same trick as Codex. If Cursor can’t produce it, check that the file is at the exact project root Cursor considers active (not a parent folder you’re symlinked from, not a workspace subfolder if you opened Cursor one level up).

One structural limitation worth knowing: AGENTS.md can’t carry the YAML frontmatter that .mdc rule files use for path-scoping and alwaysApply behavior. If you’re relying on a rule firing only for certain file types, that has to stay in .cursor/rules/*.mdc — AGENTS.md in Cursor is closer to a flat, always-on instruction file.

GitHub Copilot: CLI, coding agent, and copilot-instructions.md all behave differently

This is the tool where “which Copilot” matters most, because GitHub ships several distinct products under one name:

• Copilot CLI reads AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md.
• Copilot coding agent (the async, PR-opening agent) added AGENTS.md support in August 2025, including nested per-directory files.
• Copilot in VS Code applies both file types together.

The gotcha: Issue #489 on github/copilot-cli documents that when both .github/copilot-instructions.md and AGENTS.md exist in the same repo, the CLI applies only copilot-instructions.md and silently drops AGENTS.md — while VS Code, given the identical repo, applies both. The reporter’s own test is a clean way to check your setup: put a distinct marker string in each file, then ask a simple question in the CLI. If only one marker comes back, you’ve hit this.

Verification: there’s no dedicated introspection command for Copilot CLI at time of writing. The marker-string trick above (also usable for Codex and Cursor) is the most reliable manual check.

The checklist: run through this before you rewrite a single instruction

1. Filename and case — AGENTS.md, not agents.md or Agents.MD, on case-sensitive filesystems.
2. Location relative to where you launched the tool — most of these tools resolve paths from your working directory or git root, not from wherever the file “logically” belongs.
3. An override file shadowing it — Codex’s AGENTS.override.md and Claude Code’s local/managed CLAUDE.md tiers both take precedence silently. Check for one before assuming the base file is broken.
4. Size limits — Codex caps combined instruction files at 32 KiB and drops anything past that threshold without an error.
5. Subdirectory vs. root loading semantics — Claude Code only loads nested CLAUDE.md on demand; Codex issue #30789 shows submodule boundaries can stop discovery entirely. Don’t assume “it’s somewhere in the repo” is good enough.
6. Competing instruction files in the same tool — Copilot’s CLI/copilot-instructions.md conflict is the clearest example, but any tool that reads two file types can have one silently win.
7. Ask the agent to quote it back. This single test — “quote line 3 of AGENTS.md” — separates “not loaded” from “loaded but ignored” faster than anything else on this list, and it works the same way across every tool above.

Frequently Asked Questions

Q1. How do I know if Codex has loaded my AGENTS.md file?

Ask it directly: request that the agent quote a specific, distinctive line from the file in its response. If it can’t, the file isn’t in context — check for a submodule boundary (issue #30789), a WSL/Windows path mismatch (#25747), or an AGENTS.override.md shadowing it before assuming the file is malformed.

Q2. Why does Claude Code ignore my AGENTS.md file?

By design — Claude Code reads CLAUDE.md, never AGENTS.md directly. Add @AGENTS.md as the first line of a CLAUDE.md file (or symlink CLAUDE.md to AGENTS.md), then confirm it loaded by running /context and checking the Memory files list.

Q3. Does Cursor read AGENTS.md automatically?

Yes, as an alternative to .cursor/rules, at the project root and in nested subdirectories. Cursor doesn’t document a specific verification command, so the most reliable check is asking the agent to restate a distinctive instruction from the file.

Q4. Why did my AGENTS.md instructions disappear after using /compact?

In Claude Code, root-level CLAUDE.md is automatically re-read after /compact; nested CLAUDE.md files are not, and only reload the next time Claude reads a file in that subdirectory. In Codex, users have historically reported (and maintainers have historically closed) issues where /compact drops AGENTS.md instructions — if you see this on a current build, it may be a recurrence worth reporting.

Q5. Why does GitHub Copilot CLI ignore AGENTS.md when copilot-instructions.md exists?

This is a documented open issue (github/copilot-cli #489): when both files are present, the CLI applies only .github/copilot-instructions.md and drops AGENTS.md, even though Copilot in VS Code applies both from the identical repo. There’s no workaround beyond consolidating instructions into copilot-instructions.md until it’s fixed.

Q6. What’s the difference between an instruction file “not loading” and “not being followed”?

Not loading means the tool never put the file’s content into the model’s context at all — a filename, location, override, or size problem. Not being followed means the content is in context but the model isn’t complying — usually because the instruction is vague, contradicts another rule, or is competing with a lot of other context in a long session. Diagnose which one you have before rewriting anything: /context in Claude Code, or the “quote it back” test in Codex/Cursor/Copilot, tells you which bucket you’re in.

Q7. Do subdirectory AGENTS.md or CLAUDE.md files load automatically at startup?

Not in Claude Code — nested CLAUDE.md files load only when Claude reads a file in that specific subdirectory, not at session launch. Codex’s behavior is closer to “loads along the path to your working directory” but can stop early at a git submodule boundary. Don’t assume a file two folders deep is in context just because it exists.

Related Reading on The Prompt Shelf

• Does Claude Code Support AGENTS.md? The Complete 2026 Reference
• AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)
• AGENTS.md vs CLAUDE.md: Tool Support Compared (2026)
• GitHub Copilot Instructions.md: The Complete Guide
• Testing AGENTS.md Effectiveness: A Benchmark Approach

Keep Your Instruction Files Out of Reach of Secrets, Too

While you’re auditing what actually loads from your repo root, do the same check for secrets. 1Password CLI’s op run injects API keys and tokens at runtime instead of letting them sit in a .env file an AI agent — or a teammate — might read alongside your AGENTS.md. Same principle as instruction files: don’t assume something is safe just because it’s not causing an obvious error.