TopolearnRules stop you repeating the same instructions in every chat and keep the agent consistent with how your team works.
The agent starts each chat knowing nothing about your conventions. Project rules fix that: markdown files the agent reads, stored in .cursor/rules/ and committed with your code so the whole team shares them. You can organize them in subfolders, and create one with /create-rule in chat or from the Customize screen.
Project rule files use the `.mdc` extension and start with frontmatter (a small settings block between --- lines). A plain .md file in that folder is ignored because it has no frontmatter. Three fields decide when a rule applies:
alwaysApply: true: included in every chat.globs: src/components/**/*.tsx(file patterns): attached when matching files are in context.descriptiononly: the agent reads the description and decides whether the rule is relevant.- none of these: applied only when you @-mention the rule.
What to write: build and test commands, architecture decisions ("handlers return Result, never throw"), naming and file layout conventions, things the agent keeps getting wrong. Keep each rule focused and under about 500 lines; split big ones into smaller composable rules. Reference files with @ instead of pasting their content, so rules don't go stale.
Rules are instructions to the model, not enforcement: it usually follows them, but nothing guarantees it. They steer Agent; they are not applied to Tab. For guaranteed behavior use hooks or run-mode settings (later lessons).
Example
---
description: Conventions for React components in the web app
globs: src/components/**/*.tsx
alwaysApply: false
---
- Function components with named exports; no default exports.
- Props type is `<Name>Props`, declared above the component.
- Styling via Tailwind classes only; no inline style objects.
- Data fetching goes through hooks in src/hooks/, never fetch() in components.
- New components need a test next to them: <Name>.test.tsx (Vitest + RTL).
- Example to follow: @src/components/UserCard.tsx
# saved as .cursor/rules/react-components.mdcRemember
- Project rules live in .cursor/rules as .mdc files with frontmatter
- alwaysApply, globs or description decide when a rule is used; otherwise @-mention it
- Keep rules short and focused; they guide the model but don't enforce
Watch out for
- Saving a rule as .md in .cursor/rules and wondering why it never applies; project rules need .mdc with frontmatter.