Short answer: Claude Code does not always merge AGENTS.md and CLAUDE.md. In its default claude-md-or-agents-md mode, it reads AGENTS.md only when no qualifying CLAUDE.md or CLAUDE.local.md exists in the working directory or an ancestor. If a qualifying Claude file exists, Claude Code reads the CLAUDE.md family instead. You can change that behavior in /config, or explicitly include AGENTS.md with an @AGENTS.md import.
That is a Claude Code rule, not a universal standard for every coding agent. Treat the filenames as conventions, then verify what your installed tool actually loads.
As an Amazon Associate I earn from qualifying purchases.
The practical difference between AGENTS.md and CLAUDE.md
Both files are Markdown instructions intended to give an AI coding agent project context. The filename does not determine which instructions are correct, authoritative, or portable across products. Support and loading rules belong to the specific agent.
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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11| Question | AGENTS.md | CLAUDE.md |
|---|---|---|
| Primary purpose | Shared project guidance for tools that recognize the AGENTS.md convention. | Claude Code’s automatically loaded project context. |
| Claude Code default | Used when no qualifying CLAUDE.md or CLAUDE.local.md is found in the working directory or an ancestor. | Selected when a qualifying CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md is present in the working directory or an ancestor. |
| Can it be loaded with the other file? | Yes, if the Project instructions setting reads both, or if CLAUDE.md imports it with @AGENTS.md. |
Yes, under the same settings or import arrangement. |
| Claude Code version caveat | Direct support requires Claude Code 2.1.277 or later. | Supported as Claude Code’s native project-context format. |
| Universal precedence rule? | No. Claude Code documents its own selection modes; another agent may behave differently. | |
Anthropic’s Claude Code documentation describes this as conditional selection rather than an unconditional merge. That distinction prevents a common mistake: placing conflicting commands in both files and assuming the agent will combine them predictably.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
What Claude Code reads by default
The default Project instructions mode is named claude-md-or-agents-md. Claude Code checks for a qualifying Claude instruction file in the working directory or any parent directory. If it finds one, it chooses the CLAUDE.md family for the default launch load. If it finds none, it can use AGENTS.md.
Repository cases in the default mode
| Repository state | Default result |
|---|---|
| AGENTS.md exists; no CLAUDE.md or CLAUDE.local.md exists in the working directory or any ancestor | Claude Code reads AGENTS.md instructions. |
| AGENTS.md exists alongside a qualifying CLAUDE.md or CLAUDE.local.md | Claude Code reads the CLAUDE.md files by default, not AGENTS.md as a second automatic source. |
CLAUDE.md contains @AGENTS.md |
Claude Code reads CLAUDE.md and expands the imported AGENTS.md content. |
| Neither file exists in the applicable path | No instruction from either filename is available at that location. |
A qualifying file includes CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or an ancestor. A user-level ~/.claude/CLAUDE.md, an organization-managed CLAUDE.md, and .claude/rules/ do not count toward this particular AGENTS-versus-CLAUDE switch, although they may still participate in context loading through their own mechanisms.
Change the selection with Project instructions settings
Open Claude Code’s configuration interface with /config and inspect the Project instructions setting. The documented choices are:
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| Setting | What it loads | When to choose it |
|---|---|---|
claude-md-or-agents-md |
The default conditional selection described above. | Use one primary convention per repository and keep default behavior. |
claude-md-and-agents-md |
Both instruction types. | Use when a repository deliberately maintains shared AGENTS.md guidance plus Claude-specific guidance. |
claude-md |
Only CLAUDE.md files. | Use when you want Claude Code to ignore AGENTS.md in project instructions. |
managed-only |
Managed instructions and automatic memory at launch; it excludes project, local, and user CLAUDE.md files and AGENTS.md from launch loading. | Use in centrally governed environments where project-authored launch instructions are intentionally restricted. |
A setting change applies from the next message and in new sessions, according to the documentation. Do not infer that a change altered the current prompt already in progress; start a new session when you need an unambiguous test. The setting names and behavior are documented in Anthropic’s Claude Code instructions guide.
Directory scope and when files load
Instruction discovery is path-sensitive. Claude Code can read applicable AGENTS.md and .claude/AGENTS.md files in the working directory and parent directories at session start, subject to the selected mode. A subdirectory AGENTS.md may load when Claude begins working in that directory if the documented file-selection conditions are met.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Think in layers, not one giant file
- Repository or ancestor context: Put rules that apply to nearly every task, such as the package manager, test command, architecture summary, and non-negotiable constraints, in the project-level instruction file.
- Subdirectory context: Put rules for a service, application, or language-specific area in a nearer instruction file so unrelated work does not receive irrelevant detail.
- Claude-specific rules: Keep instructions that only Claude Code needs in CLAUDE.md or its supported rule locations.
- Reusable procedures: Put repeatable workflows in skills rather than copying long procedures into always-on context.
Claude expands @path imports in AGENTS.md as well as imports written in CLAUDE.md. This lets a short top-level file include a shared document while preserving a single source of truth. Files named AGENTS.local.md, AGENTS.override.md, and files under .agents/ are not treated as AGENTS.md instructions by this mechanism.
Version and platform caveats
Direct AGENTS.md support requires Claude Code version 2.1.277 or later. Anthropic notes that support can be unavailable in older sessions or when the relevant built-in plugin is disabled. If Claude Code does not recognize AGENTS.md directly, the documented fallback is to create or edit a CLAUDE.md file and add an import such as:
@AGENTS.mdThat import approach is also useful when the team wants Claude Code to consume the same file used by other agents without changing the project’s default selection mode. Check the installed version and confirm the feature in the current session rather than assuming every environment has the same support.
How to share one instruction file across agents
Choose a pattern based on whether you need one portable file, separate tool-specific additions, or centrally enforced settings.
Pattern 1: AGENTS.md as the shared source
- Create a concise
AGENTS.mdat the repository root. - Write only guidance that applies to every tool expected to read it: build and test commands, coding conventions, repository structure, and safety constraints.
- Use the default
claude-md-or-agents-mdmode when no qualifying CLAUDE.md exists. - Verify the loaded context with Claude Code’s
/contextor/memorycommands.
This is the cleanest arrangement when Claude Code and another agent both support AGENTS.md and there are no Claude-only requirements.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Pattern 2: CLAUDE.md imports AGENTS.md
- Keep cross-tool rules in root-level
AGENTS.md. - Create a short
CLAUDE.mdin the same project. - Add
@AGENTS.mdon its own line, then place Claude-specific additions below or around the import. - Start a new Claude Code message or session and inspect the loaded context.
This pattern is the documented compatibility fallback for versions without direct AGENTS.md support, and it makes the relationship explicit instead of relying on a configurable global mode.
Pattern 3: Read both through the setting
- Open
/config. - Select
claude-md-and-agents-mdfor Project instructions. - Review both files for duplicate or contradictory commands.
- Define ownership: for example, AGENTS.md contains portable rules, while CLAUDE.md contains only Claude Code workflow details.
- Use
/contextto verify that both sources are present.
Reading both is powerful but increases the chance of conflicting instructions. Do not put two different test commands, package managers, or security policies in the files and expect an undocumented precedence order to resolve them.
Pattern 4: A symlink
A symlink can make CLAUDE.md and AGENTS.md point to one physical document, but Anthropic flags editing-through-symlink and Windows or Git checkout concerns. For a cross-platform team, an explicit @AGENTS.md import is generally easier to inspect and reproduce. If you do use a symlink, document how contributors create it and test a fresh checkout on every supported operating system.
What belongs in CLAUDE.md
Anthropic describes CLAUDE.md as plain Markdown context automatically read at the start of a session in the relevant directory. The most useful content is short, concrete, and stable:
- Exact build, lint, format, and test commands.
- A brief architecture map showing where major components live.
- Required conventions for naming, error handling, logging, and APIs.
- Hard constraints, such as files that must not be edited or generated artifacts that must be regenerated.
- Known gotchas, environment prerequisites, and expected local services.
The Anthropic Help Center recommends keeping the file short and signal-dense, under roughly 200 lines. That is guidance, not a technical limit. A compact file that prevents a recurring mistake is more useful than a long narrative that buries the command Claude needs. See Anthropic’s April 15, 2026 Help Center guidance for the recommendation.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Move narrow rules out of always-on context
If a rule applies only to matching paths, use path-scoped rules instead of placing it in the global project briefing. For example, a rule for database migrations belongs with migration files, not in every front-end task’s context. If a procedure is reusable, such as releasing a package or rotating a development certificate, a skill is a better home than a long always-on checklist.
Anthropic’s steering guidance distinguishes always-on CLAUDE.md context from path-scoped rules, skills, hooks, and subagents. That division keeps the initial context focused while still making specialized behavior available when needed. The overview is available in Anthropic’s steering article.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Recommended repository layouts
One portable file
project/
├── AGENTS.md
├── src/
├── tests/
└── package.jsonUse this when all participating tools understand AGENTS.md and Claude Code is running in its default selection mode without a qualifying CLAUDE.md.
Shared rules plus Claude additions
project/
├── AGENTS.md
├── CLAUDE.md
├── .claude/
│ └── rules/
├── src/
└── tests/Here, AGENTS.md holds portable rules, CLAUDE.md imports it and adds Claude-specific details, and path-scoped rules hold narrower constraints. Keep the import visible near the top of CLAUDE.md so a maintainer can understand the dependency immediately.
Recommended Free Tools
Multiple services
project/
├── AGENTS.md
├── CLAUDE.md
├── services/
│ ├── billing/
│ │ └── AGENTS.md
│ └── search/
│ └── AGENTS.md
└── web/The root file can describe repository-wide commands, while service-level files explain local build steps or boundaries. Because subdirectory loading is conditional and path-sensitive, validate each service from a session working in that directory.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
How to verify what Claude Code actually loaded
- Check the active setting: Run
/configand record whether the mode isclaude-md-or-agents-md,claude-md-and-agents-md,claude-md, ormanaged-only. - Check the context: Run
/contextto inspect the instructions and other context Claude Code reports for the session. - Check memory and project files: Run
/memorywhen you need to inspect memory-related loading and the files Claude associates with the project. - Test from the relevant directory: A root session and a session started in a service subdirectory can discover different path-scoped files.
- Start a fresh session after changes: Settings and launch-loaded instructions are easiest to reason about when no prior context remains.
Do not treat a successful answer as proof that a file loaded. Ask Claude Code to identify the applicable instruction file or inspect the context display, then compare that result with your expected directory and setting.
Common failure modes and fixes
“I added AGENTS.md, but Claude ignores it.”
First check for a qualifying CLAUDE.md or CLAUDE.local.md in the working directory or an ancestor. In the default mode, that presence switches selection to the CLAUDE.md family. Either remove the accidental qualifying file, choose claude-md-and-agents-md, or import AGENTS.md from CLAUDE.md.
“The import works on one computer but not another.”
Check the Claude Code version, whether the built-in AGENTS support is enabled, and whether the file path in the @ import is correct relative to the importing file. Also check case sensitivity when the repository moves between filesystems.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →“Both files load, but instructions conflict.”
Use one file as the owner of each rule. Keep portable commands and conventions in AGENTS.md; reserve CLAUDE.md for Claude-specific behavior. Delete duplicate wording, choose one canonical command, and test the result in a new session. Do not rely on an assumed universal precedence rule.
“A subdirectory rule never appears.”
Start Claude Code in that directory or ask it to work on a file beneath it, then inspect /context. Confirm the filename is exactly AGENTS.md or a supported CLAUDE.md location; AGENTS.local.md, AGENTS.override.md, and .agents/ are not recognized as AGENTS.md instructions by this mechanism.
“Managed-only removed project guidance.”
That is expected: managed-only excludes project, local, and user CLAUDE.md files and AGENTS.md from launch loading. Ask an administrator to provide the required managed instructions or select a less restrictive mode when policy allows.
How to choose a convention for your team
| Your situation | Recommended arrangement | Reason |
|---|---|---|
| Several coding agents support AGENTS.md and rules are mostly portable | Root AGENTS.md, no qualifying CLAUDE.md unless needed. | Claude Code can use the shared file in its default mode. |
| You need Claude-specific additions | AGENTS.md plus CLAUDE.md importing it. | Shared guidance stays in one place while Claude additions remain explicit. |
| You intentionally maintain two complete instruction sets | Select claude-md-and-agents-md and remove contradictions. |
Both files are loaded by configuration rather than by assumption. |
| Enterprise policy controls project instructions | Use the managed-only mode and managed files supplied by administrators. | Launch loading follows the centrally governed policy. |
| Rules apply only to one path or workflow | Use path-scoped rules or skills instead of expanding the root file. | Specialized guidance appears when relevant without bloating every session. |
Maintenance practices that keep context reliable
- Review after tooling changes: Update commands when the package manager, test runner, language version, or directory layout changes.
- Prefer executable facts: “Run
npm test -- --runInBand” is more useful than “test thoroughly,” provided that command is actually correct for the repository. - Remove stale exceptions: Old migration warnings and retired deployment steps can cause an agent to take the wrong path.
- Keep secrets out: Instruction files are committed project context. Never place API keys, passwords, private tokens, or sensitive customer data in them.
- Review imports as dependencies: A renamed or moved AGENTS.md can silently break a CLAUDE.md import. Keep the path stable or update the import in the same change.
- Test from a clean checkout: Verify that the intended files exist, the selected setting is available, and a new session sees the expected context.
Bottom line: filenames are conventions; loading modes are the rule
For Claude Code, the default answer is conditional: AGENTS.md is selected only when no qualifying CLAUDE.md or CLAUDE.local.md exists above the working directory. A setting can read both, only CLAUDE.md, or managed instructions, and an explicit @AGENTS.md import can bridge versions and tools. Build your repository around a clear ownership model, then confirm the result with /config, /context, and /memory instead of assuming that a filename was loaded.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
