AGENTS.md vs CLAUDE.md: Where Instructions Go, and Where Decisions Go

Every repo that uses coding agents ends up with an instruction file, and many end up with two. AGENTS.md is the open format that Codex, Cursor and a long list of other agents read. CLAUDE.md is the file Claude Code reads. If your team runs both Claude Code and Codex, you have probably wondered which file is the source of truth and whether you need to keep them in sync by hand.

This post covers the difference between the two files, how Claude Code reads each one as of this month (it changed recently), and what Anthropic recommends putting in CLAUDE.md. It ends with the kind of information neither file is built to hold: the decisions and open questions that pile up once you work with several agents, and that you, the person directing them, need to keep track of.

The short answer

AGENTS.md describes itself as “a simple, open format for guiding coding agents, used by over 60k open-source projects.” Its authors call it “a README for agents.” It came out of work across OpenAI Codex, Amp, Jules from Google, Cursor and Factory, and “is now stewarded by the Agentic AI Foundation under the Linux Foundation.” Codex, Cursor, Gemini CLI, GitHub Copilot’s coding agent, Windsurf, Zed, Aider and many other agents read it.

CLAUDE.md is Claude Code’s instruction file. Claude Code loads it at the start of every session, and it comes in four scopes: a managed policy file for the whole organization, a user file in ~/.claude/CLAUDE.md for all your projects, a project file checked into the repo for the team, and a CLAUDE.local.md for your own notes on one project. All the files it finds are concatenated into context rather than overriding each other.

The part many current guides miss is that Claude Code now reads AGENTS.md directly. According to Anthropic’s docs, “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.” This requires Claude Code v2.1.277 or later. There is a catch in the default: “Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it.” If you have both files, Claude Code reads CLAUDE.md and ignores AGENTS.md unless you change the setting or import it.

Setting up both in one repo

For a team that runs several agents, the cleanest setup keeps one shared AGENTS.md as the source of truth. You then have two choices for Claude Code.

The first is a short CLAUDE.md that imports the shared file with @AGENTS.md and adds only the instructions specific to Claude Code. Anthropic’s docs recommend this route when Claude Code is not reading AGENTS.md directly, and note that keeping the import “never makes Claude read AGENTS.md twice.” The second is to change the Project instructions setting in /config. The options are claude-md-or-agents-md (the default), claude-md-and-agents-md, claude-md and managed-only, and claude-md-and-agents-md loads both.

In a monorepo, both formats support nested files. The AGENTS.md site puts the rule this way: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” Claude Code also loads CLAUDE.md files in subdirectories on demand. For rules that only apply to certain files, Claude Code supports a .claude/rules/ directory where each markdown file covers one topic and can carry a paths glob, so a rule about your API layer only loads when Claude is working in it.

CLAUDE.md best practices from Anthropic’s docs

Anthropic’s guidance on CLAUDE.md is mostly about keeping it short. The memory docs say to “target under 200 lines per CLAUDE.md file,” because “longer files consume more context and reduce adherence.” The best practices page gives a test for every line: “Would removing this cause Claude to make mistakes? If not, cut it.”

Their include list is practical: Bash commands Claude can’t guess, code style rules that differ from defaults, testing instructions, repository etiquette such as branch naming and PR conventions, developer environment quirks, common gotchas, and “architectural decisions specific to your project.” Their exclude list is just as useful: anything Claude can figure out from the code, standard language conventions, detailed API documentation, long explanations or tutorials, file-by-file descriptions of the codebase, and “information that changes frequently.”

They also recommend treating CLAUDE.md like code: “review it when things go wrong, prune it regularly, and test changes by observing whether Claude’s behavior actually shifts.” For the team side of this, including shared conventions and permissions, see our guide on how to set up Claude Code for your team.

What doesn’t fit in an instruction file

Anthropic’s include list puts “architectural decisions specific to your project” in CLAUDE.md, and the exclude list keeps out “information that changes frequently.” Both are right, and together they show the limit of the format. The rule that follows from a decision fits in one line: use the event queue for retries, never call the payment provider directly. The decision behind that rule does not fit. Its reasons, the alternatives the team rejected, who made the call and when, and the questions still open around it would take pages, and they change as the team learns.

Instruction files are also written for the agent. Nothing in AGENTS.md or CLAUDE.md is organized for the person directing the agents, and that person is the one who gets overwhelmed first. Once you run several agents, every session makes decisions, raises questions and learns something, and you need a place to see all of it, think about it, and decide what comes next. Putting that into an instruction file would quickly outgrow the 200-line budget and bury the instructions the agents are supposed to follow.

Instructions in the file, decisions in a wiki

We split it this way. AGENTS.md and CLAUDE.md stay short and imperative, holding the commands, conventions and rules an agent needs on every task. Notes, open questions, decisions with their reasons, and principles go in a wiki written for you. The personal wiki in Nimbalyst is a folder of plain files in your project, nimbalyst-local/wiki by default, so your instruction file can point agents to it like any other path.

With the Nimbalyst Wiki, a free plugin for Claude Code and Codex that also works in Cursor, VS Code, Cowork and any MCP agent, your agents write that wiki for you from their activity. While they work, they turn sessions into notes, open questions, decisions and principles and write them into pages organized by area, so you start with a wiki instead of a blank page. Every decision is marked with who made it, when, and what was not chosen, open questions show who owns them, and the home page collects what needs you and what changed recently.

The wiki is yours to work in. You read and edit it in your browser: rewrite a page, reorder priorities, settle an open question or sketch an idea, and your agents pick up from what you wrote. Pages can also be drawings, mind maps, spreadsheets, data models and mockups. Ask your agent to track competitors, customers or features and it creates a type with the right fields, gives each item a page, and keeps a table of all of them.

Your personal wiki is free and needs no app or account. With Wiki Teams, the wiki goes multiplayer, and you, your teammates and all of your agents work in the same pages in real time. See the Nimbalyst Wiki for Claude Code and Codex, Wiki Teams, and the guides for Claude Code and Codex. For the decision records themselves, see architecture decision records written by your coding agent.

FAQ

Does Claude Code read AGENTS.md? Yes, as of v2.1.277, but by default only when there is no CLAUDE.md in your working directory or above it. Change the Project instructions setting in /config, or import it with @AGENTS.md from a CLAUDE.md.

Should I have both files? If your team uses more than one coding agent, keep shared instructions in AGENTS.md and keep CLAUDE.md for what is specific to Claude Code, importing the shared file.

What goes in CLAUDE.md vs AGENTS.md? The same kinds of things: commands, code style, testing, repo etiquette and gotchas. Put what every agent needs in AGENTS.md and what only Claude Code needs in CLAUDE.md.

Where should architectural decisions live? Put the one-line rule in the instruction file and the decision, with its reasons and open questions, in a wiki you and your team read and edit.