Do I need both CLAUDE.md and AGENTS.md?

Not for rules. With two independent files, one of them silently goes unread: Claude Code reads AGENTS.md only when no CLAUDE.md is on the path, unless the Project instructions setting says otherwise. Arroway's recommendation is to keep both empty and put what holds in Arroway, which every connected agent reads at the start of the work, whichever file it loads.

How do I check which file Claude Code actually loaded?

Run /context or /memory in a session and look for the file's path. When Claude Code reads AGENTS.md because there is no CLAUDE.md, an interactive session also shows a line saying no CLAUDE.md was found and AGENTS.md was loaded. The documentation notes that before v2.1.280 those lists did not show an AGENTS.md read directly, so on older versions ask the assistant what its project instructions say.

Does Arroway replace AGENTS.md?

For anything that has to hold, yes: Arroway's recommendation is that nothing stays in the file. Whatever sits in AGENTS.md governs every session with nobody seeing or approving it. In Arroway each rule and decision carries who decided it, reaches every tool and person on the project, and leaves the read when it is replaced. Install it in the tool you already use — the install page has the route for each — and the next session opens by reading the project.

Answers

Does Claude Code read AGENTS.md?

Yes, since version 2.1.277 (18 September 2026) — but by default only when the project has no CLAUDE.md. If a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in your working directory or any directory above it, Claude Code reads those and leaves AGENTS.md out, with no error. The default can be changed under "Project instructions" in /config, for example to read both files, and a release on 24 September extended the support to Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry disabled. Which file gets loaded decides which instructions apply, and nothing tells the team. Arroway's recommendation is to keep both files empty: whatever sits in them governs every session with nobody seeing or approving it, and it never reaches a chat assistant, another agent or a person outside the repository. What holds goes to Arroway, with who decided it and when it ends, and every connected tool reads it before acting, whichever file it loads.

Last updated September 29, 2026

Which file wins, and why it fails quietly

The check is simple. Claude Code looks for CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory and every directory above it. If it finds one, those are the project instructions and AGENTS.md is not loaded. If it finds none, it loads every AGENTS.md on that path, and an interactive session shows a line saying so. The quiet case is CLAUDE.local.md: one developer adds a personal, uncommitted file, and from then on Claude Code stops reading the team's AGENTS.md for that person only. Nobody else sees the difference and nothing reports it. The setting that changes this is read from each person's user settings, not from the repository — the documentation says project and local settings files ignore it — so a team cannot commit the fix.

What the documentation describes for two files

Claude Code's documentation describes two ways to have the two files read as one. A CLAUDE.md that imports AGENTS.md with an @AGENTS.md line is expanded at launch, the imported file is not read twice, and the import also works in sessions where direct AGENTS.md support is unavailable. A symlink from CLAUDE.md to AGENTS.md works too, with two catches the documentation lists: the editing tools refuse to write through a symlink, and on Windows a committed symlink can check out as a one-line text file. In either case /context shows, under Memory files, which file a session loaded. Both settle which file is read; neither says who put each line there or whether anyone approved it.

Where one file stops scaling

An import or a symlink fixes which file is read. It leaves three things untouched. The file reaches only coding agents working in that repository: the person setting pricing in a chat window, or an agent in another repository, never loads it. A line in it cannot say it has been overtaken, so last month's rule reads exactly like today's. And nothing in it tells a rule a person approved from one an assistant wrote down. Arroway holds that part: rules and decisions per project, each with who approved it and the condition that ends it, read before acting by every connected tool — Claude, ChatGPT, Codex, Cursor or anything over MCP. That is why Arroway's recommendation is to leave the file empty.

What it looks like in practice

A team of three shares a repository they work on with Claude Code and one other coding agent. In August they moved their instructions into AGENTS.md and kept an old CLAUDE.md with the build commands. In September they add a rule to AGENTS.md: migrations are never run from a feature branch. The other agent follows it. Claude Code finds the old CLAUDE.md first and never sees the rule. They move the rule into Arroway instead, written once with the name of whoever decided it, and both agents read it at the start of each session, whichever instruction file they load. A week later the product lead decides, in a chat, that the free plan drops from five projects to three. That decision is not about the code and would never have reached AGENTS.md. In Arroway it is written once, with her name, as replacing the five-project rule — and every assistant the team uses, inside the repository or outside it, opens its next session with it.

Questions people ask about this

Do I need both CLAUDE.md and AGENTS.md?: Not for rules. With two independent files, one of them silently goes unread: Claude Code reads AGENTS.md only when no CLAUDE.md is on the path, unless the Project instructions setting says otherwise. Arroway's recommendation is to keep both empty and put what holds in Arroway, which every connected agent reads at the start of the work, whichever file it loads.
How do I check which file Claude Code actually loaded?: Run /context or /memory in a session and look for the file's path. When Claude Code reads AGENTS.md because there is no CLAUDE.md, an interactive session also shows a line saying no CLAUDE.md was found and AGENTS.md was loaded. The documentation notes that before v2.1.280 those lists did not show an AGENTS.md read directly, so on older versions ask the assistant what its project instructions say.
Does Arroway replace AGENTS.md?: For anything that has to hold, yes: Arroway's recommendation is that nothing stays in the file. Whatever sits in AGENTS.md governs every session with nobody seeing or approving it. In Arroway each rule and decision carries who decided it, reaches every tool and person on the project, and leaves the read when it is replaced. Install it in the tool you already use — the install page has the route for each — and the next session opens by reading the project.

Install Arroway See how it works →

Where this is verifiable

Claude Code changelog (code.claude.com/docs/en/changelog), entries 2.1.277 of 18 September 2026 and 2.1.282 of 24 September 2026; the Claude Code memory documentation (code.claude.com/docs/en/memory), sections on AGENTS.md, the Project instructions setting, imports and troubleshooting, read on 29 September 2026; product documentation on this site (How it works, Install); and the sanction, supersession and expiry-condition rules in the sanctioned product spec. Claude Code is described as its own documentation states it on that date, and its behaviour can change in any release. Everything described here about Arroway is behaviour the tools apply today, not roadmap.

https://www.arroway.app/en/answers/does-claude-code-read-agents-md

Continue exploring

See all answers

Arroway vs writing it in CLAUDE.md: what is the difference? Should team knowledge for AI live in versioned files, or in curated memory? My agent keeps following an instruction that is no longer true. How do I retire a rule?