AI Development Guidelines: Cursor RAG Integration and Project Standards

Posted on September 24, 2025

This document outlines comprehensive development guidelines for AI-assisted coding with Cursor, focusing on RAG (Retrieval Augmented Generation) integration and maintaining consistent project standards.

---
trigger: always_on
---

### 🕷️ Crawl4AI RAG Integration
- **Always use Crawl4AI RAG** to reference documentation for libraries like Vue 3, Nuxt 4, Tailwind CSS, and Better Auth.
- **For RAG queries, always use 5 results maximum** for focused, relevant information.
- **Only search three times maximum** for any specific piece of documentation. If you don't get what you need, use Brave Search MCP for wider web search.
- **When you find useful documentation via Context7, suggest crawling the source website** to store it in the RAG database for future reference.

### 🔄 Project Awareness & Context
- **Always read `PLAN.md`** at the start of a new conversation to understand the project's architecture, goals, and constraints.
- **Check `CHANGELOG.md`** to understand recent changes and project history.
- **Use consistent naming conventions, file structure, and architecture patterns** as described in the project documentation.
- **Always use `pnpm` instead of `npm`** for all package management operations.

### 🧱 Code Structure & Modularity
- **Never create a file longer than 500 lines of code.** If a file approaches this limit, refactor by splitting it into composables, utilities, or separate components.
- **Organize code into clearly separated modules**, grouped by feature or responsibility:
  - `components/` - Vue components (Board/, UI/)
  - `composables/` - Vue composables for state management
  - `utils/` - Utility functions
  - `types/` - TypeScript type definitions
  - `server/api/` - Server-side API routes
- **Use clear, consistent imports** (prefer named imports, use ESM syntax).

### 🧪 Testing & Reliability
- **Always create unit tests for new features** (composables, components, API routes, etc).
- **After updating any logic**, check whether existing tests need to be updated.
- **Tests should live in appropriate test directories** mirroring the main app structure.
- **Include at least**:
  - 1 test for expected use
  - 1 edge case
  - 1 failure case

### ✅ Task Completion & Documentation
- **Update `CHANGELOG.md`** immediately after making changes, using ISO date format from terminal: `date +"%Y-%m-%dT%H:%M:%S%z"`
- **Include descriptive entries** for each change, grouped by type (Added, Changed, Fixed, Removed).
- **Add new tasks or TODOs** discovered during development to appropriate documentation.

### 📎 Style & Conventions
- **Use JavaScript/TypeScript** as the primary language with Vue 3 Composition API.
- **Follow Vue 3 and Nuxt 4 best practices**, use TypeScript for type safety.
- **Use `<script setup>` syntax** for Vue components.
- **Use Tailwind CSS** for styling with mobile-first responsive design.
- **Use ESM syntax** (`import`/`export`) - never use `require()` or `module.exports`.
- **Write JSDoc comments** for complex functions:
  ```javascript
  /**
   * Brief summary of the function.
   * @param {string} param1 - Description of parameter
   * @returns {Promise<Object>} Description of return value
   */

📚 Documentation & Explainability

• Update README.md when new features are added, dependencies change, or setup steps are modified.
• Comment non-obvious code and ensure everything is understandable to a mid-level developer.
• When writing complex logic, add inline comments explaining the why, not just the what.
• Use en-UK spelling conventions throughout documentation.

🧠 AI Behavior Rules

• Never assume missing context. Ask questions if uncertain.
• Always confirm file paths & module names exist before using.
• Never delete or overwrite existing code unless explicitly instructed.
• Always use Context7 for library documentation before suggesting implementations.
• Suggest RAG storage for frequently referenced documentation.
• Use Supabase MCP for database insights and Crawl4AI RAG for content queries.

🎯 RAG Workflow Integration

• When asked about libraries/frameworks: First search Context7, then suggest crawling official docs for RAG storage.
• When implementing features: Query RAG database for relevant examples and best practices.
• When debugging: Use RAG to find similar issues and solutions.
• When researching: Combine web search with RAG queries for comprehensive information.

🔧 Development Workflow

• Always use pnpm for package management.
• Update CHANGELOG.md for all changes.
• Use TypeScript for type safety.
• Follow Nuxt 4 conventions and Vue 3 Composition API patterns.
• Use Tailwind CSS for styling.
• Leverage RAG system for documentation and examples.