Cursor rules
Customize AI coding assistant rules for your project
This boilerplate includes a .cursor/rules/main-rules.mdc file that provides context and guidelines to AI coding assistants like Cursor, helping them understand your project structure and conventions.
What are Cursor rules?
Cursor rules are instructions that help AI assistants:
- Understand your project structure.
- Follow your coding conventions.
- Use the correct tech stack.
- Respect your preferences.
The rules are stored in .cursor/rules/main-rules.mdc and include alwaysApply: true frontmatter to ensure they're automatically loaded by Cursor.
Quick start
To customize the rules for your project:
- Open
.cursor/rules/main-rules.mdcin your project. - Update "Project context" - Replace the generic description with your specific product/features.
- Add domain-specific rules - Document your business logic, user roles, or API patterns.
- Keep it updated - Add new conventions as your project evolves.
Start by updating the project context section to describe what YOUR application does. This gives the AI immediate context when helping you code.
Customizing Cursor rules
Adding project-specific context
Add information about your specific application:
# Project context
This is a SaaS platform for [your product description].
Key features include:
- [Feature 1]
- [Feature 2]
- [Feature 3]
Target users are [description of your users].
Adding custom coding preferences
Specify your team's preferences:
# Coding preferences
- Prefer functional programming over classes.
- Use early returns to reduce nesting.
- Always add JSDoc for public APIs.
- Limit file length to 300 lines.
- Use descriptive variable names, avoid abbreviations.
- Write tests for all business logic.
Adding architecture guidelines
Document your architecture decisions:
# Architecture
- Use server-side rendering for SEO-critical pages.
- Implement feature flags for gradual rollouts.
- Keep API endpoints RESTful.
- Use WebSockets for real-time features.
- Cache expensive queries with Redis.
Adding API patterns
Document your API conventions and patterns:
# API patterns
All API endpoints should:
1. Use proper HTTP methods (GET, POST, PUT, DELETE).
2. Return consistent error responses.
3. Include pagination for lists.
4. Validate input with Zod schemas.
5. Require authentication where appropriate.
Example error response:
```json
{
"error": {
"message": "Validation failed",
"code": "VALIDATION_ERROR",
"details": [/* validation errors */]
}
}
Adding security guidelines
Document security requirements:
# Security
- Never expose API keys in client code.
- Validate all user input.
- Use parameterized queries to prevent SQL injection.
- Implement rate limiting on all endpoints.
- Log security-relevant events.
- Require HTTPS in production.
Common customization examples
Domain-specific rules
# Domain model
User roles:
- **Admin**: Full system access.
- **Manager**: Can manage team members.
- **Member**: Standard user access.
- **Guest**: Read-only access.
Subscription plans:
- **Free**: Basic features, 10 items/month.
- **Pro**: All features, 100 items/month, $29/month.
- **Enterprise**: Unlimited, custom pricing.
Business rules:
- Users must verify email before accessing features.
- Free plan users see ads.
- Pro features require active subscription.
Third-party integrations
# External APIs
Stripe integration:
- Use webhook events, not polling.
- Sync subscription status immediately.
- Handle failed payments gracefully.
OpenAI integration:
- Set max_tokens to prevent runaway costs.
- Use streaming for better UX.
- Cache responses when possible.
Organizing rules for clarity
For large projects, organize rules by category:
# ===== PROJECT CONTEXT =====
[Project overview]
# ===== TECH STACK =====
[Technology choices]
# ===== CODING STANDARDS =====
[Code style and patterns]
# ===== ARCHITECTURE =====
[System design decisions]
# ===== SECURITY =====
[Security requirements]
# ===== DEPLOYMENT =====
[Deployment process]
# ===== COMMON PITFALLS =====
[Things to avoid]
# ===== EXAMPLES =====
[Code examples]
Best practices
Be specific
# ❌ Too vague
- Write clean code.
- Follow best practices.
# ✅ Specific
- Keep functions under 20 lines.
- Use early returns instead of nested if statements.
- Name boolean variables with is/has/should prefixes.
Provide examples
# ✅ With examples
When creating API endpoints, follow this pattern:
````ts
export default defineEventHandler(async (event) => {
// 1. Validate input
const body = await readBody(event)
const data = schema.parse(body)
// 2. Check authentication
const { user } = await requireAuth(event)
// 3. Check authorization
if (!canAccessResource(user, data.resourceId)) {
throw createError({ statusCode: 403 })
}
// 4. Perform operation
const result = await performOperation(data)
// 5. Return response
return { success: true, data: result }
})
````
Keep it updated
Update the rules file when:
- Adding new features.
- Changing architecture.
- Adopting new libraries.
- Learning from mistakes.
Document decisions
Explain the "why" behind rules:
# Use Composition API, not Options API
Reason: Composition API provides:
- Better TypeScript support.
- Easier code reuse via composables.
- More flexible code organization.
- Better tree-shaking.
Don't use Options API for new components.
Using with other AI tools
While designed for Cursor, this file can help other AI tools too:
- Cursor: Automatically loads
.cursor/rules/main-rules.mdcfile. - GitHub Copilot: Include rules in code comments when needed.
- ChatGPT/Claude: Copy relevant sections when asking for help.
Additional resources
Treat your
.cursor/rules/main-rules.mdc file as living documentation. Update it as your project evolves to help AI assistants (and new developers) understand your codebase better.