AGENTS.md is a plain Markdown file at the repo root that coding agents read as project instructions. It is the cross-tool standard used by Codex, Cursor, Copilot, Windsurf, and others. It is a briefing, not a database.

AGENTS.md vs CLAUDE.md — which should I use?

If the team mixes tools, make AGENTS.md the shared source of truth and add a one-line CLAUDE.md that imports it with @AGENTS.md. If you only use Claude Code, CLAUDE.md alone is enough. Neither file replaces a writable shared brain for decisions and open tasks.

Does Claude Code read AGENTS.md?

Not as its primary entrypoint. Claude Code reads CLAUDE.md. Bridge with a first-line @AGENTS.md import (or a symlink) so you do not duplicate rules.

Can AGENTS.md replace agent memory?

No. AGENTS.md is loaded at session start and should stay short and stable. Living decisions, unfinished work, and cross-tool notes belong in files agents keep updating — that is what ReadmeDB stores via MCP.

readmedbmcp

Solution · AGENTS.md

AGENTS.md vs CLAUDE.md — and the file neither of them is

AGENTS.md is the cross-tool briefing. CLAUDE.md is Claude Code's native one. Both are instruction files. They do not hold yesterday's decision, the open task Cursor left, or anything a teammate's agent wrote on another machine. That living layer is a shared project brain.

What AGENTS.md is (and is not)

AGENTS.md is a repo-root Markdown file most coding agents look for: Codex, Cursor, Copilot, Windsurf, Zed, and a long tail of others. Put build commands, stack, and "never touch billing" there. Keep it short. Closest file to the code usually wins in nested folders.

It is not:

A running task list that changes every session
A searchable log of architecture decisions
Something Cursor writes and Claude reads without you copying files
A substitute for tool-specific rules (.cursor/rules, Claude hooks)

AGENTS.md vs CLAUDE.md

	AGENTS.md	CLAUDE.md	ReadmeDB
Who reads it	Codex, Cursor, Copilot, Windsurf, …	Claude Code (native)	Any MCP client
Where it lives	Git, repo root / nested	Git + optional user-level file	Cloud namespace, versioned
Agents write it?	Rarely — it should stay stable	Same — briefing, not a journal	Yes — that is the point
Open tasks / decisions	Wrong place — file bloats, goes stale	Wrong place	decisions.md, open-tasks.md

Does Claude Code support AGENTS.md?

Claude Code's entrypoint is still CLAUDE.md. Do not paste the whole AGENTS.md into it. First line of CLAUDE.md:

@AGENTS.md

# Claude-only extras below (hooks, permissions), if any

Cursor and Codex read AGENTS.md natively. One shared file, one Claude bridge. That still only covers instructions.

What to put in AGENTS.md vs the brain

AGENTS.md — how to build, what not to touch, pointer: “read/write the project brain via ReadmeDB MCP”
decisions.md — why we picked X; updated when the call changes
open-tasks.md — what the last session left unfinished
preferences.md — stack and taste that is still settling

Connect the brain (then point AGENTS.md at it)

Same MCP block in Cursor, Claude Code, or Windsurf:

{
  "mcpServers": {
    "readmedb": {
      "url": "https://app.readmedb.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rdb_your_key"
      }
    }
  }
}

Then add one line to AGENTS.md: before coding, read and update decisions.md / open-tasks.md in ReadmeDB. Do not treat this file as the living task list.

Not a second AGENTS.md in the cloud

Keep the instruction file in git. ReadmeDB is for the stuff that should move every day — the layer AGENTS.md vs CLAUDE.md blog posts never cover because they stop at “which filename.”

Start free — AGENTS.md plus a writable brain →

Claude / CLAUDE.md Cursor Codex CLI memory Windsurf memories Project brain MCP