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
.mdcfile 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
Use the same kit conventions as CLAUDE.md, formatted as a Cursor project rule:
---
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:
- Decide which file is the source of truth for shared kit conventions. OTF uses
CLAUDE.mdfor the common guidance and.cursor/rules/*.mdcfor Cursor-specific scope and apply behavior. - Keep both files aligned when shared conventions change; do not use the legacy
.cursorrulesfile as the generated copy.
Sources
Vendor documentation checked 9 Oct 2026: