Does Cursor read AGENTS.md? What loads, when, and why nested rules disappear

Cursor applies a root AGENTS.md — a plain Markdown file of standing instructions such as build commands and conventions — to every agent chat, and attaches a nested copy when the agent reads a file in that folder, or, in the CLI since v2026.10.22, edits or creates one.

The catch is delivery. A nested AGENTS.md is not loaded when the chat starts. Cursor attaches it when the agent reads a file in that folder, attaches it once per conversation, and can lose it when the conversation is summarized. On a current build, the root file stays. That difference explains most "Cursor ignores my AGENTS.md" reports, and the stranger one where the root rules hold but a package's rules vanish halfway through a long task.

Cursor reads CLAUDE.md through the same door. In the editor, a project CLAUDE.md is applied to every chat, and Cursor's Help page says it reads CLAUDE.md files the same way as AGENTS.md. You do not need an adapter for Cursor. If you keep one instruction file for several agents, the guide to one AGENTS.md for every coding agent covers the adapters the other tools need.

Run Cursor → About Cursor in the editor or agent --version in the CLI before comparing notes with a forum thread. Nested AGENTS.md delivery changed in CLI v2026.10.22, when editing or creating a file started attaching that folder's copy; the staff reply below answers an editor report from 3.24.18, and Cursor 3.27 was the newest release on the release-notes page when checked on 27 October 2026.

Checked against Cursor's documentation on 27 October 2026.

Status, 27 October 2026: the hierarchy is documented; the exact trigger for nested files is not. A Cursor staff reply in the nested AGENTS.md thread (19 October 2026) confirmed that nested AGENTS.md and file-scoped .cursor/rules attach to a Read tool result, once per conversation, and can drop out of context after summarization without being reattached. The CLI changelog for v2026.10.22 says nested AGENTS.md now also apply when the agent edits or creates a file. No release note says the post-summary loss is fixed.

What Cursor reads, and where#

The table is the model the docs and Cursor staff describe. The important row is the second: "when the agent works with files in that directory" is not the same as "at the start of every chat."

There is no documented user-level AGENTS.md. For a rule that should apply in every project, use User Rules in Customize → Rules; they sync with your Cursor account.

Surfaces differ. The CLI page names the project-root files; the nested trigger described above is the build-dependent part. Cloud agents read AGENTS.md, and the Cloud setup page recommends a Cloud-specific section. The docs reviewed here do not describe a separate AGENTS.md loader for the Agents Window. A rule that works in the editor is evidence for the editor, not for every surface.

Root rules stay; nested rules arrive with a file read#

Cursor's docs say rule contents are included at the start of the model context. The root AGENTS.md behaves like that: Cursor staff describe it as living in the system prompt, and it survives summarization.

Nested files are different. On 3.24.18, when the agent used the Read tool on a file, Cursor appended every not-yet-attached AGENTS.md from the workspace root down to that file's directory, in one block. The block told the agent the files were relevant to the file it had just read and to consider them. That was the only trigger: cat or ls through the shell, Grep, Glob, creating a file, and editing a file did not attach the nested file.

The CLI changelog for v2026.10.22 says edits and creates now attach nested files in the CLI. The editor release notes for 3.27 do not mention the same change. Test the trigger on your build instead of assuming either list.

Two consequences:

• An agent that explores with shell commands or edits a package without reading a file there may never receive that package's AGENTS.md on the older behaviour. Tell it to read a file in the folder, or @ the file.
• The attachment is part of the chat history, so it is summarized like any other tool result.

The docs say nested files are combined with parent directories, with more specific instructions taking precedence. That is the intended composition. It only helps once the nested file is attached; before that, the model has the parent and not the child.

Why nested rules disappear#

A nested file can go missing in two ways.

The first is that it was never attached. On the 3.24 behaviour, the agent reached the package through a shell command, a search, or an edit, not a Read, so the rule never entered the conversation. The model never saw the file, so the rule cannot apply.

The second is summarization. Summarization, also called compaction, replaces older turns and tool results with a summary when the chat outgrows the context window, the amount of text the model can hold at once. The visible transcript does not change; the model's view does.

After summarization, the attached AGENTS.md text can drop out of the model's view. Cursor does not reattach it on later reads in the same directory, so the rest of the conversation runs with the root file and whatever the summary kept. The earlier tool call is still in the transcript, which is why the chat looks like it has the rules.

Root always-applied rules survive because they live near the system prompt. Nested and file-scoped rules do not, and Cursor does not put them back.

The repair is temporary. After a summary, ask the agent to read the relevant AGENTS.md again, or @-mention it in your next message. A fresh chat resets the once-per-conversation attachment state. For a long task that crosses packages, put the load-bearing rules in the root file or an always-applied .mdc rule, and keep nested files for conventions that matter only in that folder.

The multi-root trap#

A multi-root workspace is one window with several repository folders. In that setup, each folder's root AGENTS.md is applied workspace-wide instead of scoped to its folder. A Cursor staff reply in the multi-root thread (21 August 2026) says this is still current; nested files scope correctly. A chat in the frontend can receive the backend's root instructions.

Open one repository per window, or move the rules into .cursor/rules with globs scoped to that repository. A nested AGENTS.md only scopes to its folder, so moving a repo-wide rule there stops it applying to the rest of the repository; it is not a fix for the leak. Staff have suggested frontmatter globs on the root AGENTS.md as a workaround, but the docs describe AGENTS.md as plain Markdown without metadata and another staff reply (17 May 2026) says it supports no frontmatter. If you try it, test it on your build; the reliable route is the rules folder.

This is not the root file being ignored. It is the opposite: a root file you did not want is being applied.

CLAUDE.md is a second door, not a fallback#

Cursor's Help page says a project CLAUDE.md is always applied, regardless of any alwaysApply frontmatter. It also says Cursor reads CLAUDE.md files the same way as AGENTS.md. It is a second door into the same loader, not a lower-priority file. If both names exist, Cursor can read both; keep one set of instructions, because the docs do not describe a precedence rule between them.

Cursor 3.26 deduplicates CLAUDE.md when it is a symlink, hard link, or identical copy of AGENTS.md; the agent receives the instructions once. On older builds, a symlinked pair could load twice, which a Cursor staff reply in the symlink thread (26 August 2026) describes. A symlink, hard link, or identical copy is safe from double-counting on 3.26 and later, but a stale copy is still a stale copy.

A January 2026 report found CLAUDE.md still loading with the third-party toggle off, on 2.4.21; the report used a symlinked CLAUDE.md. Staff could reproduce it only on the first run after toggling, while the reporter said it persisted. Treat the toggle as unreliable for a symlinked file; for a normal file, test it on your build.

When the root file is the one missing#

Check the build before the file.

• 3.1.15–3.1.17: a regression put the root AGENTS.md in a requestable bucket instead of the always-applied one. Cursor staff said it should be fixed in 3.2, and a reporter confirmed 3.2.11 in the April thread (26 April 2026). Update before rewriting the file.
• 3.7.x worktrees: project rules and skills did not load in a new Agents Window worktree. Staff said it should be fixed in 3.9 (22 June 2026), and the reporter confirmed on 26 June. A worktree is an isolated Git checkout for one task; an old build can run the agent outside the rules you see in the main checkout.
• A plain .md file in .cursor/rules: it is ignored. The rules system needs .mdc, or use AGENTS.md. If you moved a rule there and expected it to load, that is the cause, not the AGENTS.md file.
• The file is above the folder you opened: the docs describe the project root and its subdirectories, not a parent of the folder you opened. If the file is in a parent, open the repository at that level; do not assume Cursor reads it from above.

How to see what reached the model#

Cursor's docs say Customize → Rules shows all rules and their status. If your build lists an AGENTS.md entry, check that it sits with the always-applied rules; the docs do not promise a type label for AGENTS.md. If the file is not listed, use the canary below.

@AGENTS.md in a new chat attaches the file to that message (prompting docs). If the agent follows the rule after the mention but not without it, the content is fine and the automatic path is the problem.

For a nested file, use a canary (a unique marker you plant to see whether it reaches the model). Put a unique line in the file, such as CANARY: pkg-7f3a, and a sentence: "Before your first edit in this folder, run echo pkg-canary." In a new chat, ask the agent to read a file in that folder with the Read tool, then make an edit. Watch the terminal or the reply. Then run /summarize in the CLI (aliases /compact and /compress), or wait for automatic summarization in the editor, and repeat. A canary is a test of what reached the model, not proof of what the loader did: a model can miss a line it was given, and a model can repeat a line it saw earlier.

Do not ask "which files do you see?" A model sees a prompt, not the loader; it will give a plausible answer whether the file loaded or not.

When the text is in the prompt but the rule still loses#

Once the mention or the canary shows the text is in the prompt, the remaining problem is adherence, not loading. A rule is context, not a filter. Long chats, conflicting root and nested instructions, and negative rules are the usual reasons a model does otherwise. The Cursor rules guide covers the enforcement ladder; for a hard boundary, use a hook (a script Cursor runs at a tool or session event), a CLI deny rule, or a team policy, not stronger prose. The context compaction guide covers what a summary keeps.

Where to go next#

• Cursor guides — the rest of the set.
• Why your Cursor rule isn't applied — .cursor/rules, User Rules, and the loaded-but-not-followed ladder.
• One AGENTS.md for every coding agent — sharing the file with Claude Code, Codex, and the rest.
• Context compaction — what a summary keeps.