Use Cursor Rules as Team Rails

By Rogier Muller06.25.26
Use Cursor Rules as Team Rails

Use Cursor rules to give the agent durable instructions your team wants followed on every relevant task. Cursor rules work best when they are small, version-controlled, and tied to real review habits, not when they become a giant policy document.

Cursor rules are reusable instructions that Cursor can apply while its agent reads, edits, and reasons about your codebase. For Cursor training and Cursor workshop teams, they are the bridge between “please remember our conventions” and a workflow your repo can actually enforce.

Put durable guidance in rules, not prompts

Start with the guidance you repeat every week: test commands, folder boundaries, framework conventions, security constraints, and review expectations. Put those in a Cursor rules file under .cursor/rules, then commit it with the repo so every teammate and agent sees the same operating model.

This matters because prompts are task memory. Rules are team memory. A prompt can say “please follow our API style”; a project rule can say exactly where API routes live, which helper to use, and which tests must pass before proposing a change.

Don't write a rule like a handbook. Cursor rules examples should be short enough for a busy engineer to review in a pull request. If a rule needs ten pages, split it into smaller scoped rules or move reference material into a skill.

A good starter set is three files: one always-on engineering rule, one frontend rule attached to apps/web/**, and one backend rule attached to services/api/**. That gives the agent enough shape without flooding every task with irrelevant context.

Use AGENTS.md for repo boundaries

Use AGENTS.md for broad repository instructions that other coding agents and teammates can understand, then use Cursor rules for Cursor-specific behavior. The practical approach is this: keep the repo contract in plain Markdown, and keep Cursor activation details in .cursor/rules.

For example, an AGENTS.md at the repo root might say that generated migrations must not be edited by hand, production logging must go through @company/logger, and payment code requires a human reviewer. A nested services/billing/AGENTS.md can add stricter local rules for that package.

This matters for Cursor for engineering teams because scope beats volume. Local rules near the code are easier to trust than one sprawling root document that tries to describe every service, package, and exception.

Watch for duplicating the same instruction in five places. Pick one source of truth for each boundary. If AGENTS.md owns architecture constraints, let Cursor rules point to those constraints and explain how the agent should behave when it touches that area.

Turn repeated workflows into skills and subagents

Use Cursor skills for reusable workflows that are too large or too procedural for a rule. A cursor skill can package steps, templates, scripts, and reference notes so the agent can pull them in when the task calls for it.

Rules should say what must be true. Skills should teach how to do the work. For example, a rule might require every database migration to include a rollback note; a skill might walk the agent through creating the migration, running local checks, updating fixtures, and drafting the pull request summary.

Cursor subagents and cursor custom agents are useful when the work benefits from a named role. A “review subagent” can focus on risk, tests, and diff quality while the main agent implements the change. A “docs subagent” can update usage notes after an API change.

Don't make a subagent for every preference. Start with one custom subagent for review or one skill for a painful workflow. If the team does not invoke it twice in a week, it probably belongs in a checklist, not your agent setup.

For a broader map of these patterns, keep Subagents and skills handy. If your team is already standardizing on the newer customization surfaces, this companion note on Train Your Team on Cursor 3.9 is a useful next stop.

Paste this starter Cursor rules file

Here is a small .mdc rule you can adapt. Put it in .cursor/rules/team-engineering.mdc, then review it like code.

---
description: Team engineering rails for safe Cursor agent changes
alwaysApply: true
---

# Team engineering rails

When editing this repository:

- Prefer the smallest safe diff that solves the stated task.
- Read the nearest `AGENTS.md` before changing code in a package or service.
- Do not edit generated files, lockfiles, migrations, or snapshots unless the task explicitly requires it.
- Use existing project helpers before adding a new dependency or utility.
- Add or update tests for behavior changes. If tests are not practical, explain why in the final response.
- Before finishing, summarize:
  - files changed
  - tests run
  - risks or follow-up work

Frontend notes:

- Use existing design-system components from `packages/ui` before writing custom UI.
- Keep data fetching in the route-level loader or existing query hook for that feature.

Backend notes:

- Use `@company/logger` for application logs.
- Never log tokens, secrets, raw payment data, or full user payloads.
- For database changes, include the migration command and rollback note in the final response.

This is intentionally plain. It tells Cursor what to do, when to be cautious, and how to report back in a way humans can review.

Don't treat this file as permanent. Schedule a 15-minute rule review after two weeks. Remove instructions that never mattered, tighten vague lines, and add only the conventions that prevented real review comments.

Add a review loop your team can see

Rules only help if they change the review surface. Add a short pull request checklist that asks whether Cursor followed the relevant rule, used the nearest AGENTS.md, and ran the expected checks.

A lightweight checklist is enough:

  • Did the agent read the nearest AGENTS.md for touched code?
  • Did the diff stay inside the requested scope?
  • Did tests, typechecks, or lint run locally or in CI?
  • Did the final summary name risks and follow-up work?
  • Did a reviewer check generated files, migrations, and security-sensitive paths?

This matters because Cursor MCP, skills, hooks, and subagents can expand what the agent can touch. The more capable the workflow gets, the more useful a boring review checklist becomes.

Watch for trying to automate judgment away. Hooks and MCP servers can fetch context, run commands, or connect Cursor to systems such as GitHub and internal tools, but they do not replace ownership. Keep humans on the hook for boundaries, secrets, production risk, and product judgment.

Further reading

Make the next rule boring

Pick one repeated review comment from your repo and turn it into a small Cursor rule today. If it saves one back-and-forth this week, keep it; if not, delete it and try a sharper one.