.cursorrules and Project Conventions

Why .cursorrules Is Critical

Without a .cursorrules file, the AI operates on generic best practices. With one, it operates on your project's specific conventions, stack, and constraints. The difference in output quality is dramatic.

Every rule you add reduces the number of times you have to correct the AI. A well-crafted .cursorrules file effectively encodes your code review standards into the AI's behavior.

Anatomy of a .cursorrules File

The file is plain text (Markdown formatting is supported) placed at the project root. It's automatically included in every AI interaction in the project.

# Project: [Name] .cursorrules

## Stack
- Next.js 14 App Router
- TypeScript (strict mode)
- Tailwind CSS
- Supabase (PostgreSQL + Auth)
- Stripe for payments

## Coding Standards
- Use named exports only — no default exports except for Next.js page components
- All component props must have explicit TypeScript interfaces
- Use `const` by default; only use `let` when reassignment is necessary
- Prefer early returns over nested conditionals

## File Structure
- Components: src/components/[domain]/ComponentName.tsx
- Server actions: src/app/actions/[domain].ts
- Database helpers: src/lib/db/[table].ts
- Types: src/types/[domain].ts

## Patterns to Follow
- Use Supabase RLS for all data access — never query as service role from the frontend
- Server components fetch data; client components handle interaction
- Form validation uses Zod schemas defined in src/lib/schemas/

## Patterns to Avoid
- Do not use useEffect for data fetching — use server components or React Query
- Do not import lodash — use native array/object methods
- Do not use `any` type — always provide specific types

## Testing
- Unit tests use Vitest
- Integration tests use Playwright
- Test files live next to source files as ComponentName.test.tsx

Global vs. Project Rules

Cursor supports two scopes:

• `.cursorrules` — Project-level, checked into the repository, applies to everyone on the team
• Cursor Settings > General > Custom Instructions — User-level global rules, not in the repo

Use the project .cursorrules for team standards. Use global instructions for personal preferences that shouldn't be imposed on the team (like preferred comment style or personal workflow habits).

Rules Inheritance and Composition

For monorepos or projects with distinct sub-modules, you can have nested .cursorrules files. Cursor merges rules from the project root with rules from the folder closest to the open file.

This allows different rules for your frontend (/apps/web/.cursorrules) versus your API (/apps/api/.cursorrules) while sharing global constraints from the root.

Testing and Iterating Your Rules

Rules should be treated like code — written, tested, and refined over time.

To test a rule:

1. Write the rule
2. Ask Cursor to complete a task that the rule should influence
3. Observe whether the output respects the rule
4. If not, make the instruction more explicit or add an example

Some rules need concrete examples to be followed reliably:

## Error handling pattern
Always use this pattern for async server actions:

// Correct

const result = await someAction();

if (result.error) {

return { error: result.error };

}

return { data: result.data };

// Never

try {

const data = await someAction();

return data;

} catch (e) {

console.error(e);

}

Key Takeaways

• .cursorrules is injected into every AI interaction — it's the most impactful configuration in the project
• Include stack, file structure, coding standards, patterns to follow, and patterns to avoid
• Use project-level rules for team standards; global instructions for personal preferences
• Treat rules like code — write them, test them, and iterate when the AI doesn't follow them