cachly← All posts
Rules files

AGENTS.md or CLAUDE.md? One Source for Every AI Tool

I use more than one AI coding tool. Each one wants its own rules file. I read the vendors' docs to find out which file each tool reads, and what that means for keeping one source of truth.

The short version: keep one file with the rules, and point every tool at it. How you point differs per tool. The details below come from the vendors' own docs, which I link next to each claim. Docs change, so check the date of the page when you read this.

The problem: three tools, three files

My repo can end up with a CLAUDE.md, an AGENTS.md and a .github/copilot-instructions.md. Each starts as a copy of the others. Two weeks later they disagree. One still says to run the old test command.

AGENTS.md is the attempt to end this. agents.md describes it as "a simple, open format for guiding coding agents". It is a plain Markdown file, like a README for agents.

Who reads what

This is what I could confirm on each vendor's page. Where a page said nothing, the cell says so.

ToolReadsSource
Claude CodeCLAUDE.md. Reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above.Claude Code docs
CodexAGENTS.md, one file per directory, from the project root down to the current directory.Codex docs
CursorRules in .cursor/rules, and AGENTS.md in the project root and subdirectories. The page does not mention CLAUDE.md.Cursor docs
GitHub Copilot.github/copilot-instructions.md, path-specific .instructions.md files, AGENTS.md, or a single CLAUDE.md or GEMINI.md in the repository root.GitHub docs
Gemini CLIGEMINI.md by default. A different name, such as AGENTS.md, via context.fileName in settings.json.Gemini CLI docs

Windsurf is missing from the table on purpose. The agents.md site lists it as supporting AGENTS.md. Windsurf's own documentation has moved to a Devin Desktop page, and that page did not say it for Windsurf. I could not confirm it there, so I make no claim.

Two details that cost me time

First, Claude Code. If you add a CLAUDE.md next to an existing AGENTS.md, Claude reads only the CLAUDE.md. A personal CLAUDE.local.md has the same effect. The docs list a setting, Project instructions, that can be set to claude-md-and-agents-md to load both.

Second, precedence. In Codex, files closer to your working directory come later and take precedence. In Copilot, the nearest AGENTS.md takes precedence. The agents.md FAQ says the closest file wins and that explicit prompts in chat override everything.

One source file

My setup is AGENTS.md as the single source. Claude Code gets a CLAUDE.md that imports it. The Claude docs show this pattern:

# CLAUDE.md
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The import is expanded and loaded alongside the CLAUDE.md that references it. Claude-only instructions go below it. If you need no Claude-specific text, the docs say a symlink also works: ln -s AGENTS.md CLAUDE.md. I use the import, because it also leaves room for Claude-only lines.

For Gemini CLI, the same idea is a line in settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Cursor, Codex and Copilot read AGENTS.md directly according to the pages above. Check your own tool versions, because the Claude Code docs, for example, name a minimum version for reading AGENTS.md.

What does not belong in the file

With one file the drift is gone. A different problem remains. Every one of these tools loads the file into the context, and the Claude docs say longer files reduce adherence. They target under 200 lines. Cursor's docs say to keep rules under 500 lines. The Codex docs set a combined size limit of 32 KiB by default.

So I split what I know into two kinds.

Events pile up in a rules file until it is too long to be read well. "We use idempotency keys for payments because of the double-charge in March" is useful twice a year. As line 148 of AGENTS.md it costs context in every session.

Where I put the events

There are options without any extra product. A docs/decisions folder with one short file per decision, linked from AGENTS.md. Path-scoped rules, if your tool has them: Claude Code loads .claude/rules files with a paths field only when matching files are in play, and Copilot has applyTo in its .instructions.md files. Both keep a rule out of the context until it is relevant.

I also use cachly for this. It is an MCP server that stores lessons: after a fix, the assistant writes one, and later tasks get the matching lessons shown. A lesson looks like this:

learn_from_attempts(
  topic="payments:idempotency-keys",
  outcome="success",
  what_worked="Send an Idempotency-Key per charge attempt; retries reuse it.",
  what_failed="Retry without a key charged the customer twice.",
  severity="major",
  file_paths=["api/payments/charge.ts"]
)

What cachly can do here, taken from its source: the repository contains hook adapters for Claude Code, Cursor, Copilot, Codex and Gemini CLI. In Claude Code, a UserPromptSubmit hook sorts the stored lessons against the prompt you just typed and adds the matching ones to that turn. A PreToolUse hook does the same for the file about to be edited. The tool then sees two or three lessons, not the whole history.

What it does not do, so you are not surprised:

A short checklist

  1. Pick one source file. AGENTS.md is the one the Codex, Cursor and Copilot pages above name directly.
  2. Add the one-line bridge each remaining tool needs: an import in CLAUDE.md, fileName in Gemini settings.
  3. Keep it short. Move anything that is a story, not a rule, out of it.
  4. Run one test per tool: ask it what the build command is. A wrong answer is a hint that the file is not loaded.

If you already use a CLAUDE.md and wonder how it compares to a memory server, I wrote that up in Cachly vs CLAUDE.md. For how memory carries across sessions in Claude Code, see Claude Code Persistent Memory. If your rules are in the file but the tool still skips them, read Claude Code Ignores CLAUDE.md.

cachly.dev

For solo developers, teams and whole companies

Explain it once. Every AI knows it.

cachly keeps what you explain to your AI in every session. Claude Code, Cursor, Copilot and Windsurf read your rules, decisions and solved bugs: for you alone, for your whole team and for every team in your company. Servers in Germany, with SSO and a DPA for companies.

Servers in the EU · one command, restart your editor, done · 1 project free

Four ways to install

Claude Code
/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

Then turn on auto-update once: /plugin → Marketplaces → cachly → Enable auto-update

Any MCP editor
npx @cachly-dev/mcp-server@latest autopilot