Claude Code 2.1.277 Adds AGENTS.md Fallback with Feature‑Flag Limits

The update rolled out on September 18, 2026 for Claude Code, identified as version 2.1.277, brings native handling of the AGENTS.md convention. This convention consists of a single Markdown file that aggregates repository‑wide development context, test commands, contribution guidelines and other instruction metadata, allowing the tool to source its guidance from one consolidated location.

When a project does not contain a CLAUDE.md file, Claude Code now automatically falls back to reading the AGENTS.md file. This fallback mechanism enables teams to maintain a single source of truth for instruction metadata, eliminating the need to duplicate the same information across multiple files for each tool that consumes it.

Configuration and Control

Operators can toggle between using CLAUDE.md and AGENTS.md through the /config menu inside Claude Code. The selected option is persisted locally on the developer’s machine, while the underlying implementation is delivered by a built‑in plugin that becomes active only when a remotely fetched feature flag is present, as reported by Korben.

Because the activation relies on a feature‑flag architecture, disabling non‑essential traffic or telemetry may prevent the flag from loading. In that situation Claude Code silently reverts to its previous behaviour, ignoring AGENTS.md entirely and providing no visible error message to the user.

A documented workaround consists of keeping a minimal CLAUDE.md file that simply imports AGENTS.md using the @AGENTS.md syntax. This approach guarantees that the fallback continues to work even if the remote flag cannot be retrieved, because the tool will always find a CLAUDE.md file to process.

Compatibility Landscape

The initial rollout of the AGENTS.md fallback does not include integration with the major cloud back‑ends Amazon Bedrock, Google Vertex AI or Microsoft Foundry. Users of those platforms must continue to rely on a CLAUDE.md file or on external tooling until a future update expands coverage to those services.

Several other development assistants already understand the AGENTS.md convention. Among them are Codex, Gemini CLI, Devin, Cursor and GitHub Copilot. Their existing support means that adopting AGENTS.md reduces instruction duplication across the broader AI‑assistant ecosystem.

Practical Checklist for Teams

• Verify that /config shows AGENTS.md selected as the instruction source
• Confirm that a CLAUDE.md file exists only to import @AGENTS.md if the feature flag might be blocked
• Test that Claude Code visibly reports "Loading project instructions from AGENTS.md" in the UI
• Ensure telemetry or privacy settings do not block remote flag retrieval

Teams should also keep in mind that the presence of the correct version number alone does not constitute proof of support. The UI must explicitly indicate that project instructions have been loaded from AGENTS.md; otherwise the fallback may have failed silently without any alert.

Because the fallback depends on a remote flag, organisations with strict network policies may need to whitelist the flag endpoint or adjust privacy settings to guarantee consistent behaviour across all developer workstations.

In practice, the addition of the AGENTS.md fallback simplifies onboarding for new contributors. New developers can locate all relevant project guidance in a single file, and Claude Code will automatically honour that file whenever a CLAUDE.md file is absent.

The feature also aligns Claude Code with other AI assistants that already recognise AGENTS.md, thereby reducing the maintenance overhead associated with keeping multiple instruction files in sync across tools.

For English‑speaking organisations, the concrete impact is a smoother, more transparent workflow: developers place all project guidance in one AGENTS.md file, Claude Code automatically uses it when CLAUDE.md is missing, and teams can verify the behaviour through the UI and the simple checklist provided.

Future Outlook

While the current release excludes Amazon Bedrock, Google Vertex AI and Microsoft Foundry, the development roadmap hints at future extensions that will bring AGENTS.md support to those cloud back‑ends, further unifying instruction handling across the AI development stack.

Until those extensions arrive, teams are encouraged to adopt the minimal CLAUDE.md import pattern as a safety net, ensuring that the fallback remains functional even in environments where the remote feature flag cannot be retrieved.