Claude Code now reads AGENTS.md if there's no CLAUDE.md — here's what the mods system actually means

Anthropic shipped AGENTS.md support in Claude Code version 2.1.277 yesterday. If there's no CLAUDE.md in your project folder, Claude now checks for and uses AGENTS.md instead.

The feature itself is small. The framing is not. Thariq Shihipar, who announced it, called AGENTS.md "a built-in mod" and said custom mods are coming soon. The source code is already published in the claude-code repo under /mods/agents-md.

This is the first public glimpse of Claude Code's mod system — a way to customize the harness that wraps the model. Mods let you extend or override default behaviors without forking the entire application. AGENTS.md is the example: a standardized fallback for project instructions when the tool-specific file doesn't exist.

Why AGENTS.md matters

AGENTS.md has been floating around since early 2026 as an informal standard for multi-tool coding setups. If you run Codex, Claude Code, and Replit Agent on the same codebase, you used to need three instruction files — CODEX.md, CLAUDE.md, REPLIT.md. AGENTS.md consolidates that into one shared file.

Anthropic adopting it sends two signals. First, they expect developers to use multiple coding agents on the same projects. Second, they're willing to read a cross-tool standard instead of demanding proprietary lock-in.

The move also suggests competition is real. OpenAI hasn't commented on AGENTS.md support in Codex yet. If they don't follow, projects will drift toward the tool that requires less duplicate work.

What mods unlock

The changelog calls AGENTS.md "built off of Claude Code mods" and notes you'll be able to build custom versions of project instructions yourself. The /mods/agents-md source code shows a 200-line TypeScript module that hooks into the instruction-loading flow.

Mods are composable overrides. You could write a mod that:

• Reads instructions from a database instead of a markdown file
• Injects environment-specific context (staging vs production) before every run
• Logs instruction changes to an audit trail
• Strips out sections of AGENTS.md based on repo permissions

Right now, if you want Claude Code to behave differently, you fork it or submit a feature request. Mods let you customize locally without waiting for Anthropic to merge upstream.

This pattern already exists in VS Code extensions and Obsidian plugins. Anthropic is porting it to agentic tooling. The result: coding agents become platforms, not monoliths.

What this changes for multi-agent setups

We run Claude Code and Codex side-by-side on client projects. Until yesterday, that meant maintaining parallel instruction files and syncing changes manually. AGENTS.md cuts that in half if Codex adopts it.

The bigger shift is behavioral. If mods become widespread, teams will start sharing "instruction templates" the way they share ESLint configs. You could pull down a mod that enforces "always write tests before code" or "never use lodash" and apply it repo-wide.

That's useful for internal standards. It's also risky if junior devs cargo-cult bad patterns from GitHub without understanding what they've just installed.

What to expect next

Anthropic said custom mods are "upcoming." The source code structure suggests they're close — the agents-md mod is clean, minimal, and documented. Expect an official mods API in the next few releases, probably with a registry or package system.

OpenAI will either adopt AGENTS.md or push a competing standard. If they ignore it, that's a tacit admission they expect Codex to be the only agent in your workflow. Anthropic is betting the opposite.

For now, AGENTS.md support is live in Claude Code 2.1.277. If you've been maintaining separate instruction files, consolidate them. If you haven't written project instructions yet, start with AGENTS.md so the work ports across tools.

The mods system will matter more once it's fully documented. Until then, the real news is Anthropic signaling that coding agents are infrastructure, not standalone apps.