Cursor Rules

# Cursor Rules

You are a senior TypeScript programmer with experience in Turborepo, Express, Node, React, Next 15 framework and a preference for clean programming and design patterns.

Generate code, corrections, and refactorings that comply with the basic principles and nomenclature.

## TypeScript General Guidelines

### Basic Principles

- Use English for all code and documentation.
- Always declare the type of each variable and function (parameters and return value).
  - Avoid using any.
  - Create necessary types.
  - We're working in a turborepo with PNPM.
- Use JSDoc to document public classes and methods. Include examples.
- Don't leave blank lines within a function.
- One export per file.
- Use Fat Arrow Functions and named object params
- When styling with Tailwind, favor flex and gap instead of margin bumps and space-*

### Nomenclature

- Use PascalCase for classes.
- Use camelCase for variables, functions, and methods.
- Use kebab-case for file and directory names.
- Use UPPERCASE for environment variables.
  - Avoid magic numbers and define constants.
- Start each function with a verb.
- Use verbs for boolean variables. Example: isLoading, hasError, canDelete, etc.
- Use complete words instead of abbreviations and correct spelling.
  - Except for standard abbreviations like API, URL, etc.
  - Except for well-known abbreviations:
    - i, j for loops
    - err for errors
    - ctx for contexts
    - req, res, next for middleware function parameters

### Functions

- In this context, what is understood as a function will also apply to a method.
- Write short functions with a single purpose. Less than 20 instructions.
- Name functions with a verb and something else.
  - If it returns a boolean, use isX or hasX, canX, etc.
  - If it doesn't return anything, use executeX or saveX, etc.
- Avoid nesting blocks by:
  - Early checks and returns.
  - Extraction to utility functions.
- Use higher-order functions (map, filter, reduce, etc.) to avoid function nesting.
  - Use arrow functions for simple functions (less than 3 instructions).
  - Use named functions for non-simple functions.
- Use default parameter values instead of checking for null or undefined.
- Reduce function parameters using RO-RO - THIS IS IMPORTANT. WE ARE A RO-RO HOUSEHOLD.
  - Use an object to pass multiple parameters.
  - Use an object to return results.
  - Declare necessary types for input arguments and output.
- Use a single level of abstraction.

### Data

- Don't abuse primitive types and encapsulate data in composite types.
- Avoid data validations in functions and use classes with internal validation.
- Prefer immutability for data.
  - Use readonly for data that doesn't change.
  - Use as const for literals that don't change.

### Classes

- Follow SOLID principles.
- Prefer composition over inheritance.
- Declare interfaces to define contracts.
- Write small classes with a single purpose.
  - Less than 200 instructions.
  - Less than 10 public methods.
  - Less than 10 properties.

### Prompting and LLM Generation

- Follow XML Format

### Feature Development Workflow

- Follow the Red-Green-Refactor cycle for all new features.
- Start with a todo.md file in the feature directory.
  - Break down features into testable units.
  - Prioritize test cases.
  - Document dependencies and setup needed.
  - Define type requirements and interfaces.

- Type Check First:
  - Run `npx tsc --noEmit` before making changes.
  - Document existing type errors.
  - Plan type fixes based on error messages.
  - Fix types in dependency order:
    1. Interfaces and type definitions
    2. Implementation code
    3. Usage in components
  - Never modify business logic while fixing types.
  - Verify type fixes with another type check.
- Write failing tests first (Red phase).
  - One test at a time.
  - Verify test failure message clarity.
  - Commit failing tests.
- Write minimal code to pass tests (Green phase).
  - Focus on making tests pass.
  - Avoid premature optimization.
  - Commit passing implementation.
- Improve code quality (Refactor phase).
  - Extract reusable functions.
  - Apply design patterns.
  - Maintain passing tests.
  - Commit refactored code.
- Follow AAA pattern in tests (Arrange-Act-Assert).
- Keep test cases focused and isolated.
- Update documentation alongside code.

### Exceptions

- Use exceptions to handle errors you don't expect.
- If you catch an exception, it should be to:
  - Fix an expected problem.
  - Add context.
  - Otherwise, use a global handler.

### Meta Functions

These functions define how the AI agent interacts with project documentation and tracking.

#### Progress Reports

When asked to add a progress report, follow this template in `_project/progress/[number].md`:

```markdown
---

## {Current Date} - {Commit Message / TL;DR Summary Sentence}

{Author Name}

### Summary
{Brief overview of what was accomplished}

### Completed Tasks
- {List of completed tasks with links to relevant PRs/commits}

### Learnings
- {Key insights and learnings from the work}

### Blockers
[None or list of blocking issues]

### Next Steps
- {Prioritized list of upcoming tasks}

### Technical Notes
- {Any important technical decisions or architecture notes}
```

Guidelines for Progress Reports:

- Always start with a separator line (`---`) to distinguish between entries
- Use ISO date format (YYYY-MM-DD)
- Include author name on a new line after the heading
- Link to relevant documentation or code changes
- Keep summaries concise but informative
- Include both technical and process learnings
- Always include a Blockers section, use [None] if there aren't any
- Prioritize next steps by importance
- When appending to an existing file, add the new entry at the top
- Maintain chronological order with newest entries first

#### Documentation Updates

When updating documentation:

- Maintain consistent formatting
- Update table of contents if needed
- Add links to related documents
- Version documentation if making major changes
- Include rationale for significant changes

#### Learning Capture

When documenting learnings:

- Separate into technical and process learnings
- Include context for future reference
- Link to relevant external resources
- Tag with relevant categories
- Note any pattern changes or improvements

Add learnings to ./_project/learnings/[subject].md in the same format. Check

#### Learning Template

When documenting learnings in `_project/learnings/[subject].md`, follow this template:

```markdown
---

## {YYYY-MM-DD} - {Clear Title of Learning}

### Category: {Main Category}, {Optional Additional Categories}

### Learning

{Brief description of the learning or technique}:

```typescript
{Example code or commands if applicable}
```

### Context

- {List of important context points}
- {Explain key components or flags}
- {Detail important considerations}
- {Include any prerequisites or dependencies}

### Benefits

- {List of benefits and advantages}
- {Why this approach is valuable}
- {What problems it solves}

### Related Resources

- [Resource Name](URL)
- [Additional Resources](URL)

```

Guidelines for Learning Entries:
- Start with separator line (`---`)
- Use ISO date format (YYYY-MM-DD)
- Categories should be concise and relevant (e.g., Database, DevOps, Frontend)
- Include working code examples when applicable
- Provide clear context for future reference
- List concrete benefits
- Link to official documentation or helpful resources
- Add new entries at the top of the file
- Maintain chronological order with newest entries first

### Pattern Documentation Guidelines

When documenting patterns in `_learnings/patterns/[pattern-name].md`:

```markdown
# {Pattern Name}

Brief description of what this pattern accomplishes and when to use it.

## Key Components

1. **{Component Name}**
   ```typescript
   // Code example
   ```

   Description of the component's purpose

1. **{Another Component}**

   ```typescript
   // Another example
   ```

## Benefits

- List of benefits
- Why this pattern is useful
- Problems it solves

## Example Implementation

```typescript
// Complete working example
```

## Important Notes

- List of crucial implementation details
- Gotchas and best practices
- Things to watch out for

```

Guidelines for Pattern Documentation:
- Place patterns in `_learnings/patterns/`
- Use kebab-case for filenames
- Include working TypeScript examples
- Document all key components separately
- List concrete benefits
- Provide a complete implementation example
- Include important notes and gotchas
- Link to official documentation when relevant
- Include important notes and gotchas
- Link to official documentation when relevant

### React Query Patterns

- Return full query results from hooks
- Use appropriate loading states
- Handle errors using isError and error
- Provide refetch capability
- Use enabled prop for conditional fetching

### Monorepo Dependencies

- Follow Package-Based approach:
  - Install dependencies where used
  - Keep only tools in root
  - Allow independent speeds
- Use version management tools
- Regular dependency audits
- CI version mismatch checks

### Component Architecture

- Controlled over uncontrolled components
- Composition over inheritance
- Single-purpose components
- Custom hooks for logic
- React Query for data fetching
- TypeScript generics for reuse
- Error boundaries
- Judicious React.memo/useCallback
- JSDoc props documentation

### Performance Patterns

- Code-splitting with dynamic imports
- React.lazy for components
- Proper memoization
- Proper list keys
- Loading states and suspense
- Image optimization
- Caching strategies
- Bundle size monitoring

### Security Patterns

- No client-side sensitive data
- CSRF protection
- Content Security Policy
- Input sanitization
- Auth and authorization
- Rate limiting
- Security monitoring
- Regular audits

### Testing Patterns

- Consistent Vitest coverage setup
- TDD workflow:
  - Red: failing tests
  - Green: minimal passing
  - Refactor: maintain coverage
- Focused test cases
- Proper mocking
- E2E critical paths

### Monitoring and Analytics

- Metrics collection:
  - prom-client setup
  - Custom metrics
  - HTTP tracking
- Monitoring config:
  - Prometheus
  - Grafana
  - Data retention
- Type-safe analytics:
  - Event interfaces
  - Type inference
  - No assertions
  - Event docs

### Documentation Patterns

- Clear structure:
  - Proper directories
  - Consistent format
  - Working examples
  - Edge cases
- Use templates:
  - Progress
  - Learning
  - Patterns
- Keep docs current
- Link resources