# Cursor Project Rules: [Project name]

> Guide and starter content for Cursor project rules. Project rules are
> Markdown files with a small front matter block, stored in
> `.cursor/rules/` and committed with the code. They replace the legacy
> single `.cursorrules` file at the repository root. Replace every
> `[bracketed]` value before saving the rule files.

<!--
Guidance: How to use this template
- Create one .mdc file per topic in .cursor/rules/ rather than one large file.
- Copy the example rule below, change the front matter and body, and commit it.
- Keep each rule short and concrete; long rules dilute the instructions that matter.
- Migrate any existing .cursorrules content into scoped rule files, then delete it.
-->

## How project rules work

Each rule is a file such as `.cursor/rules/[topic].mdc`. The file starts
with a front matter block that tells Cursor when to include the rule in
the model's context, followed by the instructions in plain Markdown.

| Front matter field | Meaning | Example |
|---|---|---|
| `description` | One sentence the agent reads to decide whether the rule is relevant | `Conventions for React components` |
| `globs` | File patterns; the rule is attached when matching files are in context | `src/components/**/*.tsx` |
| `alwaysApply` | `true` includes the rule in every request in this project | `false` |

The combination of fields gives four common rule types:

- **Always**: `alwaysApply: true`. Use for a handful of project-wide rules only.
- **Auto attached**: `globs` set, `alwaysApply: false`. Applies when matching files are involved.
- **Agent requested**: only `description` set. The agent pulls it in when the description matches the task.
- **Manual**: no description, no globs. Included only when a user mentions it with `@rule-name`.

Nested `.cursor/rules/` folders inside sub-directories scope rules to that
part of a monorepo.

## Example rule file

The following is a complete rule file for React components. Save it as
`.cursor/rules/react-components.mdc`.

```markdown
---
description: Conventions for writing and changing React components in the web app
globs: src/components/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---

# React component conventions

- Use function components with named exports. No default exports.
- Props are typed with an `interface` named `[Component]Props` above the component.
- Build UI from the design system in `src/components/ui/`; do not add inline styles.
- Every user-visible string goes through `t()` from `src/i18n`.
- Keep components under 200 lines; extract hooks into `use[Name].ts` next to the component.
- Accessibility: every interactive element is reachable by keyboard and has an accessible name.
- Add or update a test in `[Component].test.tsx` with React Testing Library.

## Example

@src/components/ui/Button.tsx
```

The `@file` line at the end attaches a reference file as an example of the
expected style, which is often more effective than describing it.

## Writing good rules

- State rules as direct instructions ("Use", "Never", "Prefer") rather than discussion.
- Give one concrete example or reference file per rule where possible.
- Scope with `globs` so backend rules do not appear in frontend work.
- Keep `alwaysApply` rules to project essentials: stack, commands, hard security limits.
- Review rules when the codebase changes; remove those that no longer match reality.
- Keep shared rules for all agents in AGENTS.md and reference it, rather than duplicating text.

## Rule ideas

| File | Type | Covers |
|---|---|---|
| `project.mdc` | Always | Stack, package manager, required checks before done |
| `security.mdc` | Always | Secrets, production access, input validation |
| `api-routes.mdc` | Auto attached `src/app/api/**` | Validation, error format, auth checks |
| `database.mdc` | Auto attached `src/db/**` | Migrations, query scoping, transactions |
| `testing.mdc` | Auto attached `**/*.test.ts` | Test structure, factories, mocking |
| `commit-style.mdc` | Manual | Commit and PR message format |

## Standard and licence note

Based on Cursor's documented project rules convention (`.cursor/rules/*.mdc`
files with `description`, `globs` and `alwaysApply` front matter) and common
practice for agent instruction files. Field behaviour can change between
Cursor releases; check the current Cursor documentation. Original text
written for this collection. Template licence: MIT.