AGENTS.md Not Working? 8 Fixes for Codex and Other Agents

Published 2026-10-30 · 6 min read · by AgentKit Co

You added an AGENTS.md, and the agent still runs the wrong test command or ignores your conventions. The cause is almost always on a short list: the file isn't loading, a different file is winning, it got cut off, or it loads and is too vague to follow.

Most of this page is about OpenAI Codex, because its loading rules are the most precisely documented. Everything was checked against OpenAI's Custom instructions with AGENTS.md guide and the agents.md site on 2026-10-30. Agents change fast, so re-check anything you depend on. If you use Claude Code, Cursor or Copilot, the section near the end points you to the right fix for those tools.

1. Ask the agent what it loaded

Don't guess. From your repository root, run:

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

OpenAI's guide says Codex should echo guidance from your global and project files in precedence order. If your rules aren't in the answer, Codex can't see them, and nothing else on this page matters until it does. For a subfolder, use codex --cd subdir --ask-for-approval never "Show which instruction files are active."

To audit it properly, the guide suggests a plaintext log: codex -c log_dir=./.codex-log, then check ./.codex-log/codex-tui.log.

2. You launched from the wrong place

Codex builds its instruction chain once per run (in the interactive TUI, once per session). It starts at the project root, usually the Git root, and walks down to your current working directory, picking up at most one file per directory. Then it stops.

That has two consequences people trip on:

• An AGENTS.md deeper than where you launched is not part of the chain. If you start Codex at the repo root, services/payments/AGENTS.md is not in the list it builds at startup. Start Codex in that folder (or use --cd services/payments) when you want those rules.
• No project root means only one folder. If Codex can't find a project root, it checks only the current directory. Run git init or launch from inside the repo.

The docs' troubleshooting list starts with the same check: make sure you're in the repository you think you are, and that codex status reports the workspace root you expect.

3. The file is empty, or the name is wrong

Codex skips empty files. It also only looks for these names, in this order, in each directory:

1. AGENTS.override.md
2. AGENTS.md
3. Any names you listed in project_doc_fallback_filenames

So agents.md in a different case, AGENT.md, .agents.md or TEAM_GUIDE.md are ignored unless you add them to the fallback list. The agents.md site suggests renaming old files and leaving a symlink for tools that still expect the old name:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

4. An override file is winning

In each directory, AGENTS.override.md beats AGENTS.md, and only one of them is used. The same applies in your Codex home: ~/.codex/AGENTS.override.md replaces ~/.codex/AGENTS.md.

Overrides are meant to be temporary, which is exactly why they get forgotten. If the wrong guidance appears, look for an AGENTS.override.md higher in the tree or under ~/.codex, and rename or delete it.

5. Codex is reading a different home folder

Your global file lives in the Codex home directory, which is ~/.codex unless CODEX_HOME is set. If you edited ~/.codex/AGENTS.md and nothing changed, check:

echo $CODEX_HOME

A non-default value means Codex is reading a different home than the one you edited. This often happens with a per-project automation profile.

6. The combined file hit the size cap

Codex concatenates every file in the chain, root first, and stops adding files once the total reaches project_doc_max_bytes, which is 32 KiB by default. Because nested files are added last, they're the ones that fall off when a big root file eats the budget.

Two fixes, from the docs:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

or, better, cut the root file and move area-specific rules into nested AGENTS.md files. A shorter file is also easier to follow; see how to write an AGENTS.md for what to keep.

7. Two files disagree

Codex joins files with blank lines, and files closer to your current directory appear later, so they override earlier guidance. The agents.md FAQ states the general rule for every agent: the closest AGENTS.md to the edited file wins, and explicit chat prompts override everything.

So check three places when a rule is ignored: a nested file that says something different, your global ~/.codex/AGENTS.md, and your own prompt. "Just quickly fix this" in chat can outrank "always run the tests" in the file.

8. The rule is too vague to follow

If the file loads and the agent still drifts, read the rule as a stranger would. "Write good tests" can't be checked. "Run pnpm test --filter web after changing anything in apps/web" can. The agents.md FAQ says agents will try to run the checks you list, so name the exact command.

And remember these files are guidance, not enforcement. If something must never happen, back it with a real guard: an approval or sandbox setting (see Codex config.toml examples), a git hook or a CI check.

Using a different agent?

AGENTS.md is an open format, but each tool loads it its own way:

• Claude Code reads CLAUDE.md. It can read AGENTS.md too, but by default only when no CLAUDE.md exists. The reliable fix is a CLAUDE.md that contains @AGENTS.md. Details in CLAUDE.md not working.
• Cursor lists AGENTS.md as one of its rule types alongside .cursor/rules. See Cursor rules not working.
• GitHub Copilot reads AGENTS.md, and the nearest one in the tree wins. See copilot-instructions.md examples.
• Gemini CLI reads GEMINI.md unless you set context.fileName in .gemini/settings.json. See GEMINI.md examples.
• Aider needs read: AGENTS.md in .aider.conf.yml, per the agents.md site.

A quick checklist

1. The agent can summarize your rules back to you (fix 1).
2. You launched from the folder whose rules you want (fix 2).
3. The file is non-empty and named exactly AGENTS.md (fix 3).
4. No forgotten AGENTS.override.md here, above, or in ~/.codex (fix 4).
5. CODEX_HOME points where you think (fix 5).
6. The combined chain is under 32 KiB, or you raised the cap (fix 6).
7. No nested file, global file or prompt contradicts the rule (fix 7).
8. Each rule names a concrete command or check (fix 8).

Start from a working file

Our free AGENTS.md generator builds an AGENTS.md in your browser from your package.json or pyproject.toml, plus matching CLAUDE.md, Cursor, Copilot, GEMINI.md and Kiro files so the tools can't drift apart. For templates covering 12 stacks and prompts that audit and test them, see the AI Coding Agent Config Kit.

Want ready-made files? See our copy-paste AGENTS.md examples and AGENTS.md vs CLAUDE.md vs Cursor rules.

Sources: OpenAI, Custom instructions with AGENTS.md, and agents.md (both checked 2026-10-30). AgentKit Co is not affiliated with OpenAI, the Agentic AI Foundation or the other tools named. This guide was written with AI assistance and checked against the pages above.

Keep reading