Claude Code adds AGENTS.md fallback for project instructions

Claude Code now reads AGENTS.md if no CLAUDE.md is present – a long‑awaited standards‑compliant change

Claude Code 2.1.277 (released September 18 2026) adds a single but impactful feature: when a project directory does not contain a CLAUDE.md file, the CLI automatically falls back to reading AGENTS.md for its instruction set. The change is configurable under Project instructions in /config and is not yet available on Bedrock, Vertex, or Foundry deployments.

Why this matters

  • Standard‑compliant configuration – AGENTS.md is the de‑facto community convention for describing agents, skills, and project‑level prompts. By honoring it out‑of‑the‑box, Claude Code eliminates a proprietary quirk that forced users to maintain duplicate files or symlinks.
  • Reduced friction – Developers can now delete the CLAUDE.md → AGENTS.md symlinks many kept for backward compatibility. Projects that already use AGENTS.md (or the newer .agents/ layout) work without extra steps.
  • Signal of responsiveness – The update follows a wave of community feedback calling for alignment with broader AI‑tooling standards. It shows Anthropic listening to developers rather than imposing its own file naming.

What the changelog says

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under “Project instructions” in /config (not yet on Bedrock, Vertex or Foundry)

The feature is a pure read‑only fallback; it does not alter how Claude Code discovers skills under .agents/skills or other custom directories. It merely swaps the source of the system prompt when CLAUDE.md is absent.

Community reaction on Hacker News

Commenter Sentiment Key points
@askonomm Positive “Finally doing something standards‑compliant instead of forcing users into a proprietary workflow.”
@neverrroot Positive “Thanks guys, you did the right thing.”
@bcorigliano Positive “Finallyyyy!! We need industry‑wide standards.”
@stillpointlab Observational Noted that Claude Fable already creates an AGENTS.md and a symlink to it, suggesting the change may have been triggered by automatic project scaffolding.
@TomGarden Mixed Appreciated the move but called it “the absolute bare minimum,” and removed existing symlinks.
@mococa Critical Argues the change is merely a reaction to community anger rather than genuine care for developers.
@mitchitized Critical Claims newer logic now prefers settings.json over CLAUDE.md, potentially overriding user‑provided instructions.
@aroman Practical “Finally, I can delete sync-agent-docs.sh, which recursively symlinked AGENTS.md to GEMINI.md and CLAUDE.md…”
@bluestein Humorous “AGENTS.md is the new autoexec.bat.”
@chr15m Positive “This is simply the obvious, non‑stupid thing to do, like Apple switching to USB‑C.”
@perganomoly Negative “The fact that it took this long to add such a basic feature is a disgrace.”

Overall, the community views the change as a necessary correction rather than a groundbreaking innovation. Many users expressed relief at no longer needing symlinks, while a minority remain skeptical about Anthropic’s motives.

How to use the new fallback

  1. Ensure AGENTS.md is at the project root (or in a subdirectory that Claude Code scans for project instructions).
  2. Remove any CLAUDE.md file or symlink you previously used as a pointer to AGENTS.md.
  3. If you need to customize the lookup location, edit the Project instructions section in the /config file:
    {
  "projectInstructions": {
    "fallbackFile": "AGENTS.md"
  }
}
  4. Run claude --version to confirm you are on 2.1.277 or later.

What does not change?

  • Skill loading – Claude Code still does not automatically load skills from a .agents/skills directory. That remains a separate feature request.
  • Bedrock/Vertex/Foundry – The fallback is currently unavailable on those platforms; they continue to require CLAUDE.md.
  • Existing projects – Projects that already contain both files will continue to prioritize CLAUDE.md unless you delete it.

Bottom line

Claude Code’s addition of AGENTS.md as a fallback instruction file removes a long‑standing friction point, brings the tool in line with community conventions, and demonstrates Anthropic’s willingness to adapt based on developer feedback. While the change is modest, it is a clear win for usability and standards compliance.

Sources

Related