update · TowCue Editorial Team
Claude Code adds AGENTS.md support: why portable repo instructions matter
Claude Code 2.1.277 adds AGENTS.md support when a project has no CLAUDE.md. TowCue explains what this changes for teams using multiple coding agents, plus the rollout limits to verify first.
Quick answer
Claude Code 2.1.277 added AGENTS.md support: when a project has no CLAUDE.md, Claude Code can read AGENTS.md as project instructions. Anthropic's changelog says the behavior can be changed under Project instructions in /config, and notes that the feature is not yet available on Bedrock, Vertex or Foundry.
This is a small compatibility change with a larger workflow implication. Teams that use several coding agents can move closer to keeping shared repository conventions in one portable instruction file instead of duplicating the same rules for every agent.
For related context, see the Claude tool profile, Codex tool profile, and AI agent best practices.
What exactly changed in Claude Code 2.1.277?
Anthropic's official Claude Code changelog says version 2.1.277 reads AGENTS.md when the project has no CLAUDE.md. That condition matters: this is fallback support, not a statement that AGENTS.md replaces CLAUDE.md or that both files are merged automatically.
Anthropic's project-configuration documentation still describes CLAUDE.md as the normal project instruction file loaded into context at the start of a session. It recommends putting repository conventions, common commands and architectural context there, while task-specific knowledge can live in skills or scoped rules.
So teams should treat the new behavior as compatibility, not a migration mandate.
Why does AGENTS.md compatibility matter?
Repository instructions are becoming part of the interface between a codebase and an AI agent.
They can tell an agent which build and test commands to run, which directories it may change, how the architecture is organized, what naming rules matter and which actions require human approval.
If every coding agent requires a different copy of those rules, teams create configuration drift. A convention may be updated for one agent but remain stale for another.
A portable file reduces that maintenance burden. The useful pattern is:
repository policy → agent-readable instructions → bounded task → verification → human review
The value is not that one markdown file makes an agent trustworthy. The value is that teams can make important context easier to reuse and audit.
Does Claude Code now use AGENTS.md exactly like CLAUDE.md?
No. The official changelog describes a specific fallback: AGENTS.md is read when there is no CLAUDE.md. Teams should not infer recursive precedence, automatic merging or identical behavior beyond what Anthropic documents.
There is also an availability limit. Anthropic says this support is not yet on Amazon Bedrock, Google Vertex AI or Microsoft Foundry. If your organization runs Claude Code through one of those providers, verify behavior before deleting or consolidating existing instruction files.
A safe migration is to test the actual environment your team uses rather than assuming a local Claude Code release behaves the same everywhere.
TowCue take: agent instructions are becoming a portability layer
The important trend is bigger than a filename.
Coding teams increasingly use more than one agent: one tool may be better for a long autonomous implementation, another for review, another for a quick terminal task. Repository rules should ideally survive those switches.
That suggests a separation of concerns:
- keep stable team conventions in repository-owned instructions;
- keep agent-specific tuning only where the agent genuinely needs it;
- keep permissions and destructive-action controls in enforceable settings, not prose alone;
- keep tests and CI as the evidence layer.
A shared instruction file can improve portability. It should not become the security boundary.
What should teams put in repository instructions?
Prioritize information that is stable, actionable and expensive for an agent to guess incorrectly.
Good candidates include build, lint and test commands; architecture boundaries; generated files that should not be edited; naming and formatting rules; required validation; and explicit Git constraints.
Avoid turning the file into a giant handbook. Anthropic's documentation advises keeping project instructions focused because longer always-loaded context can reduce adherence. Task-specific procedures are better placed in skills or scoped rules that load when relevant.
How should a multi-agent team test this change?
Use a small repository with a known instruction that is easy to observe, such as a required test command or a prohibited directory.
First confirm the installed Claude Code version. Then test with AGENTS.md and no CLAUDE.md, inspect /config under Project instructions, and verify that Claude follows the rule. Repeat in the deployment path your team actually uses.
If you also use Codex or another coding agent, run the same bounded task there and compare instruction adherence, manual corrections and validation failures.
Do not remove an existing CLAUDE.md across production repositories until the fallback has been verified in your environment.
Who benefits most?
Teams already using multiple coding agents benefit most because duplicated instruction files create real maintenance cost. Open-source projects can also benefit when contributors arrive with different agents but need the same repository conventions.
Single-agent teams with a mature CLAUDE.md do not need to migrate just because support exists. The lower-risk choice is to keep the current setup unless portability solves a concrete problem.
TowCue take: standardize context, not trust
AGENTS.md support makes repository context more portable, but it does not prove an agent will obey every instruction perfectly.
Treat instruction files as context, permissions as enforcement, tests as evidence, and human review as the final checkpoint for consequential changes.
That distinction becomes more important as coding agents gain longer runtimes and broader tool access. The best shared instruction format is useful only when the workflow around it can still detect mistakes.