Skip to content
agents.cli

The four rule layers

Cursor assembles its standing instructions from four separate sources. They’re additive - none cancels another; they stack into the brief the agent works from.

  • 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 budgetcli’s conventions live here.
  • User Rules - global to you, edited from Cursor Settings → Rules. 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. Treat nested-file behavior as version-sensitive; use .cursor/rules/*.mdc globs when you need explicit subtree scoping and verify the installed version.

Stacked broadest to most specific, the four layers look like this:

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


additive - all four join the brief; none cancels another,
and a matching, more specific Project Rule can refine a broad instruction

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 coexisting options in the same repo, AGENTS.md for portable simplicity and .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.