Claude Code reads AGENTS.md only when telemetry is on
A developer discovered that Claude Code's new AGENTS.md feature for project instructions silently fails if telemetry is disabled, sparking a debate on privacy, feature gating, and transparent software design. Anthropic's swift acknowledgment and fix impressed some, but others highlighted deeper concerns about reliance on remote flags for local functionality and general development practices in the AI era.
The Lowdown
A recent discovery reveals a significant quirk in Claude Code's handling of AGENTS.md, a file intended to provide project-specific instructions. The author, a user with telemetry intentionally disabled, found that this feature simply wouldn't work, leading to a silent failure where the model would proceed without ever reading the AGENTS.md file.
- The
AGENTS.mdloader plugin, designed to make project instructions accessible, is gated behind a remote feature flag,tengu_agents_md_mod. - If telemetry is off, preventing the flag from being fetched, the plugin remains unavailable, and the
AGENTS.mdfile is never read. - Attempts to enable it by setting environment variables like
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=0orDISABLE_TELEMETRY=0fail, as doenvblocks in.claude/settings.json. - A session-level override (
claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}') provides a temporary workaround. - The most robust solution found is to use a
CLAUDE.mdfile to@importtheAGENTS.md, bypassing the feature flag entirely. - The author argues this design is unacceptable, as a privacy setting should not silently disable core local functionality. Such a design disproportionately impacts privacy-conscious users and teams with strict network policies.
- Suggestions for improvement include decoupling local file reading from telemetry, providing warnings when
AGENTS.mdis skipped, and better support for global and shared instruction files and skills.
The core of the issue lies in the silent failure mode: users are left wondering why their instructions are ignored, unaware that the file was never processed due to an unannounced dependency on remote telemetry.
The Gossip
Anthropic's Swift Save
A developer from Anthropic quickly responded to the post, taking full responsibility for the 'human error' and announcing that a fix was already rolling out in a new version. This rapid and transparent response was widely praised by many commenters, who saw it as a commendable example of community engagement and accountability, contrasting it with typical corporate silence.
Telemetry's Tyranny & Silent Snubs
Many users expressed strong dissatisfaction with the design choice to tie a local file-reading feature to a remote feature flag that depends on telemetry. The silent failure mode, where `AGENTS.md` simply wasn't read without any warning, was deemed particularly problematic. Commenters debated whether this was an intentional mechanism for progressive rollouts or a fundamental design flaw that violates user expectations for privacy and control.
The 'Vibe-Coding' & Trust Verdict
Some commenters speculated that the bug might be a consequence of 'AI-generated patches' or 'vibe-coding' (a humorous term implying coding without rigorous testing or understanding). While the Anthropic dev clarified it was human error, the discussion touched on broader skepticism and trust issues concerning AI companies, especially regarding privacy, account management, and the execution of arbitrary code, with some users questioning Anthropic's overall practices.
Nuances of Instruction Handling
Beyond the telemetry issue, commenters shared practical insights and frustrations regarding Claude Code's instruction and skill handling. Topics included the default behavior when both `CLAUDE.md` and `AGENTS.md` are present, the challenges of syncing skills between different AI tools, and the perceived complexity of managing configuration files and skill sets, suggesting a need for more intuitive and flexible approaches.