skip to content

In a Cursor monorepo, how do you give the `payments/` folder its own Agent instructions, and how do they combine with the root ones?

level: middleimportance: should knowfreq 7%

answer

  1. a plain file per directory
  2. combined with parents, not replacing them
  3. the more specific wins a conflict
  4. or a rule scoped by pattern
  5. loads when that folder's files are in play

basics

~20 s

Add 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 s

Cursor 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
markdown
# 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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