In a Cursor monorepo, how do you give the `payments/` folder its own Agent instructions, and how do they combine with the root ones?
answer
- a plain file per directory
- combined with parents, not replacing them
- the more specific wins a conflict
- or a rule scoped by pattern
- loads when that folder's files are in play
basics
~20 sAdd payments/AGENTS.md: Cursor applies nested AGENTS.md files when Agent works on files in that folder, combined with the root AGENTS.md, the more specific winning on conflicts. Or write a .cursor/rules project rule with globs: payments/** and alwaysApply: false.
solid answer
~40 sCursor supports `AGENTS.md` in the project root and in any subdirectory. A `payments/AGENTS.md` is applied automatically when Agent works with files in `payments/` or its children, and its instructions are **combined** with the parent `AGENTS.md` files — nothing is replaced, but where they conflict the more specific file takes precedence. The alternative is a project rule, `.cursor/rules/payments.mdc`, with `globs: payments/**` and `alwaysApply: false`, which is auto-attached when a matching file is in context. Choose `AGENTS.md` for plain readable instructions with no metadata; choose the `.mdc` rule when you want the rule-type controls — several patterns, a description-based or manual rule — and all rules visible in one folder. Either way, keep the root file free of claims the payments file has to contradict.
code
markdown · 6 lines# Payments service
- Amounts are integer minor units; never use floating point
- Every handler is idempotent on the request ID
- Never log card numbers or account numbers
- New endpoints need a contract test under `payments/tests/contract/`go deeper
Remember that Cursor reads AGENTS.md in subfolders as well as at the root, and that a folder's file adds to the root instructions rather than replacing them.
Explain the combine-then-more-specific-wins behaviour, write a glob-scoped .mdc rule as the alternative, and know why a double-star glob reaches nested folders and a single star does not.
Pick one home per convention, keep root instructions free of claims a folder must contradict, and check scoped guidance actually loads when the work touches that folder.
Decide which conventions are local to an owning team, kept beside its code, and which are central or organisation-wide, so ownership of agent instructions follows ownership of the code.
## Two Cursor-native ways to scope instructions In a monorepo the root instructions describe the whole codebase, but one area — here a `payments/` service — has rules of its own: money as integer minor units, idempotent handlers, nothing sensitive in logs. Cursor offers two ways to give Agent those rules only where they matter: 1. **A nested `AGENTS.md`** in `payments/`. 2. **A file-scoped project rule** — an `.mdc` file in `.cursor/rules` whose `globs` point at `payments/`. ## How nested AGENTS.md files combine `AGENTS.md` is Cursor's plain-markdown instruction file: no frontmatter, no metadata, just text. Cursor supports it in the project root **and in subdirectories**: ``` project/ AGENTS.md # applies across the project payments/ AGENTS.md # payments-specific web/ AGENTS.md # web-specific ``` The behaviour Cursor documents: - A nested `AGENTS.md` is **applied automatically when working with files in that directory or its children**. - Its instructions are **combined with those of parent directories** — the root file still applies inside `payments/`. - Where the two disagree, **the more specific instructions take precedence**. So `payments/AGENTS.md` should hold only what is different or extra about payments; repeating the root file there adds nothing but drift. ## A glob-scoped project rule The same instructions can live in `.cursor/rules/payments.mdc`: ```markdown --- globs: payments/** alwaysApply: false --- - Store amounts as integer minor units, never floats - Make every handler idempotent on the request ID ``` With `alwaysApply: false` and a `globs` value, this is an **Apply to Specific Files** rule: it is auto-attached when a matching file is in context. Mind the pattern — `payments/**` covers everything under the folder, while `payments/*` matches a single path segment and misses nested files. ## Writing the payments file Whichever home you choose, the content follows the same discipline: - **Only the difference.** State what is special about payments; the root instructions already arrive. - **Concrete and checkable.** "Amounts are integer minor units" changes Agent's code; "be careful with money" does not. - **Point at canonical code.** Name the file that shows the pattern instead of pasting it, so the instructions do not go stale. - **Owned by the folder's owners.** Changes to `payments/AGENTS.md` go through review like any other change to the service. ## Choosing between them | | Nested `AGENTS.md` | `.mdc` rule with `globs` | | :-- | :-- | :-- | | Format | Plain markdown, no metadata | Markdown under frontmatter | | Lives | Inside the folder it governs | Centrally, in `.cursor/rules` | | Scope | That directory and its children | Any comma-separated set of patterns | | Other modes | None | Can instead be always-on, description-based or manual | | Conflict rule | Combined with parents; more specific wins | Every rule whose conditions match applies | A nested `AGENTS.md` is easy to find for whoever owns the folder and needs no knowledge of frontmatter. A `.mdc` rule wins when the scope is not a single folder (`payments/**, billing/**`), when the guidance should be pulled in by relevance or by mention instead, or when the team wants every rule listed together under **Customize → Rules**. Cursor's documentation does not state an ordering between a nested `AGENTS.md` and a project rule, so do not split one convention across both mechanisms and hope one overrides the other. Pick one home per convention. ## Pitfalls - **Expecting a replacement.** A nested file adds to the root one; if the root says something payments must not do, the root file needs a scoping sentence, or the payments file must state the exception explicitly. - **Same-named rule files.** Cursor identifies rules by full path, so `.cursor/rules/payments/conventions.mdc` and `.cursor/rules/web/conventions.mdc` both apply whenever their conditions match — there is no override by file name. - **Instructions that never load.** Both mechanisms key on payments files being part of the work. A chat that never touches a file under `payments/` has no documented reason to pick up its scoped guidance; @-mention a payments file when you want it in play. - **Organisation-wide policy.** If a rule must hold in every repository, not just this one, that is a Team Rule for the team's admins, not a folder file.
- The root `AGENTS.md` says "log full request bodies at debug level"; `payments/AGENTS.md` says "never log request bodies". What does Agent follow for a payments file?Both files reach Agent, combined; on the conflict, Cursor gives precedence to the more specific instructions, so the payments rule wins inside `payments/`. It is still cleaner to scope the root sentence ("outside payments/") so the two files never disagree in the first place.
- When would you choose `.cursor/rules/payments.mdc` with `globs` over a nested `AGENTS.md`?When the scope is not one folder (`payments/**, billing/**`), when the guidance should be description-based or manual rather than path-based, or when the team wants every rule in one versioned folder with its status visible under Customize → Rules. `AGENTS.md` has no metadata, so it cannot do any of that.
- A nested AGENTS.md replaces the root AGENTS.md inside that folder
- Cursor reads AGENTS.md only at the repository root
- A nested AGENTS.md needs globs frontmatter to scope it to its folder
- The glob payments/* covers every file nested under payments/
- Rule files with the same name in different folders override each other