Claude Code 2.1.277 introduces an AGENTS.md fallback mechanism that automatically reads an AGENTS.md file when no CLAUDE.md (or any CLAUDE.*.md) is present in the current directory hierarchy, and adds a four‑option /config setting to control how instruction files are combined.
What changed in Claude Code 2.1.277
The new default behavior, called claude-md-or-agents-md, checks for a CLAUDE.md file up the directory tree and, if none is found, loads the nearest AGENTS.md. If both files exist, CLAUDE.md takes precedence unless the claude-md-and-agents-md mode is selected, which loads both with CLAUDE.md first. Two additional modes—claude-md (ignores AGENTS.md) and managed-only (loads only the organization‑managed CLAUDE.md and auto‑memory)—give operators fine‑grained control. Monorepos benefit from the nearest‑file rule: opening a file in a subdirectory triggers the subdirectory’s AGENTS.md if that folder lacks its own CLAUDE.md.
Why the change matters to AI, cloud, DevOps, and security engineers
Instruction files are the first governance artifact that directs autonomous coding agents. By converging on a single, shared format, teams can reduce the drift that occurs when multiple copies of CLAUDE.md and AGENTS.md evolve independently. The fallback eliminates the need for ad‑hoc symlinks that add maintenance overhead, and it gives platform engineers a clear ownership point for agent behavior. Security engineers should note that the file‑loading logic is now configurable, which can affect visibility of instruction content in memory and hook events used by governance tooling.
Operational and governance implications
Several practical considerations arise from the new feature:
- Local overrides: A
CLAUDE.local.mdfile is treated as a CLAUDE.md and will suppress the AGENTS.md fallback. Teams must audit repositories for such files or switch toclaude-md-and-agents-mdto ensure both files are read. - Supported filenames: Only plain
AGENTS.mdis recognized. Variants likeAGENTS.local.md,AGENTS.override.md, or files under a.agents/directory are ignored, requiring alternative loading strategies. - Platform availability: The fallback is not yet available on Bedrock, Vertex, or Foundry. Sessions that lack Anthropic feature flags (including those with telemetry disabled) and the first session after an install or upgrade also miss the AGENTS.md load. The documented workaround is to import AGENTS.md from a CLAUDE.md file.
- Visibility in memory: When AGENTS.md is loaded via the configuration setting, it does not appear in
/memoryor triggerInstructionsLoadedhooks. If the file is imported or symlinked from CLAUDE.md, those hooks fire. Governance pipelines that rely on hook events must account for this discrepancy.
From an architectural perspective, the change encourages a single source of truth for agent instructions, simplifying CI/CD pipelines that provision temporary Claude Code instances on ephemeral runners. However, the fallback does not address cross‑vendor orchestration or shared context, which remains an open interoperability challenge.
Related CloudNinjas coverage: AI engineering.
What This Means For Practitioners
Actionable steps:
- Inventory all repositories for CLAUDE.md, CLAUDE.local.md, and AGENTS.md files.
- Standardize on AGENTS.md as the primary instruction file where multiple coding agents are used.
- Verify that the
claude-md-or-agents-md(or the explicitclaude-md-and-agents-md) setting is applied on the platforms you run—CLI, CI runners, or cloud‑hosted Claude Code instances. - Check for hidden overrides (e.g., CLAUDE.local.md) that could unintentionally block the fallback.
- Test the visibility of loaded instructions in
/memoryand confirm that any governance hooks you depend on fire as expected. - Document ownership of the shared AGENTS.md file within platform engineering to keep the artifact under review.
By treating the AGENTS.md fallback as a configuration boundary rather than a security control, teams can reap the operational benefits while remaining aware of the limited visibility and platform coverage.