Cursor Rules are files .mdclocated in the .cursor/rules/project directory. Each file contains two parts: a YAML frontmatter (which controls when the rule is triggered) and Markdown content (the actual instructions for the AI). When properly configured, the AI in Cursor automatically reads and follows the rules in the file without needing you to repeat them each time.
What are Cursor Rules and why do we need to use them?
- Each Chat or Composer session in Cursor starts completely from scratch – the AI doesn't remember you used TypeScript strict mode, doesn't remember the naming conventions in the project, and doesn't remember you told it "never use
anytype". As a result, you have to repeat the same context in every session, like instructing a new employee every morning. - Cursor Rules solves that problem: you write the rules, coding conventions, and project context once, save them to a file
.mdc, and Cursor AI will automatically read and follow them in every subsequent session—without you having to remind you. - Unlike the
.cursorrulesold system (a single file applied to everything), the.cursor/rules/new system allows the creation of multiple rule files with different application scopes: one rule applying only to TypeScript files, another only to test files, and yet another only when the AI proactively requests it. This is a core strength compared to the one-file-for-all approach.
Step-by-step guide: Creating and using Cursor Rules Files
Step 1: Open the project in Cursor
Launch the Cursor application on your computer, then click the Open project button (or File > Open Folder) to start working on a project.
Step 2: Choose your working directory.
Navigate to the folder containing your project (in the example image, it's the folder Test-QTM) and click the Select Folder button to have Cursor load the configuration and index the codebase.
Step 3: Activate the configuration folder creation.
In the project directory tree on the right (or left, depending on the interface), click the New Folder. icon in the root directory.
Step 4: Name the system folder..cursor
Enter the folder name .cursorand press Enter. Then, right-click on the .cursornewly created folder to create a subfolder inside and name it rules.
.mdcStep 5: Create a new rule file
rulesRight-click on the newly created folder , select New File. , and enter the file name followed by the required file extension .mdc(e.g., base.mdc).
Step 6: Customize the rule application mode (Scope)
When the file .mdcopens, Cursor will display a visual configuration UI. You click the dropdown menu in the upper left corner to select the desired mode (for example, select Always Apply so the rule always works in all chat sessions, or Apply to Specific Files if you only want to apply it to certain file formats).
Advanced tip: Instruct the AI to automatically generate files..mdc
In addition to manual creation, starting from version v2026, you can utilize the Agent mode in the Composer framework to create your own automated rules:
Step 7: Use commands /create-rulein Composer
Press the key combination Cmd + I(or on Windows) to open the ComposerCtrl + I window . Switch the mode to Agent in the bottom corner, type the character , and select a command from the system menu.//create-rule
Step 8: Write a prompt describing the desired coding standard.
Enter the prompt describing the standards you want the AI to adhere to in Vietnamese or English (for example: Request the AI to respond in Vietnamese, apply SOLID principles, catch errors using try/catch.). Then press the Send arrow button (Arrow icon) for the agent to start analyzing and automatically writing the configuration code.
Step 9: Check the AI-generated configuration and save it.
The AI Agent will automatically generate a new rule file if your existing rule file is incomplete (e.g., express-standards.mdc) and is located in the correct folder .cursor/rules/containing the YAML Frontmatter configuration for trigger mode and Markdown formatting. Simply double-check the items and click Keep File to apply.
Practical example: Template Cursor Rules for a popular project
Basic rule (base.mdc) - applies all the time:
--- description: "Quy tắc chung cho dự án Next.js TypeScript" alwaysApply: true --- Bạn đang làm việc trong dự án Next.js 15 với TypeScript strict mode. - Dùng async/await, không dùng .then() - Tất cả component là Server Component theo mặc định - Ưu tiên named export thay vì default export - Luôn có error handling cho mọi async operation
Rule TypeScript (typescript.mdc) - automatically activated when working with .ts/.tsx files:
--- description: "Quy chuẩn TypeScript nghiêm ngặt" globs: ["**/*.ts", "**/*.tsx"] alwaysApply: false --- - Không dùng kiểu `any` trong bất kỳ trường hợp nào - Tất cả function export phải có kiểu trả về rõ ràng - Dùng `interface` cho object shapes, `type` cho union types - Bật strict null checks
Common errors and how to fix them.
The rule isn't working even after creating the file: The most common cause is an invalid YAML frontmatter – missing ---closing braces, YAML syntax errors, or spaces/strange characters before the ---first brace. Try setting a temporary version alwaysApply: trueto test if the rule content works – if it does, the problem lies with the glob pattern or the triggering condition.
Agent mode ignores rule: Old files .cursorrulesin the root directory are automatically ignored by Cursor Agent mode starting from 2026. Please change the format .cursor/rules/*.mdcso that the rule works with Chat, Composer, and Agent.
The "Always Apply" rule slows down responses: Each token in the rule alwaysApply: trueis included in every request. If the rule is too long (over 200 words), you're wasting context window. Solution: trim the content, or move unnecessary parts of every request to "Auto Attached" or "Agent Requested".
The structure of the .mdc file: YAML frontmatter and rule content.
Each file .mdchas two distinct parts:
Part 1 - YAML Frontmatter (Behavioral Control):
--- description: "Quy tắc TypeScript cho dự án này" globs: ["**/*.ts", "**/*.tsx"] alwaysApply: false ---
Part 2 - Markdown Content (Practical Guide for AI):
# Quy chuẩn TypeScript - Luôn dùng strict mode (tsconfig strict: true) - Ưu tiên interface thay vì type alias cho object shapes - Không dùng kiểu `any` trong bất kỳ trường hợp nào - Tất cả function phải có kiểu trả về rõ ràng
Fields in the YAML frontmatter:
description- Briefly describe what this rule does. This is required if you want the AI to decide whether or not to use this rule (Agent Requested mode).globs- A list of pattern files to which this rule applies. For example,["**/*.ts"]it only applies when working with TypeScript files.alwaysApply- If it's `true`true, the rule is added to the context of all Chat and Composer sessions, regardless of which file is open. If it's `false`false, the rule only triggers under different conditions.
Summary of the 4 activation modes of Cursor Rules
This is the most important and often misunderstood part. How the rule is triggered depends entirely on the combination of frontmatter fields:
- 1. Always Apply
alwaysApply: true- This rule is included in the context of every AI request, regardless of what it's doing. Use it for core project conventions. Note: each token in this type of rule is loaded into every request, so keep rules under 200 words to avoid wasting context window space. - 2. Auto Attached
alwaysApply: false+globs: ["**/*.ts"]- The rule is automatically triggered when a file is open and matches the glob pattern. No further action is required. Suitable for language-specific or directory-specific rules. - 3. Agent Requested (AI proactively requests)
alwaysApply: false+description: "."(no globs) - The AI reads the description and decides whether to use this rule based on the current context. Suitable for special rules where the AI knows when to use them. - 4. Manual - No
alwaysApply, noglobs, nodescription- The rule is only triggered when you actively call it by name using the syntax@tên-rulein Chat or Composer.
Old .cursorrules vs. new .cursor/rules: Which one should you use?
- File
.cursorrules(old format): a single Markdown file in the root directory, no frontmatter, applies to everything in every session. Advantages: simple, easy to set up. Disadvantages: no scope control, completely ignored by Agent mode from 2026 onwards, cannot be disabled for individual file types. .cursor/rules/*.mdc(New format, recommended 2026): Multiple files, each with its own scope, works with Chat, Composer, and Agent modes. Slightly more complex to set up initially, but much more flexible and efficient in the long run.- Conclusion: If you are using an agentic workflow or plan to use one in the future, switch to the old format
.mdcnow. If you only use basic chat and don't need scope control,.cursorrulesthe old format will still work but long-term support is not guaranteed.
Frequently Asked Questions (FAQ)
Do Cursor Rules affect the autocomplete (Tab) feature?
- Rules only affect Chat and Composer. Cursor Tab autocomplete and Inline Edit (Cmd/Ctrl+K) do not read rules.
Is it possible to commit the .cursor/rules/ file to Git so the whole team can share it?
- Absolutely, this is the design purpose of this system - the rules
.cursor/rules/are committed to the repository to ensure the entire team uses the same AI context. If there are personal rules you don't want to share, add that file to the repository.gitignore.
How many rule files are appropriate?
- In practice, 5-8 files are optimal for most projects: one always-on rule for basic operations, 3-4 auto-attached rules by file type, and 1-2 manual rules for special tasks. More than 10 rules usually indicate the possibility of merging several files.
Can Cursor create its own rule files?
- You can request Cursor Agent to create a rule file for you by describing what you want. Cursor will generate a file
.mdcwith the appropriate frontmatter and content in the . directory.cursor/rules/.