Skip to content

Cursor

Set up version-controlled Cursor project rules in .cursor/rules.

Cursor stores version-controlled project rules in .cursor/rules/*.mdc. Choose whether each rule always applies, applies when relevant, matches specified files, or is invoked manually. Cursor's support documentation describes .cursorrules as a legacy root file that will be deprecated; it does not promise support across every Cursor version. Cursor also lists AGENTS.md as a simpler alternative to project rules.

.cursor/rules and legacy .cursorrules

Use .cursor/rules/*.mdc for current project rules:

  • Project rules are version-controlled in the repository.
  • Each rule is an .mdc file and can apply always, intelligently, to matching files, or when manually invoked.

If a project still has .cursorrules, migrate its contents to a new .cursor/rules/*.mdc file. To preserve the old file's behavior, choose Always Apply for the new rule, then remove the legacy file. Do not rely on .cursorrules as a format supported by every Cursor version.

What goes in a project rule

The OTF SaaS Dashboard kit running in dark mode, with its sample workspace data: the sidebar, the open issues and closed-this-week counts, and the created-versus-closed chart.

Use the same kit conventions as CLAUDE.md, formatted as a Cursor project rule:

.cursor/rules/kit-conventions.mdc
---
description: Conventions for this kit
alwaysApply: true
---

You are working inside the OTF SaaS Dashboard kit. The stack:

- Vite 6 + React 19, TanStack Router for routing, TanStack Query for data
- Hono 4 + Bun 1.3 server (same process as static SPA)
- Postgres + Drizzle ORM
- Better Auth 1.6 (email + Google + demo login)
- @otfdashkit/ui (Radix + Tailwind) for components

## Conventions you must follow

1. **Strict TypeScript.** No `any`, no `as` casts unless documented.
2. **Functional components.** `forwardRef` only on DOM-leaf components.
3. **Tailwind token classes only** — `bg-background`, `text-foreground`,
   `border-border`. Never hardcode hex.
4. **Hooks follow the optimistic-update pattern** in `src/hooks/useProjects.ts`.
5. **Hono routes follow the standard CRUD shape** in `server/routes/projects.ts`.

## When you add a screen

1. Create `src/pages/home/<name>.tsx`, wrap content in `<FadeIn>` + `<Page>`/`<PageHeader>`/`<PageBody>`
2. Add a route in `src/main.tsx` via `createRoute(...)` + add to `homeLayoutRoute.addChildren([...])`
3. Add a sidebar item in `src/components/Sidebar.tsx` (Lucide icon)
4. Optional: add a hotkey via `useEffect` keydown listener

Every page must have a loading <Skeleton>, an <EmptyState> for zero data, and a <FadeIn> mount.

Tips

  • Lead with rules, not facts. Cursor's chat model responds best to imperatives ("you must", "always", "never").

  • Keep required guidance in the rule body. You can reference project files with @path; the agent reads referenced files when needed, but their contents are not always included up front.

  • Choose the apply mode deliberately. Use Always Apply for guidance needed in every Agent conversation, or scope rules to relevant files or workflows.

Cursor documents project rules as applying to Agent (Chat); they do not apply to Tab completion, Inline Edit, or Bugbot PR reviews.

When Cursor rules and CLAUDE.md drift

It will happen. The fix:

  1. Decide which file is the source of truth for shared kit conventions. OTF uses CLAUDE.md for the common guidance and .cursor/rules/*.mdc for Cursor-specific scope and apply behavior.
  2. Keep both files aligned when shared conventions change; do not use the legacy .cursorrules file as the generated copy.

Sources

Vendor documentation checked 9 Oct 2026:

  • Cursor Docs, Rules — project rule storage, formats, and apply modes.
  • Cursor Support, Rules — .cursorrules migration guidance and supported rule surfaces.

Free with your email

Get the free AI configs pack

The AI files every kit ships with. Drop them in and your AI tool knows your project.

  • CLAUDE.mdProject context
  • .cursorrulesRules for Cursor
  • prompts/Task prompts

No spam. Unsubscribe any time.