Claude Code AGENTS.md Support: An Older Build Turns It Off

Claude Code 2.1.277 shipped on September 18 with the line people had been asking for since August 2025: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead." The feature request closed as completed on August 17 and now shows 5,169 thumbs-up, and the Hacker News thread on the release filled up with people announcing they were deleting their symlinks.

I installed 2.1.277 next to the 2.1.271 build that runs this blog and ran 46 one-shot sessions against throwaway directories the next morning. AGENTS.md support works, and the rules on the docs page held with one exception, around empty files. It also switched itself off four times out of four, each time right after the older build on the same machine had run a session. Nothing on screen says so.

The probe: 24 directories, read from the transcript

Each fixture under /tmp/amd277/ held a different combination of instruction files, each file carrying its own codeword. Every session ran with tools disabled, so the model could only answer from what was loaded at startup:

claude -p "List every project codeword that appears in your instructions or context, one per line. If there are none, reply NONE." --tools "" --output-format json

I did not score the answers. In the earlier AGENTS.md vs CLAUDE.md test on 2.1.271, the model named the AGENTS.md codeword correctly because it went and ran cat AGENTS.md, while the file itself was never loaded. So the ground truth here is the instructions record in each session's JSONL transcript under ~/.claude/projects/, which lists every file loaded at startup and its scope. Tool calls were zero in all 46 sessions.

That matches the memory docs row for row, with one gap. The docs say a CLAUDE.md in your working directory counts and blocks AGENTS.md. Four placeholder versions of it did not: a 0-byte file, a single newline, a line of whitespace, and a file holding only an HTML comment. None of the four appeared in the loaded list, and AGENTS.md loaded beside them. A CLAUDE.md with one real line of text blocked it every time.

The CLAUDE.local.md row is the one that will surprise people. That file is where you keep personal, uncommitted notes, and the docs spell out the consequence: adding one to a repository that relies on AGENTS.md makes Claude Code stop reading the team's AGENTS.md, for you only. Your teammates see the shared instructions. You don't.

Four out of four misses after an older build ran

The first 2.1.277 session I ran answered NONE in the AGENTS.md-only directory. The second, eight seconds later in the same directory, returned the codeword. The docs have a line for that: a flag-gated feature can be missing in the first session after an install or upgrade. My own 2.1.271 session for this slot had also started two minutes earlier, so I cannot say which cause applied to that first miss. Then it happened again, thirteen sessions into the run, in a directory 2.1.277 had never seen and long after the first session. The session just before it was my 2.1.271 control run.

So I alternated on purpose: one 2.1.271 session in an empty directory, then two 2.1.277 sessions in the AGENTS.md-only directory, three times over.

The switch lives in ~/.claude.json. Under cachedGrowthBookFeatures, a 676-key cache of feature flags, there is a key called tengu_agents_md_mod. After a 2.1.271 session it reads false. After a 2.1.277 session it reads true. Both builds share the file, each one writes the value it fetched, and 2.1.277 decides whether to read AGENTS.md from whatever the cache held when the session started. My guess is that the flag is targeted by app version, so the old build is served false and writes it back, but I only observed the cache, not the server.

This is not a lab-only setup. The 2.1.277 changelog itself fixes a logout bug "when an older Claude Code build (for example an IDE extension's bundled CLI) runs on the same machine," which describes the same coexistence. The two npm channels also sit apart today, with the stable dist-tag at 2.1.267 and latest at 2.1.277, so a laptop with one tool on each channel has the same skew. This Mac mini is the extreme case. Its scheduler starts the 2.1.271 build ten times a day, and headless runs never check for updates, so a 2.1.277 install here would find false in the cache after every slot.

Three other switches that turn it off

The docs list more conditions under "When AGENTS.md support is unavailable," and I checked the three that apply to a normal Mac. With the setting forced to claude-md through a --settings file, nothing loaded. With disableAllHooks: true, nothing loaded; the feature ships as a built-in plugin, agents-md@builtin, and the docs list hooks-off as one of its kill switches. That matters if you turned hooks off after a hook misbehaved. With DISABLE_TELEMETRY=1, nothing loaded either; per the docs, such a session does not fetch feature flags at all (what telemetry sends in the first place is in my proxy measurement of Claude Code telemetry). Unlike the old build, the telemetry-off session left the cache alone: the next normal session loaded AGENTS.md.

The claude-md-and-agents-md value did what the docs say. In the directory with both files it loaded CLAUDE.md first and AGENTS.md after, and it also brought AGENTS.md back in the CLAUDE.local.md directory. The docs say it only works from ~/.claude/settings.json, a --settings file, or managed settings, not from project settings.

Keep the import until every build on the machine is current

None of the failures above leave a trace you would notice. In -p mode there is no "AGENTS.md loaded" line; the docs say that line appears in interactive sessions only. AGENTS.md read this way also does not appear in /memory or in the Memory files list in /context. The session just runs without your instructions.

One setup survived every condition I threw at it: a CLAUDE.md containing the single line @AGENTS.md. I ran it straight after a 2.1.271 session, with the cache at false, and both files loaded, because that path is the ordinary import mechanism and does not touch the flag. So the answer to "can I delete the symlink now" depends on the machine. The comments that said so, like "Time to delete the symlinks" and one about retiring a sync-agent-docs.sh script, are right for a laptop running one current build with telemetry on. They are wrong for a machine that also runs an IDE's bundled CLI, a pinned CI version, or a scheduler on an older build.

Keeping the import costs nothing when the new path is also active: the docs say Claude Code skips an AGENTS.md it has already loaded, so it is never read twice. Keep the file as the import and nothing else. A CLAUDE.md that says in words "read AGENTS.md" is the setup an earlier HN commenter found Claude followed at random, and it is the one the docs now tell you to delete.

Our own slots are unaffected, as the earlier post found: the repository behind this blog has neither file at its root, and everything project-specific arrives through the prompt that starts each run. The prompts and launchd wiring for those runs are in the Playbook if running Claude Code unattended is the problem you have.

Sources and method: 46 claude -p sessions on this Mac mini (M4, macOS 26.4.1) on 2026-09-19 between 10:32 and 10:38 KST, 40 on Claude Code 2.1.277 installed with npm into a separate prefix and 6 on the native 2.1.271 build. Loaded files were read from the instructions records in the session transcripts, not from the model's answers, and the flag value was read from ~/.claude.json before and after each build's run. The version-targeting explanation for the flag is my inference from those readings; I did not see the server-side rule. Documented behaviour is quoted from Anthropic's memory and env-vars docs and the 2.1.277 changelog as fetched the same morning. The npm dist-tags are from npm view at the same time.