Keyboard shortcuts

jk
move through the list
↵
open the selected item
a
ask a question
nucw
tabs: new, unanswered, active, top
⌘↵
post the answer you are writing
/or⌘K
search
t
switch theme
?
this list
AskVibe
AskSign in
…
Sign in
Question

Codex ignores the rules in my AGENTS.md completely

Solved · 229 viewsasked by dana_ships
codexpromptingcontext-window

I wrote an AGENTS.md with our rules: use pnpm, never touch the legacy/ folder, run the tests before saying it is done. Codex happily runs npm install, edits files in legacy/ and says "done" without running anything.

The file lives in docs/AGENTS.md next to the rest of our documentation.

What I’ve tried

Made the rules shorter and put them in capitals. Also pasted the file into the first message, which works for that session but I don't want to do that every time.

Comment
Where exactly is the file? Root of the repo or somewhere else? jonas_k

2 answers

Marked as helpful by the asker
mira_dev

That is the problem: docs/AGENTS.md only counts when Codex works inside docs/. It reads AGENTS.md from your home folder (~/.codex/AGENTS.md), from the repo root, and from the folders on the way down to where you are working. Move it to the root of the repo.

Two things that make the rules stick better once it is found:

  • Give the command, not the wish. "Run pnpm test before you say you are done" works better than "make sure tests pass".
  • Keep it short. A page of rules gets followed; five pages get skimmed.

You can check what it loaded by asking at the start of a session: "Which AGENTS.md files did you read?"

Comment
Moved it to the root and it ran pnpm test on its own on the next task. I feel silly, thanks. dana_ships
felix_codes

Mira's fix is the main one. For the legacy/ rule specifically, put a second, tiny AGENTS.md inside legacy/ itself:

# legacy/
Do not edit files in this folder. If a task seems to need a change here, stop and ask.

Files closer to the code Codex is touching take precedence over the ones further up, so a rule that lives in the folder it protects is much harder to miss than one line in a long root file. Same trick works for a migrations/ folder.

Comment
Did the legacy/ one too. On the next task it stopped and asked instead of editing. First time ever. dana_ships

Related

One long Claude Code session per feature, or a fresh one for every step?4 ans.
Do subagents see what the main Claude conversation already found?solved
Hit the Claude Code weekly limit on a Tuesday (Max 5x). How are people working all day on this?solved
Cursor forgets everything about my app when I open a new chatsolved
What is CLAUDE.md and do I have to make it myself?solved

Your answer

Sign in to write an answer