Claude Code AGENTS.md: Why It Gets Ignored and the One-Line Bridge That Fixes It

Claude Code looks for CLAUDE.md. An AGENTS.md file in the same repository is not loaded, not merged, and not mentioned. This is the part that catches teams out: there is no error message and no startup warning, so a session with zero project context looks exactly like a session with full project context until the output starts drifting from your conventions.

This matters more than it used to because AGENTS.md has become a common shared-instruction file across other coding agents, so plenty of repos now carry one by default. If yours came from a template, or a teammate added one for a different tool, you can have a carefully written set of build commands and architecture notes that Claude Code has never once read.

Create a CLAUDE.md at the repo root whose first line is an import of the file you already have: @AGENTS.md on its own line. Claude Code expands that import at session start and loads the AGENTS.md content into context, so one file stays the source of truth and no instruction gets duplicated into two places that then drift apart.

Everything you write below the import is appended after it, which makes that space the natural home for Claude-specific instruction. A CLAUDE.md that starts with @AGENTS.md and then adds a short section saying to use plan mode for changes under a billing directory gives you the shared rules plus the Claude-only rules, in that order, with no copy-paste.

If you have nothing Claude-specific to add, skip the wrapper file and symlink instead. Running ln -s AGENTS.md CLAUDE.md points one name at the other, and Claude Code resolves it normally. The command prints no output when it works, which throws people, so treat the /context check as the real confirmation rather than looking for a success message.

The tradeoff is portability. Creating a symlink on Windows requires Administrator privileges or Developer Mode, so on a team where anyone is on Windows, the @AGENTS.md import is the version that works for everybody without a setup note. Use the symlink for a solo repo, use the import for a shared one.

The import syntax is @path/to/file and it accepts both relative and absolute paths. Relative paths resolve against the file that contains the import, not against your working directory, which is the single most common reason an import quietly fails in a monorepo. Imported files can import other files, up to a maximum depth of four hops.

Import parsing skips Markdown code spans and fenced code blocks, so you can write about a path without importing it by wrapping it in backticks. Outside backticks, @README imports the file; inside them, it stays literal text. If you have ever wondered why a CLAUDE.md that documents its own syntax suddenly pulled in three unrelated files, that is the reason.

CLAUDE.md is not one file, it is four scopes that all load and concatenate rather than override each other. Knowing which scope a rule belongs in is what stops a personal preference from ending up committed into a team repo.

Keep each file under roughly 200 lines. Longer files eat context and adherence drops as they grow. Worth knowing before you import a 900-line AGENTS.md and wonder why half of it stopped being followed: an import does not save context, because the imported file is expanded and loaded at launch just like inline text.

If the repo has instruction files scattered across several tools, you do not have to merge them by hand. Running /init generates a starting CLAUDE.md from your codebase, and it already reads Cursor rules in .cursor/rules/ or .cursorrules and Copilot rules in .github/copilot-instructions.md, folding the relevant parts in. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.

Set the CLAUDE_CODE_NEW_INIT environment variable to 1 and /init widens its net to AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules, and runs an interactive flow that explores the codebase and shows you a reviewable proposal before writing anything. There is also /import, which appends a one-time copy of files like AGENTS.md into the matching CLAUDE.md and carries over MCP servers, commands, subagents, and skills. That one needs Claude Code v2.1.213 or later, so check your version first if the command is not there.

This is the two-minute habit we teach members to run on any repo they did not set up themselves: before writing a single prompt, run /context and read the Memory files list. Not the file tree, not the repo root, the actual loaded list. It tells you exactly which instruction files made it into the session, and it is the only way to catch a silent miss like an unread AGENTS.md before it has cost you an afternoon of output that ignores your conventions.

We started running this after inheriting a client codebase with a well-written AGENTS.md, a tidy set of conventions, and a Claude Code session that cheerfully ignored all of it for most of a morning. The file was there. It was just never being read. One import line fixed it permanently, and the check now happens before any work starts.