CLAUDE.md vs AGENTS.md is not an either-or but a question of who reads your instructions. CLAUDE.md is the file Claude Code loads at the start of every session: role, rules, limits, in plain text. AGENTS.md is the same principle as an open format that, according to the agents.md site, many coding agents read, including Codex and OpenCode. Since version 2.1.277, according to Anthropic's docs, Claude Code also reads an AGENTS.md when no CLAUDE.md sits in the working directory or above it; if both are there, Claude reads the CLAUDE.md, and with one import line it reads both. Both files are Markdown, no special format. That is the real point behind the comparison: what survives a switch of model or tool is not the configuration in an interface but the text file you can read yourself.
In my setup, every AI employee is a folder with exactly these files: a personnel file, a CLAUDE.md as rulebook, skills and subagents as further Markdown files. What belongs in the CLAUDE.md and how its four levels work together, I explained in CLAUDE.md: Claude Code's Memory and won't repeat here. This post is about the question after that: what happens to these files when the model changes, when the tool changes, or when I have to carry on with Codex tomorrow. Everything else about Claude is collected on the Claude overview page.
What goes in CLAUDE.md and what goes in AGENTS.md
In content, the two files are siblings. Anthropic describes CLAUDE.md as the place for what you would otherwise explain again every time: "Treat CLAUDE.md as the place you write down what you'd otherwise re-explain." The agents.md site describes its format as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project". Codex says in its docs: "Codex reads AGENTS.md files before doing any work." Three phrasings, one idea: a text file the agent reads before it starts.
The most important difference isn't in the table: which file gets read depends on the tool, not on the content. You can write the same sentences into both.
The levels Claude Code knows
According to the docs, Claude Code loads four levels in this order: a file managed by the organization, your personal ~/.claude/CLAUDE.md, the project file ./CLAUDE.md or ./.claude/CLAUDE.md, and a local ./CLAUDE.local.md that stays out of the repository. The files don't override each other, they are placed into context one after the other, from the root of the file system down to the folder you started in. Add rules in .claude/rules/, optionally only for certain paths, and imports via @path. For an AI employee, the project level is enough in my setup: the employee's folder is the project, its CLAUDE.md its rulebook. The details on the levels and on /init, /memory, and /context are in the CLAUDE.md post.
When Claude Code reads AGENTS.md
Anthropic writes: "Claude Code can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting." The default rule is simple:
The behavior can be changed in /config under "Project instructions", for example to both files together. The docs name two limitations explicitly: reading it directly requires version 2.1.277 or later, and in some sessions, for instance via Amazon Bedrock or with telemetry disabled, Claude doesn't read AGENTS.md directly. For those cases Anthropic recommends the import from a CLAUDE.md. That is also the solution if you want to maintain one file for several tools:
@AGENTS.md
## Claude Code
Rules that apply only to Claude Code go below the import.
The docs name a symlink from CLAUDE.md to AGENTS.md as an alternative but advise against it on Windows.
Skills and subagents: also just Markdown
The rulebook isn't the only file that makes up an AI employee. In my setup, every employee has skills for recurring tasks and some have a subagent for a separate review role. Both are text as well, according to the docs. A skill is a folder with a SKILL.md: "YAML frontmatter between --- markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs." A subagent is a Markdown file under .claude/agents/ or ~/.claude/agents/: "The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior." The subagent's frontmatter also holds the model, as an alias like sonnet or opus, as a full model ID, or as inherit.
That means: the whole employee, from role to work instructions to review role, is a folder of text files. None of it lives in an interface I can't open. How you write and use skills is in Claude Skills: How to Create and Use Them.
Switching the model by command, switching the tool with the same files
Inside Claude Code I switch the model with one command. The docs: "During session: use /model <alias|name> to switch immediately, or run /model with no argument to open the picker." The aliases are sonnet, opus, haiku, fable, plus default, best, and opusplan. That is a switch within the Claude family. There is no GPT or Gemini model in Claude Code, and I say this plainly because "I can swap the model" would otherwise promise more than the docs support.
What I can do instead: switch the tool. My files live locally in an Obsidian vault, as Markdown. If Claude goes down, I carry on with Codex or with OpenCode and local models, and both read the same files. Codex reads AGENTS.md according to its own docs, from the project root down. OpenCode reads "AGENTS.md, CLAUDE.md" from the project at startup according to its docs, plus the ~/.claude/CLAUDE.md, and it supports local models: "You can configure opencode to use local models through Ollama." For Codex you need an AGENTS.md next to the CLAUDE.md, or one points to the other, as shown above. The effort is one line.
The second-brain look around the vault is more of a gimmick to me. What matters is that the tool finds the right file at the right moment, and Claude Code, Codex, and OpenCode do that because they search by the same pattern: text file in the project folder, concatenated from top to bottom.
Take Frieda, my office assistant. Her rules for the inbox, which mail goes on which pile and that she never sends herself, live in her CLAUDE.md and in a rules file that the post Sorting Your Inbox: The Pile System also describes. When I switch the tool, the rules stay where they are. The next morning, Frieda still knows what a pile is.
The counter-image: workflow JSON, scenarios, agent configurations
In a workflow tool, the same description of the work exists as a workflow: a diagram of nodes, JSON behind it, the rules in the prompt field of an agent node. In Make it's called a scenario, in a platform for organizations it's an agent configuration in the interface, with instructions and uploaded documents. All three forms work, and for fixed processes with volume they are the fitting choice. They differ from the text file in one point: they belong to the tool they were created in. You open a workflow with the workflow tool, an agent configuration with the platform. I ran it that way myself, n8n lived in my own cluster for a long time, and I didn't feel it as a shortcoming there. I only noticed what I was missing when I wanted to hand the same rules to another model. The six ways of building with their strengths are in Building an AI Employee: Six Ways Compared, the terms behind them in Agentic AI Explained: What It Is and Isn't.
CLAUDE.md best practices: what has proven itself for me
The recommendations from Anthropic's docs are short: stay under 200 lines per file, because longer files cost context and adherence drops; headings and lists instead of dense paragraphs; instructions concrete enough to verify; no two rules that contradict each other. On top of that, across many personnel files, this is what works for me:
- Role instead of tech stack. Most CLAUDE.md examples online describe a software project. Mine describe a person: who you are, what your job is, what you must not do.
- Limits as sentences you can quote. "You never send yourself, you leave drafts." One sentence that loads in every session and that I can look up in doubt.
- An approval gate, verbatim. Whatever leaves the house or changes state needs my approval in the running conversation. That's in every employee's file, not only the sensitive ones.
- Learnings in a separate file that is read before every task. Feedback doesn't go into the CLAUDE.md but into a file the CLAUDE.md points to. That keeps the rulebook short while the experience still grows.
- Hard bans don't go in the file. The docs say it clearly: CLAUDE.md is "context, not enforced configuration". Whatever must never happen belongs in a hook or in
permissions.deny.
An example of what such a limit looks like, from the rulebook of Falk, my red teamer, shortened to three lines and translated:
## Limits (non-negotiable)
- Active tests run only against systems that belong to Kevin or for which
he has granted written authorization, and only after his approval per
engagement, documented verbatim with a timestamp.
- Never test third-party systems without a written scope.
- No destructive actions.
That is not a technical lock, and I don't treat it as one. It is the personnel file of an employee whose job is to test other people's limits and who therefore needs his own especially clear. Because it is text, I can read it, change it, and hand it to any tool that opens the folder.
Frequently asked questions
Does Claude Code read AGENTS.md?
Yes, according to Anthropic's docs since version 2.1.277, but by default only when no CLAUDE.md or CLAUDE.local.md sits in the working directory or above it. If a CLAUDE.md is there, Claude reads only that. With the "Project instructions" setting in /config you can switch to both files. In sessions via Amazon Bedrock or with telemetry disabled, direct reading doesn't work; an @AGENTS.md import in the CLAUDE.md helps there.
Can I use CLAUDE.md and AGENTS.md at the same time?
Yes, in two ways. Either you set "Project instructions" in /config to claude-md-and-agents-md, then Claude reads per folder first the CLAUDE.md and then the AGENTS.md. Or you write @AGENTS.md into the CLAUDE.md, then the content comes through the import. Nothing is read twice according to the docs; Claude skips an AGENTS.md it has already loaded.
What is the difference between CLAUDE.md and AGENTS.md?
The content can be the same, both are Markdown with instructions for an agent. The difference is who looks for the file: Claude Code looks for CLAUDE.md first, Codex looks for AGENTS.md, OpenCode looks for both. Anthropic's docs name smaller differences for AGENTS.md: it doesn't appear in /memory and /context, and the InstructionsLoaded hook doesn't fire when Claude reads it directly.
Does Codex read my CLAUDE.md?
The Codex docs name AGENTS.md and AGENTS.override.md as the files Codex reads; a CLAUDE.md is not documented there. If you want to work with both tools, create an AGENTS.md and let the CLAUDE.md import it via @AGENTS.md. Then Codex reads the AGENTS.md directly and Claude Code through the import.
Can I switch to GPT in Claude Code?
No. /model switches between Claude models and, depending on your setup, between providers that host Claude, such as Amazon Bedrock or Google Cloud. For a model from another maker you switch the tool, for instance to Codex or OpenCode. The point of this post is that your files come along for that switch.
Do I need both files?
Only if you use several tools. If you work exclusively with Claude Code, CLAUDE.md is enough. If you run Codex alongside or share a repository with others, keep an AGENTS.md and let the CLAUDE.md point to it. That is the effort of one line, and if you're unsure about it, bring the question to the community, where several people have already built exactly this setup.
Where to go from here
Open the CLAUDE.md of your first employee and read it once as if you were a different tool: is everything in there that a stranger would need to take over the role? If yes, you have a file that survives a tool switch. If no, you now know what's missing. Which stage the CLAUDE.md belongs to is in Learn Claude: The Path in Five Stages. And in the calls of my community we rebuild your Frieda in your tool, once as a file and once in an interface, and then you see the difference yourself: Claude Practitioners.
