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. For a repository shared by several coding agents, the dependable setup is one source: keep the instructions in AGENTS.md and give CLAUDE.md a single @AGENTS.md import. That settles which file the agent reads. It does not settle rules that must also reach a chat assistant, another agent or a person outside the repository, or rules that change without the code changing — those need a place outside both files, with who decided them and when they end, which is what Arroway holds.
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.
One source for two files
Keep AGENTS.md as the shared file and give CLAUDE.md one line, @AGENTS.md, followed by anything specific to Claude Code. The import is expanded at launch, Claude Code does not read the imported file twice, and it 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 the next session, run /context and confirm the file appears under Memory files.
Where one file stops scaling
The import 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. The file keeps what the repository owns: how to build, test and lay out the code.
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 replace the CLAUDE.md with a single @AGENTS.md line, and both agents now read the same file. 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 never reaches 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 if Claude Code is your only coding agent: one CLAUDE.md is enough. If other agents in the same repository read AGENTS.md, keep AGENTS.md as the single source and a CLAUDE.md that only imports it, plus anything specific to Claude Code. Two independent files is the setup where one of them silently goes unread.
- 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?
- No. The file stays the right place for what the repository owns. Arroway is for the rules and decisions that have to reach every tool and person on a project, carry who decided them, and leave the read when they are 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.
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