Without explicit rules, every developer on your team gets different AI suggestions for the same problem. A well-written rules file fixes that in minutes.
The original format was a single .cursorrules file at the repo root with free-form text. As of more recent versions, Cursor moved to a per-folder rules system: .cursor/rules/*.mdc, where each .mdc file defines a block of instructions with metadata (which file globs it applies to, whether it activates always or on demand). The plain .cursorrules file still works for backward compatibility, but if you're starting a new project, it's worth using the .mdc format.
Each rule has a YAML header with description, globs, and alwaysApply, followed by markdown content that gets injected into the model's context when the rule applies.
With globs you can have layer-specific rules: one for the Laravel backend, another for React components, another for the database schema. Cursor only injects the rule when the opened or edited file matches the pattern, which saves context tokens.
The most common mistake is writing vague rules like "write clean, maintainable code." That doesn't change the model's behavior because it isn't actionable. Rules that work are specific and verifiable:
- Bad: "Follow good security practices." - Good: "Any user input that reaches a query must go through the query builder or Eloquent; raw SQL concatenation is forbidden."
- Bad: "Use descriptive names." - Good: "Boolean variable names must start with is, has, or can. Example: isAuthenticated, not authFlag."
Think of rules as the onboarding you'd give a junior developer on their first day, but written so an LLM will respect it in every suggestion.
Beyond style, document architectural decisions the AI can't infer from the code alone:
This keeps the model from "reinventing" patterns you already decided on, like using sessions when the project is API-only, or ignoring tenant filtering.
Rules live in .cursor/rules/ inside the repo, so they get versioned with git like any other file. Recommendations:
- Review changes to rules in a pull request just like you'd review a linter change. - Have a general.mdc rule with alwaysApply: true for non-negotiables (security, folder structure) and glob-scoped rules for everything else. - When you notice the AI making the same mistake repeatedly across the team (for example, not using the centralized logger), that's a signal a rule is missing, not that you need to keep correcting it by hand.
Cursor also supports global per-user rules (Settings > Rules for AI) that apply across all your projects, useful for personal preferences like comment language. But for team work, rules should live in the repository, not each developer's personal config — otherwise everyone gets different suggestions and you lose the point of standardizing.
A rules file isn't "set it and forget it." Every time the team adopts a new pattern (a library, a commit-naming convention, a testing framework change), update the corresponding rule in the same PR that introduces the change. Treat it as documentation technical debt: if the rules go stale, the AI starts suggesting old patterns and the team loses trust in the tool.
Carlos Montiel is an enterprise AI solutions architect. He implements LLMs, Agents, RAG, and orchestrators for companies across Guatemala and Latin America. Reach out for a consultation.
Contact Carlos Montiel