Claude Code adopts AGENTS.md: how to structure project instructions for Claude and Codex
Anthropic has announced that Claude Code now supports AGENTS.md, the Markdown instruction file promoted by OpenAI. In practice, a team running both Claude Code and Codex no longer has to maintain two separate sets of project rules. The news was reported by Génération NT, which cites Anthropic engineer Thariq Shihipar for the version details.
For developers, the stakes are less dramatic than they sound, but they touch a real pain point: duplicating project rules across multiple assistants. Here's what the change actually does, and how to organize your instructions to take advantage of it.
AGENTS.md vs. CLAUDE.md: what's the difference?
AGENTS.md is a Markdown document holding permanent instructions for an AI agent. It typically covers a project's coding conventions, build commands, testing requirements and other repository-specific directives. The standard is open source and backed by OpenAI, Anthropic's direct competitor.
Until now, teams combining tools from both vendors had to manage two files: CLAUDE.md for Claude Code, AGENTS.md for other agents. Claude Code's support for AGENTS.md reduces that overhead, since the same document can serve multiple assistants.
What the update actually changes
According to the source, support arrives in Claude Code version 2.1.277. The reported behavior is straightforward: if no CLAUDE.md file is present in a folder, Claude checks for an AGENTS.md and uses it. This behavior can be turned on or off in the configuration.
That detail matters, because it shapes your migration strategy. Claude Code does not replace CLAUDE.md with AGENTS.md; it falls back to AGENTS.md when the older file is absent. If you keep a CLAUDE.md, it still takes precedence.
Another reported element: the implementation relies on a native "mod" system. The actual scope of that mechanism and its rollout timeline are not specified in the available information, so it's worth staying cautious about what it will eventually enable. The source only says it foreshadows broader customization, letting developers create their own modules.
Why interoperability matters for teams
Claude Code can now read the same instructions as OpenAI's Codex, Gemini CLI or GitHub Copilot. For a team juggling several assistants — an increasingly common setup — that avoids rewriting the same rules in multiple places and watching them drift apart over time.
Reactions, however, are mixed. Some developers welcomed the move toward interoperability on social media, and OpenAI product lead Thibault Sottiaux commented positively on the decision, according to the source. On Reddit, other users called the update a small, expected adjustment, arguing that CLAUDE.md remains more relevant for heavy Claude users. The exact CLAUDE.md syntaxes discussed in those threads are not detailed.
The source also reports that AGENTS.md was adopted by more than 60,000 open-source projects by late 2025. That figure comes from the source and has not been independently verified; treat it as an indication of the standard's momentum rather than an exact measurement.
How to structure your project instructions
The right approach depends on your tooling. Here are the most common cases.
You only use Claude Code
Nothing forces you to change. CLAUDE.md still takes precedence when present, and some heavy Claude users continue to see it as better suited to their needs. You can still try AGENTS.md on a secondary repository to gauge the difference.
You use Claude Code and Codex (or another agent)
This is where the update pays off most. Two options emerge:
- A single AGENTS.md: centralize shared rules and let Claude Code use them when no CLAUDE.md exists. Upside: one source of truth. Downside: you lose Claude-specific instructions if you had any.
- A base AGENTS.md plus a supplementary CLAUDE.md: the first holds shared conventions, the second holds Claude-specific guidance. Upside: fine-grained control. Downside: two files to maintain, with drift risk unless you clearly define what goes where.
What belongs in the file
Whichever route you pick, a good instruction file stays factual and verifiable. Generally useful elements include:
- build and test commands;
- naming and formatting conventions;
- architecture or dependency constraints;
- contribution and review rules.
Avoid vague or contradictory guidance: an agent follows what's written, not what you had in mind.
Key takeaways
- Claude Code supports AGENTS.md, according to Anthropic, with support announced in version 2.1.277.
- AGENTS.md acts as a fallback: it's used only when no CLAUDE.md is present in the folder, and the behavior is configurable.
- The main benefit is reducing duplicated instructions across Claude Code, Codex, Gemini CLI and GitHub Copilot.
- Opinions are split: interoperability praised on one side, a minor adjustment on the other.
- The 60,000-plus adopting projects figure comes from the source and is not independently verified.
For teams already juggling multiple assistants, the question isn't really which file wins — it's deciding where your project's truth lives, and sticking to it.
This article is published by Roboto, a platform for generating texts, images, videos and voiceovers with AI.