iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Short answer: Claude Code does not always merge AGENTS.md and CLAUDE.md. In its documented default mode, it reads AGENTS.md only when there is no qualifying CLAUDE.md or CLAUDE.local.md in the working directory or an ancestor. If a qualifying Claude file exists, Claude Code reads the CLAUDE.md files instead. You can change that behavior in /config, select a mode that reads both, or import AGENTS.md from CLAUDE.md.
This distinction applies to Claude Code, not automatically to every coding agent. The filenames are conventions whose behavior depends on the tool, version and configuration. The safest approach is to verify what your installed Claude Code session loaded, then keep shared instructions in a file and loading mode your team has deliberately chosen.
![Claude AI for Beginners Bible: [5 in 1] The Ultimate Guide to Automate Your Work, Save Hours Every Week, and Use AI for Real-World Results](https://m.media-amazon.com/images/I/415+fSJacsL._SL160_.jpg)
The practical difference between AGENTS.md and CLAUDE.md
Both files are Markdown project-instruction files. Their names do not, by themselves, establish a universal precedence rule. Claude Code has a documented selection mechanism, while another coding agent may ignore one file, support both, or define a different order.
| Question | Claude Code answer |
|---|---|
| Which file wins by default? | Neither universally “wins.” In claude-md-or-agents-md mode, a qualifying Claude file switches the default selection to CLAUDE.md files; otherwise Claude Code can read AGENTS.md. |
| Can both be read? | Yes. Select claude-md-and-agents-md, or have a CLAUDE.md import AGENTS.md with @AGENTS.md. |
| Does the directory matter? | Yes. Root and ancestor instructions can load at session start; a subdirectory file can load when Claude works in that area, subject to the documented selection rules. |
| Does the Claude Code version matter? | Yes. Direct AGENTS.md support requires Claude Code v2.1.277 or later. |
Anthropic documents the loading rules in Claude Code’s project-memory documentation. Treat that page as the authority for the installed product’s current behavior rather than assuming a convention used by another tool.
#1 Best Overall
What Claude Code considers a qualifying CLAUDE.md
The default selection test looks for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or anywhere above it in the directory tree. The presence of one of those files changes what the default claude-md-or-agents-md mode selects.
A user-level ~/.claude/CLAUDE.md, an organization-managed CLAUDE.md, and files under .claude/rules/ do not count toward that particular “is there a project Claude file?” switch. They can still participate in Claude Code’s broader instruction and management behavior, but they are not the files that make the default project selection change from AGENTS to CLAUDE.
The three common repository cases
| Repository state | Default result |
|---|---|
AGENTS.md exists, with no qualifying Claude file in the working directory or ancestors |
Claude Code reads AGENTS.md as project instructions. |
AGENTS.md exists alongside a qualifying CLAUDE.md or CLAUDE.local.md |
Claude Code reads the Claude files only in the default mode; it does not automatically merge the AGENTS file. |
CLAUDE.md contains @AGENTS.md |
Claude Code reads CLAUDE.md and expands the referenced AGENTS file through the import. |
That second row is the source of many surprises: adding a previously unrelated CLAUDE.md anywhere above a project can change which project-instruction family is selected.
Free tools Windows power users keep installed
One-click scans. No signup required.
Claude Code’s instruction modes
The /config command exposes the Project instructions setting. Anthropic documents four named choices:
| Setting | What it loads at launch | When to choose it |
|---|---|---|
claude-md-or-agents-md |
The default conditional selection: AGENTS when no qualifying project Claude file exists; Claude files when one does. | Use when you want Claude Code’s documented automatic selection and do not need both formats merged. |
claude-md-and-agents-md |
Both project-instruction types. | Use when a repository intentionally maintains shared AGENTS guidance and Claude-specific guidance. |
claude-md |
Only CLAUDE.md files. |
Use when Claude-specific files are the sole source of project instructions. |
managed-only |
Managed instructions and auto memory at launch; project, local and user CLAUDE.md files and AGENTS.md are excluded from launch loading. |
Use when an organization centrally controls the instruction surface. |
A setting change applies from the next message and in new sessions, rather than retroactively rewriting the context already assembled for the current exchange. Start a fresh session when you need an unambiguous test of a new mode.
How to change the setting
- Start Claude Code in the repository you want to configure.
- Enter
/config. - Open the Project instructions setting.
- Select
claude-md-or-agents-md,claude-md-and-agents-md,claude-mdormanaged-only, according to the table above. - Send a new message, or start a new session, so the changed selection takes effect.
Version and availability caveats
Direct AGENTS.md support requires Claude Code v2.1.277 or later. Anthropic also documents sessions in which the feature is unavailable, including older versions and sessions where the built-in support is disabled.
When direct support is unavailable, the documented fallback is to keep a CLAUDE.md and add an import:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems@AGENTS.mdThis makes the Claude file the selected project entry point while explicitly including the shared instructions. It avoids relying on an older session to discover AGENTS.md by itself. Check the installed version and the active configuration before diagnosing a missing instruction as a Markdown or path problem.
Directory scope and when files load
Claude Code builds context according to directory scope. Applicable AGENTS.md and Claude files in the working directory and parent directories can load at session start when the selected mode permits them. A subdirectory instruction file may load later as Claude begins working in that directory, again only when the documented file-selection conditions are met.
Files that participate in AGENTS discovery
AGENTS.mdin the working directory or a parent directory..claude/AGENTS.mdwhere Claude Code’s documented discovery rules include it.- Nested
AGENTS.mdfiles encountered while Claude works in their directory.
Names that are not interchangeable
AGENTS.local.mdandAGENTS.override.mdare not treated asAGENTS.mdinstructions by this mechanism.- Files under
.agents/are not read as AGENTS instructions by this mechanism. - A filename that resembles an instruction file does not become active merely because it contains Markdown.
Claude Code expands @path imports in AGENTS files. A Claude file can therefore include a shared AGENTS file, and an AGENTS file can include another referenced path, provided the path and the selected loading mode make that file applicable.
What belongs in each instruction mechanism
File choice should follow how broadly a rule applies, not which filename sounds more portable.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Content or rule | Best location | Reason |
|---|---|---|
| Build and test commands used across the project | Main project context file such as CLAUDE.md, or shared AGENTS.md when multiple tools support it |
These facts are broadly relevant and should be available before work begins. |
| Architecture overview and repository conventions | Main project context file | Claude Code’s documentation describes CLAUDE.md as a concise project briefing. |
| Constraints that apply only to a package or file family | Path-scoped rules | They load only when matching paths matter, reducing unrelated context. |
| Repeatable multi-step procedures | Skills | Skills are intended for reusable procedures rather than always-on background facts. |
| Personal, machine-specific preferences | A local or user-level mechanism supported by your configuration | Do not force private settings into a shared repository file. |
Anthropic’s Help Center recommends keeping CLAUDE.md short and signal-dense, at roughly under 200 lines. That is guidance, not a technical maximum. Remove stale commands and explanations when the project changes; a shorter current file is more useful than a long historical record. See Anthropic’s April 15, 2026 guidance on CLAUDE.md for the rationale.
Rank #4
“CLAUDE.md is a plain markdown file that Claude automatically reads at the start of every session in that directory.”
— Anthropic Help Center
Anthropic’s steering guidance also distinguishes always-on project context from path-scoped rules and reusable skills. Put a fact in the always-on file only when most tasks need it; move specialized constraints and procedures to the mechanism designed to load them when relevant. The broader explanation is available in Anthropic’s guidance on steering Claude Code.
Patterns for sharing one instruction source
Pattern 1: AGENTS.md as the shared file
Use this when your repository already targets several coding agents and each of them supports AGENTS.md. In Claude Code’s default mode, do not add a qualifying project CLAUDE.md unless you intend to switch the selection. This keeps one file as the entry point for tools that recognize it.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallPattern 2: CLAUDE.md importing AGENTS.md
Create a small Claude entry file and put the import near the top:
@AGENTS.mdAdd Claude-only notes below the import if needed. This is the documented compatibility fallback for sessions without direct AGENTS support and makes the relationship visible to reviewers.
Pattern 3: Explicitly read both file types
Choose claude-md-and-agents-md in /config when both files are intentionally maintained. Keep ownership clear: document which file contains shared rules and which contains Claude-specific additions. If the same rule appears in both, update both deliberately rather than assuming an undocumented precedence order.
Pattern 4: Symlinked files
Anthropic documents symlinks as another sharing option, but warns about editing through symlinks and Windows or Git checkout behavior. For a cross-platform team, an explicit import is usually easier to inspect and troubleshoot than a filesystem link. Test the checkout on every supported operating system before making a symlink part of the workflow.
Step-by-step setup examples
Set up an AGENTS-only repository
- Place
AGENTS.mdat the repository root. - Keep the file focused on commands, conventions, architecture facts, constraints and known gotchas that apply to the whole repository.
- Do not add a qualifying
CLAUDE.mdin the working directory or an ancestor if you want the default conditional mode to select AGENTS. - Start Claude Code from the repository and confirm the active context with
/contextor/memory.
Add Claude-specific guidance without losing shared instructions
- Keep the shared rules in root
AGENTS.md. - Create root
CLAUDE.md. - Add
@AGENTS.mdto the Claude file. - Place only Claude-specific conventions after the import.
- Open a new session and inspect the loaded context.
Handle a monorepo with narrower rules
- Put repository-wide facts in the root project file selected by your team.
- Add a nested instruction file in a package directory for rules that apply only there.
- Keep package-specific commands and constraints out of the root file unless every task needs them.
- Work in the package directory and verify that the nested file loads when Claude begins operating on that path.
This arrangement limits irrelevant context while preserving a clear inheritance structure. It does not make AGENTS.local.md, AGENTS.override.md or .agents/ active; those names remain outside the documented AGENTS mechanism.
Troubleshooting when an instruction is missing
| Symptom | Likely cause | What to check |
|---|---|---|
Claude ignores root AGENTS.md after someone added CLAUDE.md |
The default conditional mode switched to Claude files. | Look for CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory and ancestors. Import AGENTS or select the mode that reads both. |
| Both files exist, but only one appears in context | The active setting is claude-md-or-agents-md or claude-md. |
Open /config, inspect Project instructions, then start a new message or session after changing it. |
An old installation does not recognize AGENTS.md |
The version predates v2.1.277, or direct support is unavailable. | Use a CLAUDE.md containing @AGENTS.md, or upgrade to a supported Claude Code version. |
| A nested rule appears only after work enters a package | Subdirectory files can load on demand rather than at session start. | Check the file’s directory, name and active mode; then ask Claude to work in that path and inspect context. |
A file named AGENTS.local.md has no effect |
That filename is not part of the documented AGENTS discovery mechanism. | Rename or explicitly import the intended file, following your team’s privacy and sharing requirements. |
| A configuration change seems ineffective | The current message still has the old context. | Apply the change, send a new message or start a new session, and verify with /context or /memory. |
| A symlink works on one machine but not another | Symlink editing and Windows/Git checkout behavior differ. | Prefer an explicit import for a portable setup, or test symlink creation, checkout and editing on every supported platform. |
What “precedence” does—and does not—mean here
It is tempting to summarize the system as “CLAUDE.md overrides AGENTS.md.” That sentence is too broad. Claude Code’s default behavior is a selection rule controlled by a setting: the presence of a qualifying project Claude file selects the Claude family in one mode. Other modes read both, read only Claude files, or restrict launch loading to managed instructions. The documentation does not establish a cross-vendor precedence standard.
If you are writing repository guidance intended for several agents, describe the behavior of each supported tool separately. Do not infer that a file recognized by Claude Code will be recognized by another product, or that another product will resolve duplicate rules in the same order.
A decision checklist for teams
- Need one portable file? Use
AGENTS.mdonly where every target tool supports it; otherwise provide each tool’s documented entry point. - Need Claude-specific additions? Use
CLAUDE.mdand importAGENTS.md, or select the both-files mode. - Need organization-controlled instructions? Evaluate
managed-onlyand confirm which subdirectory files can still load on demand. - Need package-specific constraints? Use path-scoped rules or nested files instead of enlarging the root briefing.
- Need repeatable procedures? Put them in skills rather than always-on context.
- Need to diagnose a mismatch? Check the version, search ancestors for qualifying Claude files, inspect
/config, then verify with/contextor/memory.
The reliable mental model is “selected instruction sources plus directory scope,” not “two filenames with a universal winner.”
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
