AGENTS.md, Project Rules, User Rules or Team Rules: Which Do You Need?
Use AGENTS.md for simple instructions in plain markdown, project rules in .cursor/rules when you need control over when they load, user rules for personal preferences across all projects, and team rules to set standards across an organization. Cursor merges them, and when they conflict, the order is Team, then Project, then User.
# AGENTS.md ## Commands - [build command] - [test command, and how to run a single file] ## Conventions - [convention the agent gets wrong without being told] - See [path to example file] for the standard structure ## Don't - Edit [generated folder] --- For a personal rule, paste into Customize > Rules: --- Reply in a concise style. Avoid unnecessary repetition.
- User RulesCustomize, your account
- Project Rules.cursor/rules, in Git
- Team Rulesdashboard, can be enforced
Try it now
- 1Create
AGENTS.mdin your project root, using the template above with your real commands. - 2Open Customize in the sidebar and click **Rules**. Add one personal preference, and look at the list to see which rules are active.
- 3Start a new chat and ask "Which instructions are you following for this project?" It worked if it reflects both.
Use it when
Start with AGENTS.md if you just need a short list of commands and conventions. Move to .cursor/rules once you want rules that load only for certain files. Add user rules for how you like answers, such as being concise. Use team rules if you're on a Team or Enterprise plan and have org-wide standards.
Skip it when
Don't put team conventions in your user rules, since nobody else gets them and your output will differ from theirs. And don't use any of these as your only security control. Cursor's docs warn that AI guidance shouldn't be the only control you rely on.
Why it works
They differ in where they're stored and who they reach. AGENTS.md has no frontmatter, so it can't be scoped by file pattern, but it can be nested: a file in a subfolder applies when working there, combines with its parent directories, and the more specific one wins. Project rules travel with the repo through Git. User rules set in Customize sync through your account. Team rules live on Cursor's servers, sync to all members, and can be enforced so people can't turn them off.
Example
Say a monorepo has apps/web and services/billing. The root AGENTS.md lists shared commands. services/billing/AGENTS.md adds "All money values are integers in cents", which applies when the agent is working in that folder. Your user rule asks for short replies. Your security team enforces a rule across all repos, which you can't turn off. If your user rule contradicted it, the team rule would win.
Going further
There are two kinds of user rule. Rules set in Customize sync to your account. Files in ~/.cursor/rules (%USERPROFILE%\.cursor\rules on Windows) stay on that one machine. Neither user nor team rules are included in profile exports. For Cloud Agents, Cursor's docs say they read user rules, team rules and repo .cursor/rules/*.mdc files. Team rules without a glob apply to every conversation. Cursor also reads a CLAUDE.md file the way it reads AGENTS.md, and its help says that file always applies to every conversation, so a long one costs context in every chat.
Common mistakes
- Assuming
AGENTS.mdcan be scoped withglobs. It's plain markdown with no metadata, so use subfolders or project rules. - Writing a rule in a personal file and wondering why teammates' agents ignore it.
- Creating local rule files in
~/.cursor/rulesand expecting them on your laptop too. - Trying to turn off a team rule that an admin has marked as Enforce this rule.
Sources
Checked 6 November 2026. Products change often, so confirm details with the vendor.