
The Ultimate .cursorrules Guide: Modular System Prompts for AI Coding Agents
Cursor project rules without invented token-saving benchmarks
Project rules are reusable instructions for code edits, review and repository conventions. They cannot guarantee hallucination-free results, prohibit destructive commands by themselves, or prove a fixed percentage reduction in model context usage.
Corrected November 12, 2026: The earlier article described hypothetical token counts as measured savings (including 65.5% and 66.8%) and promised that installing a prompt would eliminate coding errors. No tokenizer trace, execution log or controlled experiment supported those figures. This version replaces them with inspectable file templates and tests.
The original legacy title retains the older .cursorrules terminology for the existing URL, but the current recommended configuration described here uses modern MDC project rules. The official Cursor rules reference documents where project rules live, their metadata and how they are applied.
1. Rule file structure and modes
The Cursor documentation says project rules are stored as .mdc files under .cursor/rules/. A plain .md file placed inside that directory is not processed as a project rule by that mechanism; the documentation offers AGENTS.md as a plain-Markdown alternative.
Current documented rule application modes include:
| Mode | Description | Limitation |
|---|---|---|
| Always Apply | Include in every agent session | Keep it short and genuinely universal |
| Apply Intelligently | Agent decides from description | Relevance does not guarantee application |
| Apply to Specific Files | Match configured glob patterns | Verify actual file paths |
| Apply Manually | User invokes a rule explicitly | Not active for every unrelated task |
These modes are described by the same current official rules page. Do not assume older tutorials or other coding tools implement exactly the same behavior.
2. Scoped TypeScript and React rule example
This is a site-authored proposal, not an official Cursor example or a tested production configuration. It uses a simple single-extension path glob; add a separately verified rule for .ts files if needed:
---
description: TypeScript and React conventions
globs: "src/**/*.tsx"
alwaysApply: false
---
# TypeScript conventions
- Check package.json and tsconfig.json before changing dependencies.
- Preserve existing exported APIs unless the user requests a migration.
- Prefer types with documented constraints over unexplained any.
- Update focused tests for affected behavior.
- Never report tests as passing unless they ran.
- Ask before network operations, destructive commands or deployment.
Store under .cursor/rules/typescript.mdc. These are prompt instructions, not tool authorization or filesystem protection.
3. Scoped Python rule example
---
description: Python maintenance and test boundaries
globs: "**/*.py"
alwaysApply: false
---
# Python conventions
- Inspect pyproject.toml and supported interpreter versions.
- Preserve caller-visible interfaces and existing error handling.
- Add bounded tests for changed behavior where practical.
- Never invent installed packages or claim tests ran without logs.
- Do not read secrets or start new services without approval.
Store under .cursor/rules/python.mdc. This is not proof that the IDE applies it to every Python task. Check active rules in the installed release.
4. Short always-applied review rule
---
description: Evidence and safety for repository changes
alwaysApply: true
---
- Identify files actually changed and the tools actually executed.
- Separate measured results from suggestions.
- Ask before destructive changes or revealing credentials.
- Report failures instead of inventing clean CI or test output.
Prompts alone cannot provide a security boundary. Enforce permissions, sandboxing, tool scopes and human approval separately.
5. How to verify usefulness
There is no evidence supporting the old claim that moving rules automatically saves 66.8% of context tokens. To evaluate a change in a reproducible way:
- Record Cursor version, model, repository commit, rule files and task text.
- Use representative TypeScript and Python file edits to check whether the intended rules are selected.
- Save an observable rule-activation indicator if the installed IDE exposes one; do not guess inclusion from the model response.
- Repeat the same tests and lint checks on reviewed changes.
- Measure actual prompt-token counts only if a supported counter exists, otherwise report context savings as unmeasured.
- Verify code correctness and unwanted mutations independently of model self-reporting.
The Python unittest documentation describes a test runner for Python code; simply asking an agent to run a test does not demonstrate that the test ran or passed.
Related reading: MCP server basics and Linux agent sandbox boundaries. Those separate articles still need their own factual review.
References
- Cursor official project rules, MDC files, frontmatter and application modes
- Python unittest test execution reference
Source-reviewed November 12, 2026. No real Cursor session, token-usage comparison or measured improvement was claimed.