The four rule layers

Cursor assembles its standing instructions from four separate sources (as of October 2026; Cursor’s rules documentation). They’re additive - none cancels another; they stack into the brief the agent works from - standing context, what the agent reads before you type a word. And the stack is not unstructured when guidance conflicts: per the docs, “Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts” - so a personal User Rule does not stand equally against a conflicting org Team Rule. (The doc’s stated order covers Team, Project, and User Rules; it gives no position for AGENTS.md in that order.)

• Project Rules - .cursor/rules/*.mdc, version-controlled and repo-scoped. This is Cursor’s native format, and the only layer with the frontmatter that controls when a rule attaches. The bulk of the conventions in budgetcli - the course’s illustrative personal-finance API - live here.
• User Rules - global to you, edited from Customize → Rules (the current docs’ label for the sidebar section). No local file; they apply to every chat in every project on your machine. This is the home for personal working style (“always show me a diff before editing”), not facts about a specific repo.
• Team Rules - managed centrally from the Cursor dashboard and pushed to every member with no local file. These are plan-gated: per Cursor’s docs, “Team and Enterprise plans can create and enforce rules across their entire organization.”
• AGENTS.md - plain Markdown at the project root, the cross-tool path. Cursor reads AGENTS.md natively - the same file Codex and OpenCode read, so a rule you write here travels with the repo to a teammate on a different tool, unchanged. Nesting is supported: per the docs, “You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children” - nested instructions are combined with the parent directory’s, “with more specific instructions taking precedence” (as of October 2026). Use .cursor/rules/*.mdc globs when you want subtree scoping with frontmatter control over when the rule attaches.

Stacked by scope - organization, person, repository - the four layers look like this (both repo-scoped layers sit at the bottom; this is a scope map, not a precedence ladder, and their order in the map carries no meaning):

 broadest scope
   ┌─ Team Rules ────────  pushed from the dashboard, org-wide (plan-gated)
   ├─ User Rules ────────  Customize → Rules, you on every project
   ├─ Project Rules ─────  .cursor/rules/*.mdc, conditional and repo-scoped
   └─ AGENTS.md ─────────  plain Markdown at the root, portable across tools
 narrowest scope

additive - all four join the brief; none cancels another,
and when guidance conflicts, earlier sources take precedence
(Team Rules → Project Rules → User Rules, per the docs)

Two of these are the ones you’ll touch constantly: .cursor/rules/*.mdc for Cursor-specific power, and AGENTS.md for portable simplicity. Cursor’s docs frame AGENTS.md as a “simple alternative to .cursor/rules” - for “simple, readable instructions without the overhead of structured rules” - and present both formats as options - AGENTS.md for portable simplicity, .cursor/rules/ when you want structured, conditional control.

Take the portable layer first. It has the least to learn and the widest reach - one plain-Markdown file that stays in force no matter which tool clones the repo next. Next: AGENTS.md, the portable path.