AGENTS.md vs CLAUDE.md: keep one context file for every coding agent

What is AGENTS.md and where did it come from?

AGENTS.md describes itself as "a simple, open format for guiding coding agents" and as "a README for agents": a predictable place for the build steps, tests and conventions an agent needs but a human contributor would skip. It is plain Markdown with no required fields.

It began at OpenAI. In OpenAI's own words, Codex "needed a predictable way to find project-specific instructions", and AGENTS.md was the answer, released in August 2025. The agents.md site says the format "emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory." The name was chosen on purpose: "Rather than introducing another proprietary file, we chose a name and format that could work for anyone."

On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation, with three founding projects: Anthropic's Model Context Protocol, Block's goose and OpenAI's AGENTS.md. Its platinum members include AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI. OpenAI's stated reason for donating the format: so that "no single company controls its direction as adoption continues to grow."

Which coding agents read AGENTS.md?

At the donation, OpenAI and the Linux Foundation said AGENTS.md had been adopted by more than 60,000 open-source projects and agent frameworks, naming Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code. The agents.md site lists more, among them Zed, Windsurf, Junie from JetBrains, Warp, goose, opencode and Aider.

Support isn't identical everywhere. The agents.md FAQ shows that Gemini CLI and Aider need a line of configuration to use it (context.fileName in .gemini/settings.json, read: AGENTS.md in .aider.conf.yml). Check your tool's docs before you delete its old file.

Does Claude Code read AGENTS.md?

Yes, since September 18, 2026. Thariq, who works on Claude Code at Anthropic, announced it on X: "We're adding support for AGENTS.md to Claude Code. Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md. You can toggle this behavior in /config."

The Claude Code changelog entry for 2.1.277 says the same: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead". It is a fallback, not a merge. Claude Code's memory docs spell out the default:

Under /config, Project instructions switches between four values: claude-md-or-agents-md (the default), claude-md-and-agents-md (both, with CLAUDE.md first), claude-md and managed-only. A few details from the docs are worth knowing:

What catches people out with AGENTS.md in Claude Code?

• A `CLAUDE.local.md` counts as a `CLAUDE.md`. Add one for your private notes in a repo that relies on AGENTS.md, and by default Claude stops reading AGENTS.md. The docs' fix is to set Project instructions to claude-md-and-agents-md.
• Only `AGENTS.md` and `.claude/AGENTS.md` are read. Claude Code does not read AGENTS.local.md, AGENTS.override.md or anything under .agents/. Codex does read AGENTS.override.md, so an override you write for Codex is invisible to Claude.
• Older versions and some setups read `CLAUDE.md` only. You need v2.1.277 or later, and the docs say sessions on Amazon Bedrock or with telemetry disabled needed v2.1.281. If the built-in plugin that reads AGENTS.md is disabled, it is not read either.
• Your personal file still loads. ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and .claude/rules/ files don't count for the check and keep loading next to AGENTS.md.

AGENTS.md vs CLAUDE.md: what's the difference?

The content is the same kind of thing: how to build, how to test, what not to touch. The difference is who can read it. A CLAUDE.md reaches one agent; an AGENTS.md reaches all of them.

Why is the industry moving to AGENTS.md?

Because separate files drift, and drifting files make agents fight. Thiago put it in four lines on X: "CLAUDE.md says pnpm. AGENTS.md says npm. Each agent obeys its own and they take turns rewriting your lockfile." His fix is the one most people land on: "Keep one file, symlink the other." And his summary: "Two agents is fine. Two managers is not."

I use more than one agent every day: one in the terminal, one in the editor, one for reviews. Every tool-specific file is one more place a rule can be out of date. A vendor-neutral file under a foundation, with no required schema, is the boring answer, and boring is what you want from a file every tool reads.

It also helps the tools. Once Claude Code reads AGENTS.md, a repo set up for Codex or Cursor works in Claude Code without any extra file, and the Claude Code docs say exactly that: a repository already set up for other coding agents "works without adding a CLAUDE.md, an import, or a setting."

How do you move from CLAUDE.md to AGENTS.md?

Keep AGENTS.md as the source of truth and make every other file point at it:

1. Merge the rules into `AGENTS.md`. Take the content of CLAUDE.md, .cursorrules, GEMINI.md and copilot-instructions.md, resolve the contradictions (pnpm or npm, decide once) and write one AGENTS.md at the repo root.
2. Decide whether you need a `CLAUDE.md` at all. On Claude Code 2.1.277 or later with the default setting, you don't: with no CLAUDE.md, Claude reads AGENTS.md directly.
3. If you do need one, import instead of copying. Put @AGENTS.md on the first line of CLAUDE.md and add only Claude-specific instructions below it. The docs recommend this for projects that also have a CLAUDE.md, for the claude-md setting and for sessions that can't load AGENTS.md.
4. Or symlink. ln -s AGENTS.md CLAUDE.md works too, and the docs say a CLAUDE.md symlinked to AGENTS.md is read once. An import is a plain line of text, so it survives checkouts where symlinks don't, such as Windows clones without symlink support.
5. Point the other tools at it. Configure Gemini CLI or Aider as the agents.md FAQ shows, and remove the old files once each tool reads AGENTS.md.
6. Remove hooks that inject it. If you used a SessionStart hook to print AGENTS.md into Claude Code, the docs say to remove it, or Claude gets a second copy.

What should a context file for coding agents contain?

The agents.md site suggests a project overview, build and test commands, code style guidelines, testing instructions and security considerations, plus anything you'd tell a new teammate: commit message rules, pull request guidelines, deployment steps. What I'd add from experience:

• Exact commands, not descriptions. pnpm test --filter api beats "run the tests".
• The mistakes you don't want twice. If an agent got something wrong in a way that cost you time, write the rule down.
• What not to touch. Generated files, vendored code, migrations that only move forward.
• Nothing private. A committed AGENTS.md goes to everyone who clones the repo. Keep secrets and personal preferences out.
• Keep it short. Codex stops adding instruction files at 32 KiB by default, per its docs. Long files also cost context in every session.

How does AGENTS.md work in a monorepo?

Put one AGENTS.md at the root for repo-wide rules and another inside each package for what is specific to it. The agents.md site says agents read the nearest file in the directory tree, so "the closest one takes precedence", and that explicit chat prompts override everything.

Tools load nested files slightly differently. Codex walks from the project root down to your working directory, at most one file per directory, and later files override earlier ones. Claude Code reads every AGENTS.md from the working directory up at session start, and a subdirectory's AGENTS.md when it opens a file there. Same files, same intent, so one layout works for both.

What does a context file not cover?

A context file covers the repo. It does not cover what you learned while working in it. Alexandre made the point on X: "Symlink AGENTS.md to CLAUDE.md. Tool-switching is free. Your session transcript does not symlink."

That's the gap I keep running into. Why we picked one crate over another, the approach we tried and dropped, the preference I explained to one assistant last week: that lives in session transcripts, in one tool's memory, in a chat with a colleague. AGENTS.md fixes the rulebook. It doesn't carry decisions across sessions, assistants and people, and it shouldn't, because everything in it is public to the repo.

This is what we're working on at Koru. Koru Workspace, our free, open-source notes app, keeps your notes in a local database on your device and ships a local MCP server, so an agent can read the notes you keep there. Koru Weave, which is in development, is being designed for the part beyond one repo: connecting your knowledge, the people you work with and your AI assistants with permissions on what each can see. Save it once, reuse it, share selected parts, and nothing goes to everyone by default. My knowledge stays mine.

If that's a problem you have too, join the Koru Weave early access list. Joining doesn't give access yet. For Workspace and the MCP server, see Koru for developers, and for the longer version of this argument, read what a shared memory layer for coding agents should do.