AGENTS.md와 CLAUDE.md 차이, 멀티 에이전트 규칙을 맞추려면

Running more than one AI coding assistant against the same repository raises a simple question: how should AGENTS.md and CLAUDE.md relate to each other, and how do you keep them in sync in one repo? This note only covers the role difference between the two files, how to sync them, and which one wins in a conflict, based on current official documentation.

Policies for each tool may change after future updates, so treat this as a snapshot of current documentation rather than a permanent guarantee.

How do AGENTS.md and CLAUDE.md differ in role?

Short answer: AGENTS.md is a universal markdown rule file that multiple agents can read, while CLAUDE.md is a file that only Claude Code reads.

  • AGENTS.md follows the agents.md spec, acting as an open, cross-agent markdown convention — effectively a README written for agents. It can live at the repo root or be nested in subfolders.
  • Cursor can also read AGENTS.md as a plain-markdown alternative to .cursor/rules; this note does not cover how to write .mdc rule files.
  • Claude Code does not automatically read AGENTS.md by default — it only reads CLAUDE.md.

What’s the best way to keep the two files in sync in one repo?

Short answer: The most recommended approach is a live import — adding @AGENTS.md inside CLAUDE.md.

  • Create CLAUDE.md, put an @AGENTS.md import line at the top, and add Claude-specific settings below it. This keeps the two files synced on an ongoing basis instead of letting them drift apart.
  • A symlink such as ln -s AGENTS.md CLAUDE.md also works, but on Windows it may require Admin rights or Developer Mode, so the @AGENTS.md import is usually simpler.
  • The /import command available from v2.1.213 onward only copies content once, so the two files can drift apart over time. If you need ongoing sync, prefer the live @AGENTS.md import instead.

Which file wins when AGENTS.md and CLAUDE.md conflict?

Short answer: Each tool follows its own documented convention, and regardless of tool, a prompt typed directly in chat always outranks any rule file.

  • Claude Code only follows CLAUDE.md and whatever it explicitly imports.
  • In the AGENTS.md ecosystem (including Cursor), the AGENTS.md file closest to the file being edited wins. When files are nested at multiple levels, the more specific, deeper file is combined in and takes precedence.
  • No matter what a rule file says, a prompt the user types directly in chat always applies first and overrides every file-based rule.

When both files exist side by side without one importing the other, there is no single officially documented cross-tool precedence rule that decides the winner. This note only summarizes what each tool’s own documentation states.

FAQ

Can Claude Code read AGENTS.md at all?

Yes — when the CLAUDE_CODE_NEW_INIT=1 environment variable is set, running /init can read AGENTS.md.

Can I use only AGENTS.md in Cursor instead of .cursor/rules?

Yes. Cursor reads AGENTS.md as a plain-markdown file at the root and in nested folders.

It can work, but it may require Admin rights, so the @AGENTS.md import is usually simpler in most cases.

Sources