# Project context

This is a full-featured Nuxt 4 template focusing on clean, maintainable code with modern best practices.

# Tech stack

- **Framework**: Nuxt 4 with Vue 3 Composition API
- **Language**: TypeScript (strict mode preferred)
- **Package manager**: PNPM
- **Styling**: Tailwind CSS v4 with dark/light mode theming
- **UI components**: shadcn-vue (Reka UI based)
...

# 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].

# 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

# 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

# State management

Use Pinia for global state:
- Create stores in `app/stores/`
- Use camelCase for store names
- Keep stores focused and small

Example:
```ts
export const useCartStore = defineStore('cart', () => {
  const items = ref([])
  const total = computed(() => /* ... */)
  return { items, total }
})

# 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 */]
  }
}

# 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

# 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

# External APIs

Stripe integration:
- Use webhook events, not polling
- Store minimal customer data
- 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
- Implement retry logic with exponential backoff

# Testing

Test requirements:
- Write unit tests for all utilities
- Write integration tests for API endpoints
- Write E2E tests for critical user flows
- Aim for 80% code coverage

Test file naming:
- Unit tests: `*.test.ts`
- Integration tests: `*.integration.test.ts`
- E2E tests: `*.e2e.test.ts`

Use Vitest for unit/integration tests.
Use Playwright for E2E tests.

# ===== 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]

# ❌ 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

# ✅ 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:

## Using with Cursor

If you're using the Cursor editor:

1. The `.cursorrules` file is automatically loaded
2. The AI uses these rules when generating code
3. Update the file anytime to change AI behavior

## Using with other AI tools

Other AI coding assistants can use this file too:

- **GitHub Copilot**: Include rules in comments
- **ChatGPT**: Copy-paste relevant sections when asking for help
- **Claude**: Reference the rules file in your prompts

## Advanced: Multiple rule files

For large projects, consider organizing rules into multiple files:

Reference them in the main `.cursorrules`:

## Reference

- [Cursor documentation](https://docs.cursor.com)
- [Cursor rules examples](https://github.com/PatrickJS/awesome-cursorrules)

::tip
Treat your `.cursorrules` file as living documentation. Keep it updated as your project evolves, and it will help both AI assistants and human developers understand your codebase better.
::