Claude Code shipping AGENTS.md support should've been a quiet win. One portable instruction file. Less dual-maintain. Everyone goes home early.

Then the details arrived, and the details are where the agents live.

@the_actual_kyle celebrated the obvious upside: Claude Code now reads AGENTS.md when there's no CLAUDE.md. @KevinShengHui was sharper about the bill: if CLAUDE.md exists anywhere in the project path, AGENTS.md is skipped. Portable file, not portable behaviour.

I'll say the thesis once, then leave it alone.

Portable AGENTS.md is not the same as portable behaviour. Claude Code's support is a fallback when CLAUDE.md is missing, and for a window the loader sat behind a remote feature flag that failed closed (telemetry / nonessential traffic off meant a silent skip). The durable craft lesson: verify the harness actually ingested the file. A one-line CLAUDE.md with @AGENTS.md is the boring escape hatch.

I've already written about AGENTS.md as intent versus control flow, and about DESIGN.md. This is adjacent. Same family of files. Different failure mode: the harness nodding along while quietly not loading them.

The marketing-shaped reading of this feature is: stop maintaining two instruction files. The engineering reading is less tidy.

By default, Claude Code treats AGENTS.md as a fallback. No CLAUDE.md in the path, it looks for AGENTS.md. CLAUDE.md present (including a personal CLAUDE.local.md that counts as one), and the shared file can be ignored unless you've changed Project instructions in /config.

That's not a bug. It's a precedence rule. It's also the unsexy detail launch posts skip, because "we support the portable file" sounds better than "we support it when our own file isnt already vetoing it".

If your teams already keep a chunky CLAUDE.md for Claude-specific quirks, you havent unified anything. You've added a second file that only loads in the empty case.

Then came the messier scrap. Independent writeups (szypowi.cz and others amplifying GitHub issue #95690) showed the agents-md loader sitting behind a remote flag, tengu_agents_md_mod, with a fail-closed default. Sessions that couldnt fetch that flag (DISABLE_TELEMETRY=1, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, Bedrock / Vertex / gateway) could skip AGENTS.md with no warning.

@JoeIngeno, @markhuang_ai, and @surendra_ai hit the same nerve: local markdown gated on a remote switch. Two machines, same version, different context.

Be accurate about the timeline. Claude Code v2.1.281 reportedly fixed the telemetry-disabled / Bedrock / Vertex / gateway cases. Good. Update. Don't cosplay that current builds are still broken if you've moved on.

The craft smell still stands. A silent fail-closed gate on local project instructions is a bad pattern even when a later patch removes this instance. Privacy toggles should cost you diagnostics. They shouldnt quietly switch off reading a file from your own working directory.

The workaround people landed on is almost insultingly small. A one-line CLAUDE.md that imports the portable file via @ path reference, not a /import copy that drifts:

That route goes through CLAUDE.md import behaviour, which didnt depend on the flag. Yes, it's one extra file. Yes, that is exactly the sprawl AGENTS.md support was meant to remove. It's also how you stop guessing.

If you want to be less polite about it: put a canary phrase in AGENTS.md, ask the session what the project instructions say, and refuse to trust the changelog until the canary shows up. Marketing said support. The harness has to prove ingestion.

While everyone was arguing about instruction files, @mikemurphyai called out the sibling friction: Claude Code Skills under .claude, Codex Agents under .codex. Same job. Two trees. Update one, open the other agent, patch the twin.

So even when the root AGENTS.md story improves, the surrounding skill/agent surfaces can still ask your teams to dual-maintain. Portability is a spectrum. Announcing support for a filename is one notch on it. Shared behaviour across harnesses is another.

I'm not asking for a grand unified markdown format overnight. I am asking that we stop pretending a fallback plus a silent gate equals "one instruction file forever".

None of this needs a ceremony. A short checklist beats another opinion piece about agent standards:

• Keep the portable AGENTS.md as the source of truth for cross-harness intent.

• Know that Claude Code's default still lets CLAUDE.md veto the fallback.

• If you care about Claude specifically, use the one-line @AGENTS.md import (or the /config mode that loads both).

• Canary-test that the file reached the model after upgrades, privacy toggles, or gateway changes.

• Treat silent skip of local instructions as a harness bug class, even when this instance got patched.

That's it. No framework. No manifesto. Just refuse to confuse "file exists on disk" with "harness loaded it".