How to write Cursor rules in .cursor/rules without wasting tokens

Cursor rules save you from re-explaining your stack, project layout and prohibitions to the agent in every chat. You write a rule once and it lands in the model's context automatically. But everything that lands in the context costs tokens. Below is the current rule format from the official Cursor docs (the Rules page), examples, and tips for keeping rules compact.

Kinds of rules in Cursor

• Project Rules — .mdc files in the project's .cursor/rules folder. Version-controlled and scoped to that project.
• User Rules — personal rules for all projects, set in Customize → Rules.
• Team Rules — team-wide rules from the dashboard, available on Team and Enterprise plans.
• AGENTS.md — a plain Markdown file in the project root or subdirectories; an alternative to .cursor/rules with no metadata.

Precedence when rules conflict: Team Rules, then Project Rules, then User Rules.

Rule file format

Each project rule is a separate file with the .mdc extension in .cursor/rules/ (subfolders are fine). A plain .md file in that folder is ignored because it has no metadata. A file has frontmatter fields followed by the rule text.

The frontmatter controls when a rule is included:

In the UI these modes are called Always Apply, Apply to Specific Files, Apply Intelligently and Apply Manually.

Rule examples

A general rule that always applies. Keep it short:

---
alwaysApply: true
---

- Python 3.12, FastAPI, SQLAlchemy 2.x, PostgreSQL
- Run `make test` before proposing a commit
- Never edit files in `migrations/versions/` by hand; use `alembic revision --autogenerate`
- Ask before adding a new dependency

A rule for specific files:

---
globs: app/api/**/*.py
alwaysApply: false
---

- Each router lives in its own module under `app/api/`
- Validate input with Pydantic models, never accept raw dicts
- Return errors as `{"code": ..., "message": ...}`
- See @app/api/users.py for the reference structure

A rule the agent pulls in based on its description:

---
description: Database migration conventions for Alembic
alwaysApply: false
---

- Every migration must have both upgrade and downgrade
- Never change a column type in place: add a column, backfill, drop the old one

@filename lets a rule point to a reference file. That beats copying code into the rule, because the reference doesn't go stale.

Create a rule with /create-rule in the agent chat (the agent writes the file with frontmatter for you) or via Customize → Rules → Add Rule.

A bad example

---
alwaysApply: true
---

You should write really good, clean, well-designed code that follows best
practices. Think about edge cases, performance and security. Use good names.
Add comments where needed. Refactor if something seems messy.

What's wrong with it:

• there's not a single fact about the project; the agent already tries to write good code;
• alwaysApply: true sends these lines with every chat;
• nothing in it can be checked, so you can't tell whether the agent broke the rule.

Cursor's docs give similar advice: keep rules under 500 lines, split large rules into several, give concrete examples or file references, don't copy whole style guides (that's what a linter is for), and don't document commands the agent already knows (npm, git, pytest). Add a rule when you see the agent repeat the same mistake.

Rules and token spend

An applied rule is inserted at the start of the model's context. So an alwaysApply: true rule is paid for in every request, while rules with globs or description cost tokens only when they're needed.

A worked example. Your alwaysApply: true rules take 1,500 tokens and the agent makes 300 requests in a day. That's 1,500 × 300 = 450,000 input tokens, or 0.45 × $0.3 = $0.135 at Zukko's price for Claude Sonnet 5 or GPT-5.6 Sol ($0.3 per 1M input). Cut the always-on part to 500 tokens, move the rest to globs, and that line item drops to a third. A caveat about caching: vendors charge about 10% of the input price for prompt-cache reads, while Zukko bills cached tokens at the normal input price. So for repeated blocks the real gap versus official pricing is smaller than a straight price comparison suggests.

You can measure a rule in tokens with the count_tokens↗ endpoint:

jq -n --rawfile t .cursor/rules/general.mdc '{model: "claude-sonnet-5", messages: [{role: "user", content: $t}]}' |
curl -s https://api.zukko.pro/v1/messages/count_tokens \
  -H "Authorization: Bearer fetch_your_key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @-

The response contains input_tokens. Tokenizers differ between models, so treat it as an estimate.

Connecting Cursor to Zukko

In Cursor's model settings, enable Override OpenAI Base URL and enter:

• Base URL: https://api.zukko.pro/v1;
• API Key: your fetch_... key from the Zukko dashboard↗;
• model: a Zukko alias for Cursor — cursor-sonnet-5 (Claude Sonnet 5), cursor-gpt-sol (GPT-5.6 Sol) or cursor-opus-55 (Claude Opus 5.5).

The detailed guide with a connection check is in the Zukko Cursor docs↗. For the current model list, call GET https://api.zukko.pro/v1/models or open the Models page in your dashboard. Rules work the same whichever model you pick. To see which model follows your rules better, try a few of your own tasks.

FAQ

Why isn't my rule being applied?

Check the rule type. Apply Intelligently needs a description; Apply to Specific Files needs a globs pattern that matches files in context. Also make sure the file extension is .mdc.

Can a rule reference another file?

Yes: @filename in the rule text adds that file to the context. You can also apply a rule manually by @-mentioning it in chat.

Do rules affect Tab autocomplete?

No. Rules don't apply to Cursor Tab or any feature other than the agent. User Rules don't apply to Inline Edit (Cmd/Ctrl+K) either.

Should I use .cursor/rules or AGENTS.md?

AGENTS.md is simpler: plain Markdown with no metadata, and other agents (Codex, Aider and others) read it too. Use .cursor/rules when a rule should apply only to certain files or be pulled in by description.