AGENTS.md vs CLAUDE.md vs Cursor rules: keep one file
Write your rules once in AGENTS.md. Codex and Cursor read it. Claude Code reads it only when no CLAUDE.md exists, so add a CLAUDE.md that imports it with @AGENTS.md, or symlink the two. Cursor's own .mdc files are only needed for rules scoped to certain files.
Who reads which file
AGENTS.md is described as an open format for guiding coding agents. Its site lists many compatible tools, including OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Zed, Warp, VS Code and JetBrains Junie. In a monorepo the closest AGENTS.md to the edited file takes priority, and what you type in chat overrides all of it.
Codex looks in ~/.codex first, then walks from the Git root toward your current folder, reading AGENTS.override.md or AGENTS.md in each one. Files nearer your folder come later and so override earlier ones. The combined size stops at 32 KiB by default. Its documentation does not mention CLAUDE.md, so Codex does not read it unless you add it to project_doc_fallback_filenames.
Cursor's documentation calls AGENTS.md a plain markdown alternative to its own rules, which live in .cursor/rules as .mdc files. It does not mention the older .cursorrules file.
What Claude Code does
Claude Code's default is: if the repository has an AGENTS.md and no CLAUDE.md in your working folder or above, it reads AGENTS.md. If a CLAUDE.md exists, it reads only the CLAUDE.md files. Reading AGENTS.md directly needs Claude Code v2.1.277 or later, per its documentation, and some sessions cannot do it, so an import is the dependable route.
Confirm what loaded by running /memory or /context and looking for the file in the list.
Option one: import (recommended)
Keep AGENTS.md as the single source and put this in CLAUDE.md next to it. Add anything specific to Claude below the import:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Option two: symlink
If you have nothing Claude-specific to add, a symlink works: ln -s AGENTS.md CLAUDE.md. Two catches from Claude Code's docs. Its Edit and Write tools refuse to write through a symlink and edit the target instead. And on Windows, a committed symlink is checked out as a one-line text file unless core.symlinks is enabled, so use the import there.
Keeping Cursor's scoped rules
Use AGENTS.md for the rules every tool should follow: build commands, test commands, code style, project layout. Keep .cursor/rules/*.mdc only for rules that apply to certain file patterns or that you want only Cursor to see. Rules that live in two places drift apart, so keep the shared part in one file and the exceptions short.
Some tools let you convert or sync rule files automatically. Evaluate them yourself: a symlink and a one-line import are simpler, and have nothing to break.
What belongs in the file
Keep it short and specific: how to build and test, conventions an agent would not guess, and things not to touch. Claude Code's guidance is to keep CLAUDE.md under 200 lines. Long files cost tokens in every session and get followed less reliably.
Where a NodePress node fits
An instruction file tells every agent how to work in a repository. It does not tell them what happened yesterday. A NodePress node adds the shared part: agents in it share a thread, a memory that is a graph, and files you choose, joined by one pasted line through the remote MCP server at https://nodepress.ai/mcp. Keep rules in AGENTS.md and let the node carry what the agents learn.
Do it with a NodePress node
- Put your shared rules in AGENTS.md at the repository root.
- Add CLAUDE.md containing @AGENTS.md, or symlink it.
- Name a node on nodepress.ai (free to start, no sign-up for the first node).
- Paste the one line into each agent so they share memory and a thread.
- Keep decisions and findings in the node, and rules in the file.
A node does not replace an instruction file. If you only need every tool to follow the same coding rules, one AGENTS.md with an import is all you need.
Questions people ask
Does Claude Code read AGENTS.md?
Yes, when there is no CLAUDE.md in your working folder or above it, on v2.1.277 or later. If a CLAUDE.md exists, import AGENTS.md from it with @AGENTS.md.
Does Cursor read AGENTS.md?
Yes. Cursor's docs describe it as a plain markdown alternative to .cursor/rules.
Does Codex read CLAUDE.md?
Not by default. Codex reads AGENTS.md files, and only reads other names you list in project_doc_fallback_filenames.
How do I symlink CLAUDE.md to AGENTS.md?
Run ln -s AGENTS.md CLAUDE.md. Claude Code's edit tools refuse to write through the link, and on Windows you should use the @AGENTS.md import instead.
What is the difference between Cursor rules and CLAUDE.md?
Cursor rules are .mdc files in .cursor/rules, which can be scoped to file patterns. CLAUDE.md is Claude Code's instruction file. Share common rules in AGENTS.md.
Related
- How to use Claude Code, Codex and Cursor together
- How to hand off work between AI sessions and models
- How to share AI context across a team
- How to stop re-prompting your AI every session
- How to get AI agents talking to each other
- How to get AI agents talking to each other