Alcoven

CLAUDE.md vs AGENTS.md: which file does your AI read?

Blog · Published 4 November 2026

Claude Code reads CLAUDE.md. Codex, Cursor, GitHub Copilot and many other coding agents read AGENTS.md, and Claude Code reads AGENTS.md too (version 2.1.277 or later) when your project has no CLAUDE.md. If you want one set of instructions for all of them, write it in AGENTS.md and add a CLAUDE.md that imports it with a single line: @AGENTS.md.

Tool Reads by default Can also read
Claude Code CLAUDE.md (project, personal and local) AGENTS.md when there is no CLAUDE.md, or through an @AGENTS.md import
Codex AGENTS.md (a personal one in ~/.codex, then the project’s) Other file names you list in project_doc_fallback_filenames
Cursor AGENTS.md and its own .cursor/rules A CLAUDE.md at the project root
GitHub Copilot on GitHub AGENTS.md, anywhere in the repository One CLAUDE.md or GEMINI.md at the root
Gemini CLI GEMINI.md AGENTS.md, if you set context.fileName

What is CLAUDE.md?

CLAUDE.md is a markdown file of instructions that Claude Code reads at the start of every session. You write it in plain text, and it can live in a few places:

  • ./CLAUDE.md or ./.claude/CLAUDE.md in the project folder. This is the one your team shares through the repository.
  • ~/.claude/CLAUDE.md in your home folder, for your own preferences across every project.
  • CLAUDE.local.md in the project folder, for personal notes you keep out of the repository.
  • A CLAUDE.md inside a subfolder, which loads when Claude reads files in that subfolder.

Run /init in Claude Code and it writes a first draft for you. A CLAUDE.md can also pull in other files with @path, for example @docs/style-guide.md.

What is AGENTS.md?

AGENTS.md is an open format for the same job: plain markdown at the root of the repository, with no required fields. A large project can have one per folder, and the agent follows the one nearest the file it is working on.

Codex reads AGENTS.md before it does any work. It also reads a personal AGENTS.md from ~/.codex, and it stops adding instructions once they reach 32 KiB by default. Cursor supports AGENTS.md at the root and in subfolders. GitHub Copilot on GitHub reads AGENTS.md files anywhere in the repository. The list on agents.md also includes Jules, Zed, Warp, VS Code, Devin, Junie and Windsurf, among others.

Does Claude Code read AGENTS.md?

Yes, on version 2.1.277 or later, with one condition: there must be no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or any folder above it (your personal ~/.claude/CLAUDE.md doesn’t count). Here is what happens in each case:

  • Only AGENTS.md: Claude Code reads AGENTS.md.
  • AGENTS.md and a CLAUDE.md: Claude Code reads the CLAUDE.md files only.
  • A CLAUDE.md that imports AGENTS.md: Claude Code reads the CLAUDE.md, with AGENTS.md included through the import.

To have it read both files without an import, type /config and set Project instructions to claude-md-and-agents-md. To see what actually loaded, run /memory and look for the file’s path.

One trap: a CLAUDE.local.md counts as a CLAUDE.md. Add one for your personal notes in a project that relies on AGENTS.md alone, and Claude Code stops reading AGENTS.md for you.

How do I keep one file for every coding agent?

  1. Write the shared instructions in AGENTS.md at the root of the project.

  2. Next to it, create CLAUDE.md with @AGENTS.md as its first line. On current versions of Claude Code, AGENTS.md alone would be enough, but the import also covers older versions, sessions that can’t load AGENTS.md directly, and anyone who adds a CLAUDE.local.md. Anthropic’s docs say the import never makes Claude read the file twice.

  3. If Claude Code needs lines of its own, add them below the import (Cursor reads a CLAUDE.md at the project root too, so it will see them):

    @AGENTS.md

## Claude Code only
- Use plan mode before renaming or moving files.

  4. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Anthropic’s docs say to use the import if anyone who clones the project works on Windows.

  5. For Gemini CLI, add AGENTS.md to context.fileName in its settings.json. Codex, Cursor and Copilot need nothing.

  6. Check it: run /memory in Claude Code; in Codex, ask it to list the instruction sources it loaded.

Both Claude Code (/import) and the ChatGPT desktop app (Settings, then Import) can copy another agent’s instruction files across. Claude Code’s copy is one-time, so it starts drifting the day you edit the original; the ChatGPT desktop app can keep imported work in sync with automatic updates. An import line keeps one file.

What should go in the file?

Anthropic’s advice is to write down what you would otherwise re-explain, and to keep each CLAUDE.md under about 200 lines, because longer files are followed less closely. The agents.md site suggests a project overview, build and test commands, code style, testing instructions and security notes.

Both files are read as context, so how reliably the agent follows a rule depends on how you write it. Write rules concrete enough to check. “Headings in sentence case” works better than “keep it tidy”.

Can I use CLAUDE.md or AGENTS.md for work that isn’t code?

Yes. The file is plain text in a folder, and any coding agent that looks for that file name picks it up, whether the folder holds code or a client’s briefs, research and drafts. Say you keep a folder for a client launch:

# Spring launch for the client

## What this folder is
Briefs, research and copy for the launch. The brief is brief.md.
If another file disagrees with it, the brief wins.

## How we write
- British spelling, sentence case headings.
- The product is called Ember. Hearth is the old name.

## Files
- Drafts go in drafts/, named YYYY-MM-DD-topic.md.
- Never edit anything in client-originals/.

## Before you finish
- Check each draft against brief.md and list anything that contradicts it.

Outside coding agents, it depends on the app. A ChatGPT project on the web can’t read a folder on your computer, so you paste the text into its project instructions or upload the file. In the ChatGPT desktop app, Codex working in a local project picks up the AGENTS.md in the project’s main folder. Claude Cowork has global and folder instructions of its own; Anthropic’s help page doesn’t say whether it reads a CLAUDE.md in the folder. A file like the one above is also the first thing to write when you use Claude Code on a folder of documents.

What if only one person on the team uses a coding agent?

Then the file works for one person. Say your delivery lead keeps a CLAUDE.md for a client folder, and Claude Code follows it well. The strategist drafts in a ChatGPT project, the designer in Claude, the copywriter in Gemini. None of them opens that folder, so none of their AIs reads the file.

Next, the lead pastes parts of it into Slack, then into each person’s project instructions. Now there are four copies. The lead updates the file on Tuesday, and by Thursday nobody can say which copy is current, or who changed the product name in the one the designer has.

You have three ways out:

  1. Paste the file into each tool’s instructions, and paste it again every time it changes.
  2. Share the folder itself. This helps the people who work in a coding agent or a desktop app with folder access, and nobody else.
  3. Keep the folder somewhere the whole team can open, with a record of who changed what.

Plain files are the part worth keeping: this year’s AI tools and next year’s can all read plain text. The open question with a team is who else reads them.

Where Alcoven fits

Alcoven is one place for a project’s brief, documents, tasks and history, shared by the people and agents on it. A project keeps its AGENTS.md and CLAUDE.md at the root. Everyone on the project can clone it with git (https://app.alcoven.co/git/your-project.git) and open it in Claude Code, Codex or any coding agent, so each person’s coding agent reads the same instructions; people who write to the project push their changes back. The people who never open a terminal add Alcoven to Claude, or to ChatGPT on plans where an MCP tool can write (check yours in OpenAI’s help centre), as an MCP server, and sign in once to reach every project they’re on; or they open the project in the Alcoven app. Whatever someone’s AI changes comes back under that person’s name, for everyone on the project. Every document keeps every past version: open one in the Alcoven app and you see what others changed since you last read it, and who changed it. Working from your own AI over git or MCP costs nothing on any plan, and one project with up to five people writing to it is free. Start a project free

Sources

Checked on 30 September 2026.