Claude Code Was Silently Ignoring Your Instructions File — And Wouldn't Tell You

Independent testing found that Claude Code could silently fail to load a project's AGENTS.md file — the instructions file meant to guide the assistant's behavior — whenever a remote feature-flag check couldn't be completed. No error. No warning. The repository would still have the file; Claude Code would just proceed as if it didn't exist.

That's a real problem, because instruction files aren't decoration. Teams use them to set coding conventions, testing requirements, repository boundaries, and security-sensitive workflow rules. Anthropic added AGENTS.md support in Claude Code 2.1.277 as a fallback for repos without a CLAUDE.md file — meant to make Claude Code compatible with a convention already used across multiple coding-agent tools.

The specific trigger, according to testing on version 2.1.280 and a corroborating GitHub issue: AGENTS.md loading was gated by a remotely evaluated flag. When that flag couldn't be checked — for example, with DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 set, including in Bedrock and Vertex AI setups — the file simply didn't load, with no indication to the user that anything had changed.

That silence is the real defect, not the failure itself. A visible error ("AGENTS.md wasn't loaded because the feature check failed") would let developers adjust and move on. Instead, the repository looked fully configured while the instructions governing the assistant's behavior quietly disappeared — a particularly awkward outcome for teams that deliberately restrict network traffic for privacy reasons and reasonably expect a local markdown file to behave, well, locally.

There is a reported workaround: adding a CLAUDE.md that explicitly imports AGENTS.md with @AGENTS.md continued to work even when the automatic fallback didn't. And Anthropic's current documentation describes different behavior — suggesting unavailable telemetry shouldn't block AGENTS.md loading in the current default mode. But there's no confirmation of exactly when that changed or whether it fully addresses the earlier design.

Bottom line: This isn't evidence that Claude Code is broadly unreliable — it's a specific, reproducible reported issue in a specific version and configuration. But it's a useful reminder for teams running restricted-network setups: verify your instruction files are actually loading, especially if you're using telemetry restrictions, Bedrock, or Vertex AI. A configuration that fails silently isn't really configurable at all.