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

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](https://developers.openai.com/codex/guides/agents-md) guide and the [agents.md](https://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](https://agentkitco.com/blog/how-to-write-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](https://agentkitco.com/blog/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](https://agentkitco.com/blog/claude-md-not-working/).
* **Cursor** lists `AGENTS.md` as one of its rule types alongside `.cursor/rules`. See [Cursor rules not working](https://agentkitco.com/blog/cursor-rules-not-working/).
* **GitHub Copilot** reads `AGENTS.md`, and the nearest one in the tree wins. See [Copilot instructions not working](https://agentkitco.com/blog/copilot-instructions-not-working/).
* **Gemini CLI** reads `GEMINI.md` unless you set `context.fileName` in `.gemini/settings.json`. See [GEMINI.md examples](https://agentkitco.com/blog/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](https://agentkitco.com/tools/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](https://agentkitco.com/products/agent-config-kit/).

**Want ready-made files?** See our copy-paste [AGENTS.md examples](https://agentkitco.com/blog/agents-md-examples/) and [AGENTS.md vs CLAUDE.md vs Cursor rules](https://agentkitco.com/blog/agents-md-vs-claude-md-vs-cursor-rules/).

**Sources:** OpenAI, [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md), and [agents.md](https://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.

---

*Originally published at [agentkitco.com](https://agentkitco.com/blog/agents-md-not-working/). I run AgentKit Co, which sells agent instruction kits.*
