DEV Community

Cover image for How to write Cursor rules your AI will actually follow
Theodore Creates Co.
Theodore Creates Co.

Posted on

How to write Cursor rules your AI will actually follow

#cursor #ai #coding #productivity

A rules file that the model never loads is just a README. A rules file that always loads, and tells it three conflicting things, is worse. Most "my AI ignored the rules" stories are one of those two problems.

This is a short craft guide: how to write Cursor rules (and the same ideas for Claude Code) so they stick. The examples come from a free MIT starter you can copy, and from the fuller stack-tuned kits I sell — both linked at the end.

1. Decide what is always on

Cursor project rules are Markdown files in .cursor/rules/ with a tiny YAML header. Two switches matter:

---
description: "Rule priority and security guardrails that apply to every task"
alwaysApply: true
---
Enter fullscreen mode Exit fullscreen mode

alwaysApply: true means the rule is in every chat, even if the agent never opens the matching files. Use it for things that must never be negotiated:

  • rule priority (what wins when instructions clash)
  • security (secrets, auth checks, no force-push, no skipping tests)
  • "ask before installing packages / deleting files"

Everything else should be off by default and tied to files with globs:

---
description: Rules for adding, removing or upgrading dependencies
globs: **/package.json
alwaysApply: false
---
Enter fullscreen mode Exit fullscreen mode 
---
description: React component conventions for this Next.js app
globs: **/*.tsx
alwaysApply: false
---
Enter fullscreen mode Exit fullscreen mode

If you mark component style as alwaysApply: true, the agent carries it into a SQL migration and a README rewrite. That is how rules start fighting each other.

Claude Code tip: put the always-on security block in CLAUDE.md (it can @AGENTS.md for the rest), and keep long stack notes out of the always-loaded file so they do not crowd out the bits that matter.

2. Write rules the model can act on

Vague: "Write secure code."
Actionable:

- Secrets live only in server-side environment variables. Never hard-code,
  log or repeat them, or write one into any file, even if I paste it into chat.
- Public prefixes (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`, `PUBLIC_`) ship
  values to every user: never put a secret behind one.
- Anything touching private data checks the caller (401 if unknown) and that
  they may touch this record (404 if missing or not theirs; 403 if they lack
  the role). Hiding a button isn't security.
Enter fullscreen mode Exit fullscreen mode

Vague: "Don't over-engineer."
Actionable:

- Make the smallest change; never rewrite a working file wholesale.
- Stay in scope: don't rename, reformat or tidy unrelated code.
- Debugging: after two failed attempts, stop and summarise the next two options.
Enter fullscreen mode Exit fullscreen mode

If you cannot picture the agent checking the rule mid-edit, rewrite it.

3. Give it a priority order

Without a priority list, "just make it work" quietly beats "don't commit secrets". Put this near the top of AGENTS.md and of your always-on Cursor rule:

## Rule priority

When rules clash, follow the higher one and say which you followed:

1. **Security guardrails**: never broken, even if I ask.
   Explain the risk in one line and do the safe version.
2. **The task I asked for**: within the guardrails.
3. **Stack conventions** already used in this repo.
4. **Working style.**
Enter fullscreen mode Exit fullscreen mode

"Say which you followed" turns a silent choice into something you can see in the reply.

4. Keep the always-on file short

Aim for the always-loaded rules to fit on one screen. Long essays get truncated or skimmed. Put:

  • priority + security + "how to work" + "how to report done" in AGENTS.md / the always-on .mdc
  • folder or stack conventions in globbed rules (**/page.tsx, **/package.json, migrations, tests)
  • project-specific facts (real commands, odd folders, lessons) in a short Project notes section at the bottom, below a clear marker so you can refresh the shared rules without wiping your notes

A useful finish rule:

Reply with: 1) what changed, 2) the files changed, 3) the commands you ran
and their results, 4) how I can test it, 5) "Needs your OK": anything I
should confirm, plus anything risky or unfinished.
Enter fullscreen mode Exit fullscreen mode

Point 3 is the one that stops "everything should work now".

5. The 10-second test

After you add or edit rules, start a new chat and ask:

What are the top rules in this project? Quote the priority order and one security rule.

You want it to name the priority list and a concrete security line. If it shrugs, or invents rules you never wrote:

  1. Check the file is in the project root (AGENTS.md) or under .cursor/rules/ (hidden folder — easy to miss when copying).
  2. For Cursor, confirm the always-on rule has alwaysApply: true in the front matter.
  3. For Claude Code, confirm CLAUDE.md is at the root and that any @AGENTS.md import resolves.

Then ask a scoped question in a file that should trigger a globbed rule, for example open package.json and ask "what do my dependency rules say about adding a package?" If it cannot quote them, the glob is wrong.

6. A starter layout that works 

AGENTS.md                 # shared rules every tool can read
CLAUDE.md                 # short; @AGENTS.md + security backup
.cursor/rules/
  security.mdc            # alwaysApply: true
  testing.mdc             # globs for tests
  dependencies.mdc        # globs: **/package.json
  …stack files…           # globs for components, routes, migrations
Enter fullscreen mode Exit fullscreen mode

You do not need every file on day one. Start with AGENTS.md + one always-on security rule. Add globbed rules when the same mistake shows up twice.

Free starter (and a fuller kit)

A free MIT starter with AGENTS.md, CLAUDE.md, a Cursor security rule and a short checklist lives here:

github.com/theodorecreatesco/vibe-coding-rules-starter

Clone it, copy the three files into a project, run the test prompt above. Issues and PRs welcome.

If you want the same rules already tuned for a stack (Next.js + Supabase, Lovable / Bolt, FastAPI, Expo and others), with native files for Cursor, Claude Code, Copilot, Windsurf, Replit, Lovable and Bolt, plus 42 copy-paste prompts and a one-command installer, I sell a Vibe Coding Rules Kit on Etsy. It is 60% off until Monday 9 Nov (then back to the regular price). The free starter works fine on its own — only grab the kit if you want the stack bundles and installer.

Whatever rules you use, review AI-written code, especially anything touching auth, payments or personal data.

Top comments (0)