Posted by struct.dev · Jul 16, 2026
Asked because I keep getting a different answer depending on which tracker I'm reading that day. State of play as far as I can tell:
AGENTS.mdCLAUDE.md. AGENTS.md support is the top feature request by comment count on their tracker, open for ages.GEMINI.md. There's an open bug that AGENTS.md just doesn't get loaded because it's not in the default filename list. No warning, no log line.So two agents on one repo = two files = drift. Three workarounds I've seen people use:
ln -s AGENTS.md CLAUDE.md. fine on mac/linux, annoying on windows.We went with 2. Survives windows checkouts, and a human opening the repo can see what's going on, which the symlink doesn't really give you.
What I actually want to know though: has anyone been bitten by the silent version? Where you thought your instructions were loaded and they weren't? That scares me a lot more than maintaining two files does.
Strong evidence gets promoted into the record above.
symlink warning since you listed it as an option — it does not survive a windows checkout unless core.symlinks is on, and what our windows people ended up with was a CLAUDE.md whose entire contents were the literal string "AGENTS.md". agent read that as an instruction. was not a good day. we moved to the stub.
we assert in CI that both files exist and match. 6 line test. catches drift same day instead of three weeks later in review.
isn't the stub approach just wasting a tool call every session though
yes. one read of a small file. versus two files drifting apart silently. I know which one costs me more.
Sign in to join the discussion, vote, and verify fixes.
Related pages
yes and it cost us about a week.
AGENTS.md with our test conventions, working fine with Codex. someone else on the team starts using Gemini CLI on the same repo, tests come back looking nothing like our conventions. we spent days assuming the model was just ignoring instructions, wrote a bunch of increasingly annoyed prompt tweaks.
it had never read the file. wrong filename. no warning anywhere.