Cursor Rules for Teams: Scope, Tests, and Governance

Direct Answer

A team Cursor configuration should be a small set of scoped, versioned, testable rules connected to real repository evidence and deterministic delivery controls. Rules help the model find conventions and expected checks. They do not grant access, protect secrets, prove correctness, or replace CI and review.

The most maintainable design has one provider-neutral source of truth and thin Cursor adapters. It avoids copying the same policy into a legacy .cursorrules file, multiple .mdc files, an AGENTS.md, and a wiki where the copies silently diverge.

Understand the Current Rule Surfaces

Current Cursor Rules documentation describes four rule surfaces:

Project Rules can be always applied, selected by file glob, chosen by the Agent from a description, or manually included. A plain .md file inside .cursor/rules is not a Project Rule; current documentation requires the .mdc extension and frontmatter. The root .cursorrules mechanism is legacy.

These are product contracts, not timeless file semantics. Pin the Cursor version or verification date in your internal compatibility record and repeat activation tests after product changes.

Keep One Source of Truth

Classify guidance by owner:

If a linter can enforce formatting, use the linter. If IAM can deny a write, use IAM. Rules should carry information that the model needs to make a choice, not duplicate controls that software can enforce.

Design Focused Project Rules

A Project Rule needs:

• one purpose;
• a clear activation mode;
• the narrowest useful file scope;
• observable requirements;
• links to canonical examples;
• verification and escalation behavior.

Example:

---
description: "Billing API contracts and verification"
globs: "services/billing/**/*.go"
alwaysApply: false
---

- Read `services/billing/contract.go` and adjacent tests before editing.
- Preserve tenant and principal checks on every object lookup.
- Reuse the existing domain error types.
- Add a regression test for each changed behavior.
- Verify with `go test ./services/billing/...`.
- Stop and report conflicts between the task and the checked-in contract.

The frontmatter controls when Cursor includes the text. It does not enforce the listed behavior. A protected branch and CI must still reject a change that removes authorization or skips tests.

Avoid Ambiguous Rules

Weak rule:

Always write production-ready code and never introduce bugs.

Testable rule:

For changes under services/payments:
- preserve the public request and response schema;
- derive account ownership from authenticated context;
- add duplicate, timeout, and unauthorized tests;
- run `go test ./services/payments/...`;
- report any skipped check.

Words such as “clean,” “best,” “simple,” and “secure” need an observable definition. Otherwise the model must guess.

Use AGENTS.md for Portable Instructions

AGENTS.md is useful when the same repository guidance should be readable by people and multiple compatible coding agents. Current Cursor documentation supports root and nested files, with more specific nested instructions applying to their directory scope.

A root file might contain:

# Repository instructions

## Source of truth
- Public API contracts live under `api/`.
- Generated files under `gen/` are never edited manually.

## Required checks
- Run `go test ./...`.
- Run `golangci-lint run`.
- Report failures and skipped checks.

## Change boundaries
- Do not change dependencies, migrations, or deployment without approval.
- Never read or print secret files.

A nested services/payments/AGENTS.md can add payment-specific constraints. Do not repeat the root content. Repetition creates unclear precedence and makes updates expensive.

Treat Prompt Templates as Work Contracts

A reusable task template should define inputs and acceptance, not imitate a senior persona.

Regression-Test Template

Goal:
  Add tests for the selected function.

Read:
  The implementation, existing tests, public contract, and error types.

Cover:
  Happy path, boundaries, documented failures, and the reported regression.

Constraints:
  Do not change production behavior or add dependencies.
  Do not mock the unit under test.

Evidence:
  Report changed files and exact commands run.
  Do not claim coverage or success without command output.

Escalate:
  Missing dependency, conflicting contract, or behavior that cannot be observed.

Refactoring Template

Goal:
  Improve the selected code without changing observable behavior.

Before editing:
  Identify callers, side effects, concurrency assumptions, and current tests.

Proof:
  Add characterization tests if behavior is not already covered.
  Compare API, persistence, logs, metrics, and ordering where relevant.

Stop:
  If the requested shape requires a breaking change or no reliable oracle exists.

“Do not change behavior” is not self-validating. The template must point to tests or other oracles that make behavior observable.

Put Security Outside the Prompt

Rules can help an Agent cooperate with policy, but trusted systems must enforce:

• repository, branch, directory, and command permissions;
• secret isolation and redaction;
• network destination and tool allowlists;
• sandboxing and resource limits;
• approval for push, merge, deployment, deletion, and external writes;
• required tests, reviews, and signed artifacts;
• audit events and incident response.

NIST SSDF treats secure practices as part of the software lifecycle. A sentence in a model context cannot replace those controls.

Issue text, source comments, terminal output, documentation, and generated plans can carry hostile instructions. Treat them as evidence under the task, not as higher-priority policy.

Test Rule Activation and Outcomes

Two kinds of tests are necessary.

Activation Tests

Verify that:

• an always-applied rule appears in every intended Agent conversation;
• a glob rule appears only for matching files;
• an Agent-selected rule has a description specific enough to be selected;
• a manual rule is absent unless requested;
• nested AGENTS.md files apply only to the expected subtree;
• Team, Project, and User conflicts resolve according to current documentation.

Do not assume a file was loaded because it exists in Git.

Outcome Tests

Replay representative tasks and check:

• files changed remain inside scope;
• protected files and dependencies remain unchanged;
• required tests actually run;
• unauthorized or destructive actions are not attempted;
• missing evidence is reported;
• the diff satisfies the business oracle;
• irrelevant rules do not increase errors or cost.

A Runnable Go Outcome Gate

This dependency-free program checks recorded Agent runs against deterministic repository policy. A real harness should populate observations from a sandbox and CI rather than trusting the model's summary.

package main

import (
	"fmt"
	"path/filepath"
)

type Observation struct {
	ChangedFiles    []string
	CommandsRun     map[string]bool
	ExternalWrites  int
	ReportedSuccess bool
}

type Contract struct {
	AllowedRoot      string
	RequiredCommands []string
	MaxExternalWrites int
}

func evaluate(contract Contract, observed Observation) []string {
	var violations []string

	for _, file := range observed.ChangedFiles {
		relative, err := filepath.Rel(contract.AllowedRoot, file)
		if err != nil || relative == ".." ||
			len(relative) >= 3 && relative[:3] == "../" {
			violations = append(violations, "out_of_scope:"+file)
		}
	}

	for _, command := range contract.RequiredCommands {
		if !observed.CommandsRun[command] {
			violations = append(violations, "missing_check:"+command)
		}
	}

	if observed.ExternalWrites > contract.MaxExternalWrites {
		violations = append(violations, "external_write_budget_exceeded")
	}
	if observed.ReportedSuccess && len(violations) > 0 {
		violations = append(violations, "unsupported_success_claim")
	}

	return violations
}

func main() {
	contract := Contract{
		AllowedRoot:       "services/billing",
		RequiredCommands:  []string{"go test ./services/billing/..."},
		MaxExternalWrites: 0,
	}
	observed := Observation{
		ChangedFiles:    []string{"services/billing/handler.go"},
		CommandsRun:     map[string]bool{"go test ./services/billing/...": true},
		ExternalWrites:  0,
		ReportedSuccess: true,
	}

	violations := evaluate(contract, observed)
	fmt.Printf("accepted=%t violations=%v\n", len(violations) == 0, violations)
}

Expected output:

accepted=true violations=[]

The code intentionally checks evidence, not prose. In a production system, also verify command exit status, commit identity, sandbox provenance, and artifact hashes.

Version, Review, and Roll Back Rules

Treat a rule change like code:

1. state the repeated failure it is meant to fix;
2. identify owner and scope;
3. add or update a replay fixture;
4. compare old and new rule bundles on identical tasks;
5. inspect regressions and irrelevant activation;
6. review through a pull request;
7. canary with a small team or repository set;
8. roll back if task success, review effort, safety, latency, or cost regresses.

Record:

{
  "client": "cursor",
  "client_version": "recorded-version",
  "model": "provider/model@revision",
  "rule_bundle": "git-commit",
  "fixture_set": "coding-rules-v6",
  "result": "canary",
  "known_gaps": ["windows-shell", "large-monorepo"]
}

Accepted suggestions are not the same as successful work. Measure merged changes that passed checks, post-merge defects, unnecessary churn, reviewer time, incidents, and reversions.

Migrate Legacy .cursorrules Deliberately

Current Cursor documentation labels .cursorrules as legacy. A migration should:

1. inventory what the legacy file actually contains;
2. move portable repository facts to AGENTS.md or their canonical docs;
3. split Cursor-specific behavior into focused .cursor/rules/*.mdc files;
4. choose explicit activation for each Project Rule;
5. remove duplicate or contradictory copies;
6. run activation and outcome fixtures;
7. delete the legacy file only after the new path is verified.

Do not mechanically copy one large file into an always-applied rule. That preserves noise and hides whether the new scoping works.

Frequently Asked Questions

Where should Cursor Project Rules be stored?

Current Cursor documentation uses .cursor/rules/*.mdc. The frontmatter determines whether a rule is always active, file-scoped, Agent-selected, or manual. Use AGENTS.md when plain, directory-scoped Markdown is a better portable source.

How are Team Rules different from Project Rules?

Team Rules are managed at the organization level and can be enforced across repositories. Project Rules live with one codebase and are reviewed through its version-control workflow. Current precedence must be verified against Cursor documentation whenever the product behavior changes.

Can Cursor Rules enforce security policy?

No. They can explain policy to an Agent, but the model can misunderstand or fail to follow them. Credentials, repository access, sandboxing, network policy, branch protection, required checks, and release approval need deterministic enforcement.

What belongs in a reusable task template?

Include the goal, scope, authoritative references, required output, verification, evidence, and escalation conditions. Do not encode identity, permissions, prices, secrets, or irreversible approval in a prompt template.

How can a team measure whether a rule helps?

Replay old and new rule bundles on the same versioned repository tasks. Compare successful outcomes, regressions, unnecessary changes, policy violations, checks run, review effort, latency, and cost rather than accepted-suggestion counts alone.

Common Failure Modes

• treating a legacy filename as the current default;
• putting every convention in one always-applied rule;
• copying linter output, generated types, or entire style guides into context;
• duplicating requirements across Team Rules, Project Rules, and AGENTS.md;
• using a role prompt where a path, command, or acceptance test is needed;
• asking for “no behavior change” without characterization tests;
• letting issue text or code comments redefine policy;
• assuming an Agent-reported test result is execution evidence;
• storing secrets or production records in rules;
• changing rules without replay, ownership, or rollback.

Team Checklist

• [ ] Inventory Project, User, Team, AGENTS.md, and legacy rule surfaces.
• [ ] Assign one canonical owner to each requirement.
• [ ] Keep Cursor adapters narrow and scoped.
• [ ] Use current .mdc frontmatter and test activation.
• [ ] Link to authoritative files instead of duplicating them.
• [ ] Define task templates with scope, inputs, evidence, and escalation.
• [ ] Enforce permissions and side effects outside the model.
• [ ] Replay normal, boundary, stale-context, and injection cases.
• [ ] Measure successful outcomes, regressions, review effort, latency, and cost.
• [ ] Review, canary, and roll back rule changes like code.

Related Resources

• Customizing AI Coding Assistants
• AI Coding Rule Architecture
• Agent Harness Evaluation
• Prompt Engineering

Primary Sources

• Cursor Rules Documentation
• Cursor: Best Practices for Coding with Agents
• NIST Secure Software Development Framework 1.1

Conclusion

Good Cursor Rules reduce repeated ambiguity; they do not replace software controls. Keep one source of truth, map it into focused .mdc or AGENTS.md adapters, define observable outcomes, and replay changes against real repository tasks. The result is a team system that can evolve with Cursor and model versions without confusing prompt text with permission or proof.