My Cursor Rules

My Cursor Rules

=== USER RULES ===
# I store each one of these as a single Rule in the Cursor User Settings file, rather than in one big block
# From what I can tell, it doesn't matter which way you do it, I just find that easuer to manager

Core Principles
- Simplicity First: Prefer the simplest, clearest working solution. Add complexity only if it solves a real problem.
- Maintainability: Code should be easy to read, modify, and extend.
- Critical Collaboration: Act as a thoughtful partner. Evaluate ideas, question them, and explain reasoning — never rubber-stamp suggestions.

Critical Partnership & Validation
- Challenge Thoughtfully: Evaluate suggestions critically. If risks or unnecessary complexity exist, flag them and suggest simpler alternatives.
- Best Practice, Pragmatically: Use best practices when they add value; skip them when they create overhead without clear benefit.
- Rationale Required: Always explain why a solution is better in this context.
- Confirm Before Implementing: Don't modify code or implement solutions until the approach is agreed upon.

Communication & Feedback Loop
- Neutral Start: Do not begin responses with affirmations like “You’re absolutely right,” “Correct,” or “Of course.” Start by restating the problem neutrally, then provide analysis or options.
- Plain English: Explain decisions and trade-offs clearly, avoiding unnecessary jargon.
- Confirm and Plan: After task discussion, summarize:
    - The agreed task.
    - The chosen approach.
- Small, Safe Steps: Make incremental changes; avoid sweeping refactors without explicit agreement.

Code Quality & Standards
- Balanced Design: Keep code simple and modular. Follow good practices (separation of concerns, modularity), but avoid over-architecture unless necessary.
- Readability First: Optimize for clarity and maintainability over cleverness or premature optimization.
- Avoid Duplication: Consolidate repeated code into helpers/utilities where it improves clarity and reduces maintenance.
- Documentation: Document functions, methods, and classes concisely using the project’s docstring standard.
- No Placeholder Work: Don’t leave TODOs unless explicitly directed; if unavoidable, explain them at the end of the task.
- Working Code: When you create new code the code should compile and tests should pass unless you are instructed to not complete those steps

Security and External Context
- Security Hygiene: Validate/sanitize all user input and API/database interactions. Be mindful of common vulnerabilities (XSS, injection, etc.) and propose proportionate defenses.
- Dependency Justification: Suggest external libraries only when native solutions cannot achieve the goal, and the benefits clearly outweigh the overhead.




=== PROJECT RULES ===
# These rules are added to projects on a need-to basis depending on what the scope of the project is
# Vast majority of them are based on the languages being used, and I keep those light as the user rules should drive good engineering practice
# I also provide a single project rule, which describes the project in more detail, but that is very project specific

---
description: Bash Scripting and Support Function Standards
globs:
  - **/*.sh
alwaysApply: true
---

- Bash Scripting & Support Functions Standards
    - All Bash scripts must begin with the shebang #!/usr/bin/env bash and include the robust set command: set -euo pipefail to ensure immediate exit on errors, failure for unset variables, and proper pipe failure handling
    - All mission-critical commands must include a check for a successful exit status ($?) or use || exit 1
    - Scripts should provide clear, actionable logging messages (e.g., using echo with distinct prefixes) rather than silent execution
    - You must strictly enforce the use of double quotes around all variable expansions (e.g., "$my_variable") to prevent word splitting and globbing issues
    - Prefer standard POSIX utilities (e.g., awk, sed) and avoid using non-standard Bash extensions where possible
    - Scripts must be clear and include comments explaining complex logic or unusual syntax
    - Bash scripts are exclusively for support functions (e.g., deployment, cleanup, lifecycle management) and you must challenge any attempt to use Bash for business logic that should reside in an application layer
    
    
    
---
description: HTML Markup Standards
globs:
  - **/*.html
alwaysApply: true
---

- HTML Markup Standards
    - All elements must be used semantically so avoid using generic <div> or <span> elements where a more descriptive element exists (e.g., use <header>, <nav>, <main>, <article>, <button>)
    - All user interface components must be accessible and have proper use of ARIA roles and properties where native HTML semantics are insufficient, especially for dynamic content
    - All tags must be properly closed and markup must be valid HTML5
    - Avoid non-standard or deprecated elements and attributes
    - Never use inline CSS (style="...") or inline JavaScript event handlers (onclick="...")
    - Stylesheets must be external or contained within the <style> block
    - JavaScript must be external or referenced via the <script> tag
    
    
    
---
description: TypeScript Standards
globs:
  - **/*.ts
  - **/*.tsx
alwaysApply: true
---

- Typescript & Node.js Standards
    - Prioritize utility types and type inference to maintain clean, readable code
    - Enforce strict type checking for all new code and never use the any type without explicit approval and a detailed comment explaining the necessity
    - All complex interfaces, custom types, and enumerations must be defined in dedicated .ts or .d.ts files separate from the main business logic implementation to enforce modularity and prevent unnecessary circular dependencies
    - Encourage immutable patterns by defaulting to const, using spread operators (...), and preferring pure functions and challenge any code that directly modifies passed arguments or existing state
    - All new code must leverage modern JavaScript/TypeScript standards (ES6+) and specifically use async/await for all promise handling, avoiding older patterns like callbacks or .then() chains
    - All functions, especially those interacting with external systems (APIs, forms, databases), must include appropriate error handling (e.g., try...catch) and validate inputs using type boundary checks to prevent runtime errors
    - Use ES Module syntax (import/export) exclusively, and challenge the use of require() in any new or refactored TypeScript files

- Code Organisation
    - In classes member variables come first, then methods
    - For variables and methods, they should be added in the order public, protected, private

- Comments
    - Should only be used when they need to explain rational and behaviour, not code
    - Methods, interface, types and declarations etc. should be a single one line comment explaining their purpose, not listing all params, return codes etc
    
    
    
---
description: Python coding standards and development rules
globs:
  - **/*.py
alwaysApply: true
---

- Pyenv is used for all Python environment management

- Python Standards
    - Use type hints consistently across all types and function returns
    - Use lazy formatting for all strings where possible
    - Avoid unnecessary else statements; use the if-return pattern instead
    - Avoid hard-coded values, pull out fixed values to the top of the file as scoped final variables
    - Never use local imports, always import them at the top of the file
    - Use lowercase with underscores for directories and files (e.g., routers/user_routes.py).

- Shared libraries
    - Ensure you indicate public and non-public methods using _ at the start of method names
    - Expose default imports using __all__ = []

- Documentation (function, method, module etc.)
    - Should start and end with a space and for single sentence comments they do not have a full stop
    - Should be simple and should not document types, arguments, return types etc

- For error handling
    - Place the happy path last in the function for improved readability
    - Implement proper error logging and user-friendly error messages
    - Do not use generic exceptions and be specific on the error, creating new exception classes if needed
    - Never use warnings.filterwarnings unless I explicitly ask you to

- Formatting
  - Follow PEP8 conventions for all code written - https://peps.python.org/pep-0008
  - Use pylint for all linting
  
  
  
  
=== EXAMPLE PROJECT OVERVIEW ===
# I'll have one of these per project which just helps the agent understand the project structure
# without having to do an deep investigation each time

---
description: An overview of this project and it's file structure
alwaysApply: true
---

- Project Overview
    - An AI powered audio/video generation pipeline to create long videos with minimal animation playing music
    - All AI models and scripting is done locally with no use of external LLMs like Gemini or ChatGPT
    - README.md in the root folder has a breakdown of how the project works

- Development 
    - All code is written in either Python (for the generation process) or bash files (for support functions)
    - For the Python environment
        - The version used is specified in .python-version

- Organisation
    - All main project scripts are in the src folder
    - There are additional utility scripts in the utilities folder
    - Within the src/generation folder are the individual stages of the generation process (starting at "01 - ", then "02 -" etc.)
    - Each stage in the process is a standalone Python environment to avoid package conflicts across different AI models
    - In src/generation, each stage has it's own requirements file(s) stored in the "requirements" folder
    - In src/generation, each stage has it's own virtual environment which is in the root of the stages folder
    - When a new stage is added, it will be added sequentially (e.g. "03 - ") to the scripts folder mirroring the other stages folder structure
    - Within the src/utilities folder are common utilities that are used in all scripts
    - Within the src/sdxl folder are Stable Diffusion XL specific utilities used by some stages

- Configuration 
    - The project is powered by the root "generation.json" file which defines all properties of the generation process