Cursor Rules for AI Projects: Keep the Agent on the Task

Cursor rules are standing instructions that Cursor includes at the start of the model’s context whenever they apply. For an AI project the useful ones are project rules: .mdc files in .cursor/rules, committed with the code, each with a type that decides when it is loaded. A good set says how the codebase works, what the agent must not touch, and how it picks up and reports a task. That last part is the one most projects leave out, and it is what keeps an agent on the task you gave it instead of the three it noticed on the way.

Four places a rule can live

Cursor’s rules documentation↗ (opens in a new tab) describes four kinds:

• Project rules: files in .cursor/rules, version-controlled and scoped to the codebase. You can organise them in subfolders.
• User rules: your own preferences under Customize, Rules, applied in every project. Tone and personal habits go here, not project conventions.
• Team rules: free-form rules managed from the Cursor team dashboard, which an admin can make required for everyone. A team rule can also carry a glob pattern, and then applies only when matching files are in context.
• AGENTS.md: plain Markdown with no frontmatter, following the open AGENTS.md↗ (opens in a new tab) convention, at the project root or in any subfolder. Nested files combine with their parents, and the more specific one wins where they disagree.

One trap: project rules must end in .mdc. A plain .md file inside .cursor/rules is ignored, because it has no frontmatter to say when it applies. If you want plain Markdown, use AGENTS.md, which has the advantage of being read by other agents too; does GitHub Copilot read AGENTS.md? covers Copilot’s side.

The four rule types

Each project rule has a type, set from a dropdown in the editor or by three frontmatter fields: alwaysApply, description and globs.

• Always Apply (alwaysApply: true): included in every chat session. Description and globs are ignored.
• Apply Intelligently (alwaysApply: false with a description): the agent reads the description and pulls the rule in when it judges it relevant.
• Apply to Specific Files (alwaysApply: false with globs): attached automatically when a matching file is in context. Separate several patterns with commas.
• Apply Manually (alwaysApply: false, neither field): included only when you mention it in chat, for example @release-checklist.

---
globs: db/migrations/**
alwaysApply: false
---
- Every migration has an up and a down step.
- Never change a column type in place: add, backfill, then drop in a later migration.
- Follow @db/migrations/_template.sql for the file layout.

The @ reference pulls a file into the rule’s context, so the rule points at a real example instead of copying one that will drift. You can also type /create-rule in the agent and describe what you want; it writes the file with the frontmatter for you.

Rules in a repository with several apps

A single folder of rules works for one app. In a repository with a web app, a mobile app and shared packages, the rules for one are noise for the others, and noise is what makes an agent skim. Two tools keep them apart.

• Scope project rules with globs. A rule for apps/mobile/** is attached only when a mobile file is in context, so the web work never sees it. Subfolders inside .cursor/rules keep the files themselves in order.
• Put an AGENTS.md in each app folder. Cursor applies it to work in that folder and below, combined with the root file, so the root carries what is true everywhere and each app carries its own commands and conventions.
• Keep one rule about the work itself at the root, marked Always Apply: which task is being worked on and how it is reported. That is the same in every app, and it is the rule further down.

Whichever you choose, write the app name into paths and commands. “Run the tests” is ambiguous in a monorepo; “run pnpm --filter web test” is not.

What rules do not reach

• Rules are used by Agent (Chat) only. According to Cursor’s help↗ (opens in a new tab), they do not apply to Tab completion, Inline Edit or Bugbot PR reviews.
• When several apply, Cursor merges them in the order team rules, project rules, user rules; the earlier source wins where they conflict.
• A rule is guidance, not enforcement. Cursor’s own documentation says AI guidance should not be your only security control. Anything that must never happen needs a real permission behind it.

Writing rules an agent follows

• Keep each rule under 500 lines, and split a large one into several focused rules. Cursor’s guidance is explicit about both.
• Write rules that can be checked: “run pnpm test before you say you are done”, not “test your changes”.
• Reference files rather than pasting them in; pasted code goes stale.
• Leave out what the agent already knows: common style conventions, how git or npm work. A linter enforces style better than a paragraph.
• Add a rule when you see the same mistake twice, not before. Then commit it, so the whole team gets the fix.

A rule that points the agent at the board

Most rule sets describe the code and say nothing about the work. The agent is then told how to write a component but not which task it is on, what counts as finished, or where to say what it did. The result is scope creep: it fixes the bug, tidies two files nearby, and reports all of it as one change in a chat that closes at the end of the day.

Connect your board to Cursor first through Cursor’s MCP support↗ (opens in a new tab); for fenbs that is one entry in mcp.json, described on Connect Cursor. Then add an Always Apply rule, because this one must hold in every session, not only when the agent thinks it relevant:

---
description: How to pick up, record and finish work on the fenbs board
alwaysApply: true
---
- Before changing code, call fenbs_whoami and fenbs_get_context, then fenbs_get_item for the task ref I give you.
- No ref? Search with fenbs_search. If nothing matches, create the task with fenbs_create_item
  (kind: bug, feature or enhancement) and tell me its ref before you start.
- Work on that one task. If you notice something else, file it as a new task; do not fix it in this change.
- When you start, move the task to In Progress and write your approach in its plan. Rewrite the plan if it changes.
- When you stop, comment what changed, the commit, and the check you ran with its result.
  Set testStatus to tested only for checks you actually ran.
- Never move a task to Completed. I do that after review.

Each line closes a gap. Reading context first means the agent starts from what you have written about how you work. One task per change, with everything else filed, keeps the diff reviewable and the backlog honest. The plan field records the approach where colleagues can see it. And keeping Completed for a person means the lane says “reviewed”, not “an agent believed it was done”.

The rule sits on top of permissions, not in place of them. The agent acts under your role on the board, narrowed by the scopes you ticked when you connected it; if the rule is ignored, the board still refuses what the role does not allow, and the history shows every change it did make under its name and yours.

Checkpoints do not undo the board

Cursor takes checkpoints before significant changes, and restoring one reverts your files. According to Cursor’s agent overview↗ (opens in a new tab), checkpoints are stored locally, separate from Git, and restore files only. A task the agent moved or a comment it posted through MCP is not a file, so a checkpoint will not bring it back. The board’s history is the record there: every move is listed with who made it, and you can move a task back by hand.

Rules for the repository, context for the work

Rules belong to one repository and one tool. Some guidance is true of the work wherever it happens: how you name tasks, how big one should be, what “done” means. fenbs keeps that as AI context, short notes on the board that any connected assistant reads through fenbs_get_context. Put codebase conventions in .cursor/rules, and the things every assistant on the board should know, whether Cursor, Copilot or Claude, in AI context.