AGENTS.md reaches CLAUDE.md three ways, and one wrapped example line turns all of it off

When one rule document becomes two

Some AI coding tools read a rules file before they start working. It is like the note a teacher leaves on the board: follow these rules today. Two of these notes have different names. One is called AGENTS.md. It is a shared rules file that many tools understand. The other is called CLAUDE.md. The tool Claude Code reads that one only. The official docs say it plainly:

Claude Code reads CLAUDE.md, not AGENTS.md. — Manage Claude's memory (CLAUDE.md) / Claude Code Docs (loader)

So a team that writes its rules in AGENTS.md has a problem. The note is on the board, but the specific tool never reads it. The team needs some way to connect one file to the other, like taping a copy of the note where the other reader will see it. The question tested here was: which way of taping works, and does the choice matter?

AGENTS.md exists for a reason. Its own site describes it as the place for extra context that coding tools need:

AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need. — AGENTS.md

Three ways to connect them

There are three official ways to get the contents of AGENTS.md into CLAUDE.md.

The first is an import. An import is a one-line instruction inside CLAUDE.md that says "go fetch this other file." You write one line: @AGENTS.md. The official docs describe it this way:

CLAUDE.md files can import additional files using @path/to/import syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them. — Manage Claude's memory (CLAUDE.md) / Claude Code Docs (import syntax)

None

The second is a symbolic link. A symbolic link is not really a file. It is a pointer that says "this name actually points at that file.", like a nickname. When the tool opens CLAUDE.md, it silently gets AGENTS.md. One document, two names.

The third is a plain copy. You photocopy AGENTS.md and name the photocopy CLAUDE.md. Simple, but now the rules live in two places. Change one and the other is out of date.

How the measurement worked

To settle which wiring works, I built a small test. I wrote a rules document with a made-up marker phrase at the top. If the tool read the document, the marker would show up in its answers.

I tested six setups. A file with no connection at all. Three connected files: import, link, copy. One file where the import line was wrapped in a code block, of which more later. And one control file no tool would ever read. Each setup ran three times. The measure was two things: whether the marker appeared (out of 3 runs), and how many tokens (small chunks of text the model is billed for) the whole session used.

How we measured

Step 1. We prepared AGENTS.md files with a canary marker phrase in six different states.
Step 2. In each state we ran Claude Code three times and checked whether the marker appeared in the output.
Step 3. We confirmed the marker never appeared in the state with no connection to establish a baseline.
Step 4. We counted marker hits per connection method and compared them.
Step 5. We also tested the import statement placed inside a code block separately to see where it still resolves.

What happened with no connection

First, the control case. Leave only AGENTS.md in the folder and never create CLAUDE.md. In this case the marker showed up in none of 3 runs. The token count, 14940, was essentially the same as a session where no rules document existed at all, within 2 tokens of the control.

What that means for you: a rules file that nothing points at simply is not read. Hoping the tool finds it on its own does not work. Your team's careful rules have zero effect.

passNo connectionWe placed only AGENTS.md and did not create CLAUDE.md. In all three runs the marker was absent from the output. The document did not reach the model at all.

Hits 0/3

What the three connections measured

All three connections worked, every single time. Import: 3 of 3 hits, 17978 tokens. Link: 3 of 3 hits, 17856 tokens. Copy: 3 of 3 hits, 17862 tokens. That is the core result, in one small table:

Setup	Marker hits	Session tokens
No connection	0/3	14940
Import (`@AGENTS.md`)	3/3	17978
Symbolic link	3/3	17856
Copy	3/3	17862

Two things in these numbers are worth slowing down for.

First, the whole document costs about 2920 tokens per session. The document was 9674 bytes of text. The widest gap between any two working wirings was 122 tokens, roughly 4% of one document. And the import did not double-bill the document: it cost only 116 tokens more than the copy, which is the wrapper file's share, not the document's. You are not paying twice for one note.

Second, an honest caveat. Each setup ran only 3 times, and in 4 of the 6 cells exactly one run came in 109 tokens lower, for reasons nobody has identified yet. With only 3 runs, calling three wirings perfectly "equal" oversells the statistics. What the data does support is simpler and enough for most desks: all three hit 3 of 3, and their token gap is comparable in size to one observed wobble. For a person choosing a wiring, the question is not 4% of a token bill. It is which option breaks tomorrow.

So the practical summary is plain: three different-looking methods put the same document in front of the model, and the differences between them are too small to matter.

The trap of one line wrapped in an example

Now the part that actually caught me off guard.

An earlier version of my CLAUDE.md had the import line sitting inside a code example (a fenced code block), meaning a chunk of text marked off with triple backticks so it displays as "here is what the command looks like," not "here is the command." Many documents do this: they show an example line so readers can copy it.

The result: 0 of 3 hits. Session tokens were 15081, which is bare-agents territory, just 141 tokens above the no-connection baseline. The wrapped example line did not fail to import. It silently made the entire rules document never load. Six characters of fence decided whether a 2920-token document existed or not.

This is not a bug I stumbled into. The official docs state the rule directly:

Import parsing skips Markdown code spans and fenced code blocks. To mention a path in your CLAUDE.md without importing it, wrap it in backticks: writing @README keeps the text literal, while @README outside backticks imports the file. — Manage Claude's memory (CLAUDE.md) / Claude Code Docs

Here is the practical warning: the parser is a simple machine. It skips anything inside a code block, and it runs before the session starts. There is no warning, no error, no half-load. The document is in, or it is not. A documentation example intended to help someone can quietly turn off every rule you wrote.

passCode block importWe placed @AGENTS.md inside a code block. In all three runs the marker was absent from the output. The fenced line was not parsed as an import, and the entire document never reached the model.

Hits 3/3

How to choose a connection method

Since all three wirings measured equal, the choice is not about speed. It is about what fits your constraints.

The docs already name one such constraint: on Windows, creating a symbolic link needs special Administrator rights or Developer Mode, so they recommend the @AGENTS.md import instead. So the decision is ordinary, not technical: if you cannot get permission to create links, use the import line instead.

If you use Windows or cannot create links, use the import line.
If you must add tool-specific notes under the shared rules, use the import line, and accept its roughly 116 extra wrapper tokens.
If none of that applies, the symbolic link is the lightest option: lowest token count and only one document to maintain.
A plain copy is fine too, but remember two notes means two places to update.

And whenever you mention a file path inside CLAUDE.md, even in an example, wrap it in backticks unless you truly want it imported. That one habit is the difference between showing an example and deleting a document.

Takeaway

The @import, symbolic link, and copy methods all fed the same document content into the model, and without any connection the document did not get in at all.

Two plain instructions. If your team has no tool-specific notes to add and your environment restricts what files you can create, just pick whichever connection needs the least fuss and make it your default. If your document does include example paths, check that each one is wrapped before you save. That single glance protects the whole file.

What this article could not verify

This run tested one tool, on one computer, with only 3 repetitions per setup, so rare random misses would not show up. It did not test whether the tool actually follows the rules it reads. The docs themselves say a loaded document does not promise the rules are followed. It also ran only on macOS, so the Windows link-permission problem was never tested here. Next to check: rerun the same measurement more times and test whether the code-fence trap looks the same with much larger documents.

One line on when this article's judgment would be wrong: if the same measurement is run again and any one method misses in all 3 runs, or the token gap moves far beyond 122, then "the three ways are equal" is a wrong call and this piece should not be trusted on it.