TopolearnInstructions come from several places; knowing the layers avoids conflicting guidance and duplicated files.
Project rules are one of four instruction sources:
- User Rules: your personal preferences for every project, set in Customize > Rules. For example "explain trade-offs briefly before large changes" or "I use pnpm". They apply to Agent chats; they are not applied to Inline Edit.
- Team Rules: managed by admins from the Cursor dashboard on Team and Enterprise plans. An admin can enforce a rule, so members can't switch it off; non-enforced team rules can be toggled by each user. Team rules can also use file patterns.
- Project Rules: the
.cursor/rules/*.mdcfiles from the previous lesson. - AGENTS.md: a plain markdown file with no frontmatter, in the project root and optionally in subfolders. Nested files combine with their parents, and the more specific one wins on conflicts. Other coding agents read
AGENTS.mdtoo, so it is a good choice for a repository used with several AI tools.
When several apply, they are merged, and on conflicts earlier sources in this order win: Team Rules, then Project Rules, then User Rules.
Practical layering:
- Personal style and workflow preferences: User Rules.
- Company-wide must-follow guidance (security, licensing headers): enforced Team Rules.
- Repository conventions: Project Rules for scoped, conditional rules; AGENTS.md if you want one simple file shared with other tools.
- Avoid saying the same thing in several places; when guidance drifts apart, the agent may follow either version.
Review rules like code. When the agent keeps ignoring one, the cause is often too many rules, a vague wording or a conflict with another layer.
Example
# AGENTS.md (repo root; plain markdown, no frontmatter)
## Setup
- Install with `pnpm install`; Node version is in .nvmrc.
## Commands
- Tests: `pnpm test`; single file: `pnpm vitest run <path>`
- Lint + types before finishing: `pnpm lint && pnpm tsc --noEmit`
## Conventions
- Never edit files under src/generated/ (run `pnpm codegen` instead).
- Commit messages: Conventional Commits (feat:, fix:, chore:).
# packages/billing/AGENTS.md adds billing-specific notes;
# it combines with this file and wins on conflicts.Remember
- User Rules (personal), Team Rules (admin, can be enforced), Project Rules, AGENTS.md
- Precedence on conflicts: Team, then Project, then User
- AGENTS.md is plain markdown, supports nested files and is shared with other agents
Watch out for
- Writing the same rule with different wording in User Rules, project rules and AGENTS.md, so they drift and conflict.