The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Cursor currently recognizes root-level AGENTS.md and CLAUDE.md, supports legacy root .cursorrules, and uses configurable files in .cursor/rules. Its official documentation does not publish a deterministic loading order or a conflict winner among AGENTS.md, CLAUDE.md and .cursorrules. Treat them as recognized instruction sources, not as a documented priority chain.
The safest way to make a repository predictable is to keep one authoritative set of project instructions, move legacy content into a Project Rule set to Always Apply, and state any priorities explicitly. When instructions conflict, inspect the active rules or context view in the Cursor version you have installed rather than assuming that one filename automatically overrides another.
As an Amazon Associate I earn from qualifying purchases.
At a glance: what Cursor reads
| File or mechanism | What the documentation establishes | What you should not assume |
|---|---|---|
.cursor/rules/*.mdc |
Configurable Project Rules stored in the repository. A rule can be set to Always, Auto Attached, Agent Requested or Manual. | Every rule is active for every prompt. Auto Attached, Agent Requested and Manual rules have conditions or require selection. |
Root AGENTS.md |
A plain-Markdown project-instruction alternative described as globally applied within the project. | A guaranteed hierarchy over other files, arbitrary nested-file behavior, or a universal result across Cursor versions. |
Root CLAUDE.md |
Cursor’s help page says it is picked up automatically and applied to every conversation. The CLI guide says root CLAUDE.md is read when present. |
That “every conversation” wording establishes frequency, not priority over AGENTS.md or .cursorrules. |
Root .cursorrules |
Still recognized, but documented as legacy and deprecated. Cursor recommends moving its contents into a Project Rule. | An official file-by-file precedence rule or a guaranteed winner when it conflicts with another project file. |
Cursor also documents a category-level precedence statement—Team Rules over Project Rules over User Rules. That statement concerns rule categories and does not specify the order among individual project files.
There are therefore two separate questions. “Does Cursor recognize this source?” is answered for all four mechanisms above. “Which source wins when two instructions disagree?” is not answered by a published filename order. Keeping those questions separate prevents a common configuration mistake: treating recognition as proof of precedence.
#1 Best Overall
Does Cursor read AGENTS.md?
Yes, current Cursor documentation recognizes a root-level AGENTS.md as a project-instruction file. The rules guide presents it as a straightforward Markdown alternative to configurable Project Rules. In the behavior described there, its instructions are applied across the project rather than selected through per-rule attachment modes.
What “root-level” means
Place the file at the top of the project that Cursor has opened, alongside the project’s main configuration and source directories. The documented behavior is for that root file; it is not a blanket promise that every AGENTS.md found in every subdirectory is merged automatically.
In a monorepo, confirm which directory is actually open as the workspace root. A correctly named file in a parent or sibling directory is not the same thing as the root file documented by Cursor. Keep the project policy in the opened root unless your installed version explicitly documents another discovery scope.
Nested files are version-sensitive
The rules guide associated root-only limitations with the documentation around v1.5 and described nested AGENTS.md support as planned for v1.6. Those are version-specific statements, not proof that nested discovery works identically in every current build. If nested instructions matter, verify the behavior in your installed Cursor release and in the active context view.
Do not use the v1.6 planning reference as a guarantee that nested files are available, merged in a particular order, or supported by every Cursor surface. Treat it as a documentation milestone and test the behavior where you work.
When an AGENTS.md is a good fit
- One concise set of repository-wide conventions is enough.
- You want instructions readable by people and tools without introducing rule metadata.
- You do not need file-pattern matching, manual invocation or agent-requested rules.
- You want a simple file that can be reviewed alongside source changes.
If different parts of a monorepo need different instructions, a single root file can become difficult to maintain. In that case, use scoped Project Rules instead of assuming that adding more Markdown files will produce a documented hierarchy.
Does Cursor read CLAUDE.md?
Yes. Cursor’s help documentation says it reads CLAUDE.md files the same way it reads AGENTS.md. The same page describes a root CLAUDE.md as being applied to every conversation. Cursor’s CLI documentation also says it reads root AGENTS.md and CLAUDE.md, when present, alongside the project’s .cursor/rules.
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 →Cursor Docs summarizes the relationship this way: “Cursor reads CLAUDE.md files the same way it reads AGENTS.md.” That is useful confirmation that the filename is recognized, but it is not a statement that one file outranks the other.
What the statement does establish
- A root
CLAUDE.mdis an accepted project-instruction source. - Its application is described as automatic rather than dependent on a user manually attaching it to each prompt.
- It can coexist with
AGENTS.md, legacy.cursorrulesand Project Rules. - The CLI can read it when the file is present at the project root.
What it does not establish
“Applied to every conversation” does not mean “wins over every other project file.” The documentation does not say whether CLAUDE.md is loaded before or after AGENTS.md, whether its text overrides a contradictory Project Rule, or whether duplicate instructions are deduplicated. Do not convert an application-frequency statement into a precedence claim.
Is .cursorrules still supported?
Yes, according to Cursor’s rules documentation, but it is a legacy mechanism. Cursor labels .cursorrules as deprecated and recommends using Project Rules instead. The documented migration target is a rule in .cursor/rules configured to Always Apply, which is intended to match the old always-on behavior.
The rules documentation describes the legacy status directly: “Still supported, but deprecated. Use Project Rules instead.” That wording means an existing file may continue to influence a project, while new configuration should generally use the current rule system.
Why legacy support still matters
Existing repositories may depend on a root .cursorrules. Removing it without first transferring its content can change an agent’s behavior. Legacy recognition also explains why a project may appear to follow instructions that are not visible in the newer Project Rules interface.
When taking ownership of an older repository, include .cursorrules in your configuration audit even if your team has standardized on AGENTS.md or CLAUDE.md. A hidden-looking legacy file can contain commands, style requirements or safety checks that still affect responses.
What legacy support does not tell you
“Still supported” is not a promise that .cursorrules takes precedence over AGENTS.md or CLAUDE.md. The official material reviewed for this topic does not publish a filename-by-filename conflict algorithm, so a contradictory legacy file should be treated as a maintenance risk, not as a reliable override mechanism.
How .cursor/rules changes the question
.cursor/rules is Cursor’s configurable Project Rules system. Rules are project files, normally version-controlled with the repository, and each rule can have an application mode. Unlike a single always-on Markdown file, this system lets you decide when a particular instruction set enters the active context.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallAlways
An Always rule is intended to be included for every relevant interaction in the project. This is the documented migration setting for reproducing the old always-on role of .cursorrules. Use it for requirements that should not depend on the files being edited or on an agent deciding to request the rule.
Rank #3
Auto Attached
An Auto Attached rule is selected when its configured file patterns match the work in progress. A rule for tests, for example, can be attached when matching test files are involved. Because attachment depends on conditions, the mere existence of the file does not make its instructions universally active.
Pattern design matters. A rule intended for a particular package should not use a pattern so broad that it attaches to unrelated directories, and a rule intended for all tests should not be so narrow that it silently fails to attach. Check the active context when validating a pattern.
Agent Requested
An Agent Requested rule is available for the agent to select when it considers the rule relevant. Its presence is not equivalent to unconditional application. This mode suits guidance that is useful in some tasks but would add noise to every conversation.
Free tools Windows power users keep installed
One-click scans. No signup required.
Manual
A Manual rule requires explicit invocation. This is useful for an instruction set that should be used only on demand, such as a release checklist or a specialized migration procedure. A mandatory build or security requirement does not belong only in a Manual rule.
This mode system is why a directory listing alone cannot answer “what is active right now?” The active set depends on the rule mode, matching conditions and any explicit selection. Two conversations in the same repository can have different active Project Rules if they touch different files or use different invocations.
In what order does Cursor read these files?
The official documentation reviewed does not provide a deterministic order among root AGENTS.md, root CLAUDE.md and root .cursorrules. It identifies each source and describes how some are applied, but it does not state which one is loaded first, which one wins a contradiction, or whether later text automatically overrides earlier text.
Do not infer order from the category precedence statement
Cursor documents the broad relationship Team Rules > Project Rules > User Rules. That is a precedence statement between categories. It is not an ordering of individual project files. A root AGENTS.md, a root CLAUDE.md and a legacy .cursorrules are all project-level sources for this purpose; the category statement does not identify a winner among them.
Recommended Free Tools
For example, Team Rules being listed above Project Rules does not imply that CLAUDE.md beats AGENTS.md, or that either beats .cursorrules. Category precedence and file discovery are different layers of configuration.
Why filename order is unsafe
Assuming alphabetical order, creation date, “newest file wins” or “the modern filename wins” can produce silent failures. An agent may follow one instruction in one task and another instruction in a different task if Project Rule attachment changes. Without a published algorithm, a filename-based conflict rule is speculation.
What happens when instructions conflict?
There is no documented universal winner among these three filenames. For example, if AGENTS.md says to use one formatter and CLAUDE.md says to use another, Cursor’s public documentation does not tell you which sentence overrides the other. The same uncertainty applies when either file conflicts with legacy .cursorrules.
Make the intended priority explicit
Instead of relying on load order, write a single authoritative instruction set and remove contradictory copies. If separate files must remain for compatibility, make them agree on the same commands, paths and standards. Add a short statement such as “When instructions differ, follow the rule in .cursor/rules/project-policy.mdc” only if that rule is actually configured and active; this is a repository convention, not an official Cursor precedence feature.
Keep the canonical policy specific enough to resolve practical questions: which package manager to use, how tests are invoked, which directories are generated, and what validation is required before a change is considered complete. Duplication is safest when it is identical; paraphrased copies can drift and create conflicts that are hard to diagnose.
Check the active context in your installation
Use Cursor’s rules or context view to see which instructions are active for the current conversation. The exact label and location can vary by installed version. This check can reveal that an Auto Attached rule did not match, a Manual rule was never invoked, or a legacy file is still contributing instructions.
Perform this check after changing a rule and again in a fresh conversation. The goal is not to infer an undocumented global order, but to confirm which sources your installed build included for that task.
Recommended setup for a new repository
- Choose one primary home for project guidance. Use a root
AGENTS.mdor rootCLAUDE.mdfor a simple, repository-wide policy, or use.cursor/ruleswhen you need scoping and application modes. - Search for all four mechanisms. Check for root
AGENTS.md, rootCLAUDE.md,.cursorrulesand files under.cursor/rules. Record which files contain overlapping commands. - Separate universal and conditional guidance. Put build, test, security and style requirements that apply everywhere in an Always rule or one canonical Markdown file. Put directory-specific instructions in Auto Attached rules with precise patterns.
- Reserve Agent Requested and Manual modes for optional workflows. Do not place a requirement that must always run in a rule that the agent may omit or a user must remember to invoke.
- Remove or reconcile legacy content. If you migrate
.cursorrules, copy its useful instructions into a Project Rule set to Always Apply, then delete or neutralize the old contradictory copy after confirming the repository’s behavior. - Commit the configuration. Version-control the chosen files so teammates and the CLI see the same project policy.
- Document the chosen convention. Tell contributors where the canonical policy lives and which rule modes are intentional. This reduces the chance that someone adds a second file expecting it to override the first.
Migration path from .cursorrules to Project Rules
- Open the existing root
.cursorrulesand classify each instruction as universal, path-specific or optional. - Create a corresponding file in
.cursor/rulesfor the universal portion and configure it as Always. - Move path-specific instructions into Auto Attached rules with matching file patterns.
- Put optional procedures in Agent Requested or Manual rules, depending on whether the agent may select them or a person must explicitly invoke them.
- Compare the resulting text with
AGENTS.mdandCLAUDE.md, if either exists. Resolve contradictions before deleting the legacy file. - Start a fresh conversation and inspect the active rules/context view. Test a harmless request that should exercise each rule mode.
- Commit the migrated files and remove the old file only after the team agrees that the canonical instructions are complete.
The Always setting is the documented way to approximate the old .cursorrules behavior. It is not evidence that the legacy file has a higher or lower priority than another project file.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Troubleshooting common surprises
A rule exists but the agent ignores it
- Confirm the file is inside the opened project, not in a sibling directory.
- For
.cursor/rules, check whether the rule is Auto Attached, Agent Requested or Manual rather than Always. - For Auto Attached rules, verify that the current files match the configured patterns.
- For Agent Requested rules, determine whether the agent selected the rule for this task.
- For Manual rules, invoke the rule explicitly before testing its instructions.
- Refresh the conversation or start a new one after changing project instructions, then inspect active context.
The agent follows two contradictory instructions
- Search every recognized source, including legacy
.cursorrules. - Look for overlapping Project Rules whose modes make both active.
- Consolidate the policy and state the desired behavior in one canonical location.
- Do not assume the filename that appears first in a directory listing is the winner.
- Check whether a Team Rule or User Rule is involved; category precedence is separate from project-file order.
Team or user guidance seems to override project guidance
Check the documented category relationship: Team Rules are listed above Project Rules, and Project Rules above User Rules. That category precedence is separate from the unresolved order among project files. If the conflict is between categories, investigate the higher-level rule; if it is between project files, the public documentation does not define a universal winner.
Practical decision guide
| Your requirement | Prefer | Reason |
|---|---|---|
| One short policy for the whole repository | Root AGENTS.md or root CLAUDE.md |
Plain Markdown is easy to review and the documented root files are applied project-wide. |
| Different rules for different directories | .cursor/rules with Auto Attached modes |
File-pattern conditions provide scoping that a single root Markdown file does not. |
| A rule that must always be present | .cursor/rules set to Always, or one canonical root file |
Avoids relying on agent selection or manual invocation. |
| Compatibility with an existing repository | Keep .cursorrules temporarily, then migrate |
Legacy support exists, but migration is the documented direction. |
| A release-only checklist | Manual Project Rule | It remains available without adding release instructions to every conversation. |
| Optional guidance the agent can choose when relevant | Agent Requested Project Rule | The rule is available without forcing it into every interaction. |
Bottom line on “what Cursor actually reads”
Cursor reads root AGENTS.md and root CLAUDE.md according to its current help and CLI documentation. It still recognizes .cursorrules, but calls it deprecated and recommends migration. It also reads Project Rules in .cursor/rules according to each rule’s configured mode and matching conditions.
What Cursor does not publicly document is a fixed order or conflict winner among AGENTS.md, CLAUDE.md and .cursorrules. Use explicit, non-contradictory instructions and verify the active context in your installed version instead of treating any filename as an automatic override.
Frequently Asked Questions
Does Cursor read AGENTS.md?
Yes. Cursor documents a root-level AGENTS.md as a plain-Markdown project-instruction source. The documented root behavior should not be expanded into an assumption that every nested AGENTS.md is automatically merged in every version.
Does Cursor read CLAUDE.md?
Yes. Cursor’s help page says CLAUDE.md is read the same way as AGENTS.md and applied to every conversation; the CLI guide also lists root CLAUDE.md when present. That describes application, not priority over another project file.
Is .cursorrules still supported?
Yes, but Cursor labels it legacy and deprecated. The recommended replacement is a Project Rule in .cursor/rules configured as Always Apply to approximate its former always-on behavior.
In what order does Cursor read these files?
The reviewed official documentation does not publish a deterministic order among AGENTS.md, CLAUDE.md and .cursorrules, nor does it name a universal conflict winner. Do not infer order from filenames or from the Team Rules > Project Rules > User Rules category statement.
Are all files in .cursor/rules active all the time?
No. Each Project Rule can be Always, Auto Attached, Agent Requested or Manual. Auto Attached rules depend on matching patterns, Agent Requested rules can be selected by the agent, and Manual rules require explicit invocation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsHow can I make conflicting instructions predictable?
Keep one canonical policy, migrate useful legacy content into an Always Project Rule when appropriate, remove contradictory copies, and inspect the active rules or context view in your installed Cursor version. This is a configuration practice, not an official filename-precedence rule.
The Bottom Line
Cursor recognizes root AGENTS.md and CLAUDE.md, still supports legacy .cursorrules, and applies .cursor/rules according to each rule’s mode and conditions. Official documentation does not define a fixed order or conflict winner among the three named files, so use one authoritative policy and verify the active context in your installed version.
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.
