AI Development

This guide provides comprehensive information on using Cursor, an AI-powered code editor, to accelerate development of the SCAYLE Storefront Application. Cursor provides context-aware code suggestions, refactoring assistance, and automated code generation while following the project's established patterns and best practices.

Why Use Cursor for SCAYLE Storefront Development?

The SCAYLE Storefront Application is a sophisticated e-commerce platform built with modern technologies. Cursor AI provides intelligent assistance that helps developers of all skill levels work effectively with this codebase through 13+ project-specific rules that ensure code quality and consistency.

Core Benefits

Accelerated Development

• Generate boilerplate code for components, composables, and RPC methods instantly.
• Refactor existing code while preserving functionality and patterns.
• Write comprehensive tests following project conventions.
• Get instant answers about architecture and implementation patterns.

Consistent Quality

• Automatic adherence to Vue 3 Composition API, Nuxt 3, TypeScript, and Tailwind CSS best practices.
• Built-in validation against project standards before code review.
• Proper error handling, loading states, and accessibility compliance.
• Maintain consistency across the codebase regardless of developer experience.

Interactive Learning

• Understand complex patterns through AI-generated examples with explanations.
• Learn SCAYLE-specific concepts like RPC methods and basket management.
• Discover performance optimization and accessibility best practices.
• Validate approaches against project standards automatically.

Benefits by Developer Level

Junior Developers

• Focus on business logic while AI handles syntax and boilerplate.
• Learn Vue 3 Composition API and TypeScript patterns through correct implementations.
• Build confidence by experimenting with AI assistance before asking seniors.

Mid-Level Developers

• Implement features quickly following established patterns.
• Expand knowledge of advanced TypeScript and Nuxt 3 optimization techniques.
• Generate comprehensive test coverage efficiently.

Senior Developers

• Ensure team follows architectural patterns through AI-enforced standards.
• Scale knowledge across distributed teams with consistent AI-generated examples.
• Identify deviations from project standards during code review.

External Developers & Agencies

• Understand SCAYLE architecture quickly without deep platform knowledge.
• Follow best practices automatically, reducing dependency on SCAYLE support.
• Minimize rework and technical debt from the start.

SCAYLE Storefront Advantages

Project-Specific Intelligence

• Cursor Rules tailored for SCAYLE Storefront patterns and @scayle/storefront-nuxt conventions.
• Understanding of e.g., RPC methods, session handling and basket workflows.

Framework Expertise

• Nuxt 3 server-side rendering, Vue 3 Composition API, Tailwind CSS utilities, and TypeScript type safety.

Quality Assurance

• Consistent code style, proper error handling, WCAG accessibility compliance, and comprehensive test coverage.

By leveraging Cursor AI, teams deliver high-quality SCAYLE storefronts faster with fewer bugs and more maintainable code — regardless of individual experience levels.

Cursor Rules

The project includes a comprehensive set of Cursor Rules located in .cursor/rules/ that guide the AI to follow project-specific conventions. These rules are automatically loaded by Cursor and provide context-aware guidance when writing code.

Available Rule Files

The following rule files are available to guide AI-assisted development:

These rules ensure that AI-generated code follows the project's established patterns and maintains consistency across the codebase.

Getting Started with Cursor

1. Install Cursor

Download and install Cursor from cursor.sh. Cursor is available for macOS, Windows, and Linux.

2. Open the Project

bash

Copy

Alternatively, open Cursor and use File > Open Folder to open the Storefront Application directory.

3. Verify Cursor Rules

Cursor will automatically detect and load the rules from .cursor/rules/. You can verify this by:

• Opening the Cursor settings
• Navigating to the "Cursor Rules" section
• Confirming that the project rules are loaded

4. Add Documentation References

Enhance Cursor's context awareness by adding relevant documentation sources:

1. Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
2. Navigate to Features > Docs
3. Click Add new doc;
4. Add the following documentation URLs (one at a time):
   • SCAYLE Storefront: https://scayle.dev/
   • Nuxt 3: https://nuxt.com/docs/3.x/
   • Vue 3: https://vuejs.org/guide/
   • Tailwind CSS: https://v3.tailwindcss.com/docs/
   • Vitest: https://vitest.dev/guide/
   • Playwright: https://playwright.dev/docs/
5. Depending on your selected CMS provider:
   • Storyblok: https://www.storyblok.com/docs
   • Contentful: https://www.contentful.com/developers/docs/
6. Wait for each to complete indexing.

Once indexed, you can reference these documentation sources using @Docs in the Cursor chat.

Understanding Cursor Chat Modes

Cursor provides three distinct chat modes, each optimized for different development scenarios. Understanding when to use each mode will help you work more effectively with the SCAYLE Storefront Application.

Ask Mode

Best for quick questions, explanations, and code reviews.

For more details check the official Cursor documentation for "Modes > Ask".

Use in SCAYLE Storefront for:

• Understanding Code: Ask questions about existing patterns and implementations.
• Code Review: Get feedback on specific code sections.
• Quick Fixes: Solve specific problems without modifying files.
• Learning: Understand SCAYLE-specific concepts.

Characteristics:

• Provides answers and code suggestions in the chat panel.
• Does not automatically modify files.
• Good for exploration and learning.
• Fast responses for quick questions.
• Lightweight context, ideal for multiple quick queries.

Context Management:

• Keep questions focused and specific
• Start fresh after 3-5 prompts if switching topics
• Use @filename to provide relevant context
• Good for creating plans that can be saved to files

Plan Mode

Best for multi-file changes and feature implementation.

For more details check the official Cursor documentation for "Planning".

Use in SCAYLE Storefront for:

• Feature Implementation: Build complete features across multiple files.
• Refactoring: Make coordinated changes across components.
• Bug Fixes: Fix issues that span multiple files.
• Adding Tests: Create comprehensive test coverage.
• Planning: Create detailed implementation plans before coding.

Characteristics:

• Can edit multiple files simultaneously.
• Shows proposed changes before applying.
• Maintains context across related files.
• Best for coordinated, multi-file changes.

Context Management:

• Provide clear, detailed requirements upfront.
• List all files that need changes using @filename .
• Review proposed changes before accepting.
• Start fresh context for each major phase of work.
• Use @PLAN_FILE.md to reference saved plans.

Agent Mode

Best for complex tasks requiring autonomous planning and execution.

For more details check the official Cursor documentation for "Modes > Agent".

Use in SCAYLE Storefront for:

• Complex Features: Implement features requiring research and planning.
• Architecture Changes: Make significant structural improvements.
• Investigation: Debug complex issues.
• Documentation: Generate comprehensive documentation.

Characteristics:

• Autonomous decision-making and planning.
• Can run terminal commands and tests.
• Iterates on solutions until completion.
• Best for complex, multi-step tasks.

Context Management:

• Most context-intensive mode - monitor for context overload.
• Give high-level goals and let agent plan the approach.
• Monitor progress and provide feedback.
• Consider breaking into phases if output quality degrades.
• Watch for signs of hallucination or drift from requirements.

Choosing the Right Mode

Best Practices by Mode

Ask:

• Keep questions focused and specific
• Reference specific files or components
• Use for learning and understanding
• Good for code review feedback

Plan:

• Provide clear, detailed requirements
• List all files that need changes
• Review proposed changes before accepting
• Use for coordinated multi-file work

Agent:

• Give high-level goals and constraints
• Let the agent plan the approach
• Monitor progress and provide feedback
• Use for complex, autonomous tasks

Best Practices for Using Cursor

1. Be Specific: Provide clear, detailed requirements in your prompts.
2. Use Context: Keep relevant files open and use @ references to provide context.
3. Reference Patterns: Point to existing code that demonstrates desired patterns with @filename.
4. Plan Before Implementing: For complex changes, create detailed plans in Ask mode first.
5. Manage Context: Keep tasks small and independently verifiable. Start fresh after 3-5 prompts.
6. Iterate Thoughtfully: Start simple and refine, but know when to start over with a better prompt.
7. Review Everything: Always review and test AI-generated code before committing.
8. Follow Rules: Trust the Cursor Rules to maintain code quality and consistency.
9. Learn Continuously: Use Cursor as a learning tool to understand the codebase better.
10. Break Down Tasks: Divide complex features into phases with fresh context per phase.

Avoid Assumptions and Guesswork

Copy

Ask Specific Questions

Instead of vague requests, provide specific context and requirements:

• ❌ Bad:
  test

  Copy
• ✅ Good:
  Copy

Reference Existing Patterns

Point Cursor to existing code when asking for similar functionality:

• ❌ Bad - No Reference Point:
  Copy
• ✅ Good - Clear Reference to Existing Pattern:
  Copy

Request Explanations

Ask Cursor to explain complex code or patterns:

• ❌ Bad - Too Broad:
  Copy
• ✅ Good - Specific Questions:
  Copy
• ✅ Good - Contextual Comparison:
  Copy

Iterative Refinement

Start with a basic implementation and refine iteratively:

• ❌ Bad - Everything at Once:
  Copy
• ✅ Good - Step-by-Step Approach:
  Copy
  
  Then after reviewing:
  Copy
  
  Then after reviewing:
  Copy

Leverage Context

Cursor understands the files you have open. Open related files before asking questions:

• Open the component you're working on
• Open related composables or utilities
• Open test files when writing tests

Code Review Assistance

Ask Cursor to review code for improvements:

• ❌ Bad - Generic Review Request:
  Copy
• ✅ Good - Performance Review:
  Copy
• ✅ Good - Code Standards Review:
  Copy
• ✅ Good - Accessibility Review:
  Copy
• ✅ Good - Security Review:
  Copy

Common Use Cases

Creating New Components

• ❌ Bad - Vague Requirements:
  Copy
• ✅ Good - Detailed Specifications:
  Copy

Implementing RPC Methods

• ❌ Bad - Missing Context:
  Copy
• ✅ Good - Complete Implementation with API Specs:
  Copy

Writing Unit Tests

• ❌ Bad - No Specific Target:
  Copy
• ❌ Bad - Too Vague (Will Generate Too Many Tests):
  Copy
• ✅ Good - Explicit Test Cases to Avoid Bloat:
  Copy
• ✅ Good - Targeted Test Requirements:
  Copy
• ✅ Good - Extending Existing Tests:
  Copy

Refactoring Code

• ❌ Bad - No Context or Goals:
  Copy
• ✅ Good - Clear Refactoring Objectives:
  Copy
• ✅ Good - Performance Optimization:
  Copy

Adding Translations

• ❌ Bad - Unclear Scope:

Copy

• ✅ Good - Specific Translation Scope:
  Copy
• ✅ Good - Adding New Translation Keys:
  Copy

Debugging Issues

• ❌ Bad - Too Generic:
  Copy
• ✅ Good - Specific Problem Description:
  Copy
• ✅ Good - With Context and Expected Behavior:
  Copy
• ✅ Good - Performance Issue:
  Copy

Tips for Maximum Productivity

1. Use Cursor's Chat Feature

• Press Cmd+L (macOS) or Ctrl+L (Windows/Linux) to open the chat panel.
• Ask questions about the codebase, request code generation, or get explanations.

2. Use Cursor's Inline Edit

• Press Cmd+K (macOS) or Ctrl+K (Windows/Linux) to edit code inline.
• Select code and ask Cursor to refactor, improve, or fix it.

3. Use Cursor's Codebase Search

• Press Cmd+Shift+F (macOS) or Ctrl+Shift+F (Windows/Linux) to search the codebase.
• Ask Cursor to find examples of specific patterns or implementations.

4. Use @ File References Effectively

Cursor's @ reference system is powerful for providing precise context:

Reference Specific Files:

Copy

Reference Multiple Files for Pattern Context:

Copy

Reference Folders for Broader Context:

Copy

Reference Cursor Rules:

Copy

Reference Plan Files Across Phases:

Copy

Combine Multiple References:

Copy

Best Practices for @ References:

• Use specific file paths, not wildcards
• Reference pattern files when asking for similar functionality
• Combine with indexed docs using @Docs when available
• Reference plan files to maintain continuity across chat sessions

5. Reference Documentation with @Docs

If you've indexed documentation (see Getting Started), you can reference it using @Docs in the Cursor chat:

Copy

Or combine with file references:

Copy

Tip: The @Docs feature allows Cursor to search through indexed documentation. Combine this with opening relevant codebase files or manually tagging via @filename references for the most effective assistance.

6. Maintain Context

Keep relevant files open in tabs to provide Cursor with better context for your questions.

7. Follow the Rules

The Cursor Rules in .cursor/rules/ are designed to maintain code quality and consistency. Trust the AI's suggestions when they reference these rules.

8. Verify Generated Code

Always review AI-generated code before committing:

• Check that imports are correct
• Verify TypeScript types are accurate
• Ensure Tailwind classes are appropriate
• Test that the functionality works as expected

9. Learn from the AI

Use Cursor as a learning tool to understand patterns and best practices used in the codebase.

Common Pitfalls to Avoid

Don't

• Accept code without reviewing it for correctness and style.
• Ask Cursor to generate entire features without breaking them into smaller tasks.
• Ignore linter errors or TypeScript warnings in generated code.
• Use generated code that doesn't follow the project's established patterns.
• Forget to test AI-generated code thoroughly.
• Continue iterating on a bad start - recognize when to reset.
• Let Cursor decide test cases - explicitly specify which cases to test.
• Keep adding context indefinitely - start fresh after 3-5 prompts.

Do

• Break large tasks into smaller, manageable pieces.
• Review and understand all generated code before using it.
• Ask follow-up questions if something is unclear.
• Reference existing patterns and components when requesting new code with @filename.
• Use Cursor's suggestions as a starting point and refine as needed.
• Start fresh with a refined prompt if first output is off-track.
• Explicitly list test cases to avoid test bloat.
• Create plans for complex changes before implementing.

Managing Context for Complex Changes

Effective context management is crucial for maintaining output quality. Know when to iterate, when to reset, and when to use Plan Mode for complex features.

Context Overload: When to Start Fresh

Signs to Start a New Chat:

• Responses drift from requirements or ignore Cursor Rules
• Hallucinations, contradictions, or degrading output quality
• After 3-5 prompts on same topic or 2-3 failed refinement attempts
• When switching to unrelated tasks

Iterate When:

• Good foundation, measurable progress, minor refinements needed

Reset When:

• Off-track responses, wrong patterns, no improvement after 2-3 attempts

Reset Strategy:

• Analyze what went wrong → Start fresh chat → Add @ file references → Be more specific

Example:

• ❌ Don't
  Copy
• ✅ Do
  Copy

Using Plan Mode for Large Features

Cursor's Plan Mode autonomously researches your codebase and creates structured to-do lists for multi-step tasks.

Activation: Press Shift + Tab or let Cursor suggest it for complex tasks

How It Works:

1. Researches codebase and finds relevant files
2. Reviews indexed docs and Cursor Rules
3. Asks clarifying questions
4. Generates Markdown to-do list with file references

Working with Plans:

• Edit the generated plan directly (Markdown with checkboxes)
• Save optionally: Save this plan as FEATURE_PLAN.md
• Review each change before accepting
• Note: Manual edits to saved files may not sync—start fresh Plan Mode session if needed

Best Practices:

1. Clear Goals:
   1. ✅ "Add product comparison with side-by-side display and session persistence"
   2. ❌ "Add comparison"
2. Reference Patterns: Use @app/composables/useWishlist.ts to help Cursor find relevant code
3. Review First: Edit to-dos to match project conventions before execution
4. Phase Large Features: Execute Phase 1 → Review → Fresh Plan Mode for Phase 2

Example:

Copy

Continuing Across Sessions:

Copy

Troubleshooting:

• Not activating: Update Cursor, press Shift + Tab, check Agent mode enabled
• To-dos not updating: Restart Cursor or start fresh Plan Mode session
• Edits not syncing: Edit in Plan Mode interface, not saved .md files

Troubleshooting

Cursor isn't following the project rules

Problem: Generated code doesn't match project conventions or patterns.

Solutions:

• Verify the .cursor/rules/ directory exists and contains the rule files.
• Restart Cursor to reload the rules.
• Explicitly reference the rule file in your prompt using @.cursor/rules/vue-components.mdc.
• Use @ to reference existing code that follows the correct pattern.

Generated code has errors

Problem: AI-generated code contains TypeScript errors, linting issues, or runtime errors.

Solutions:

• Provide more context about the specific requirements.
• Use @filename to reference existing working examples in your prompt.
• Ask Cursor to fix the specific error you're encountering.
• Break down complex requests into smaller, more manageable tasks.
• If errors persist after 2-3 attempts, start fresh with a refined prompt.

AI suggestions don't match the project style

Problem: Generated code uses different patterns or conventions than the rest of the codebase.

Solutions:

• Reference the specific Cursor Rule file using @.cursor/rules/imports.mdc.
• Use @filename to point to existing code that demonstrates the desired pattern.
• Provide explicit style requirements in your request.
• Open related files to provide better context for the AI.

Cursor isn't producing good outputs

Problem: Code doesn't match expectations or follow patterns despite clear prompts.

Solutions:

• Add more context with @ file references to pattern examples.
• Reference Cursor Rules explicitly: @.cursor/rules/rpc-methods.mdc.
• Break into smaller, clearer tasks with specific requirements.
• Start fresh chat with refined prompt instead of continuing to iterate.
• Verify you're using the right chat mode (Ask, Plan, or Agent) for the task.

Too many test cases generated

Problem: LLM generates unnecessary permutation tests, creating test bloat.

Solutions:

• Explicitly list exact test cases in your prompt: "Test ONLY these 4 cases: 1) ... 2) ... 3) ... 4) ..."
• Add instruction: "DO NOT test all permutations of parameters."
• Specify: "ONLY test the N cases listed above."
• Use @ to reference existing test file for assertion patterns: @app/composables/useWishlist.test.ts.

Context seems too large / responses degrading

Problem: Hallucinations, off-script responses, or quality degradation after multiple prompts.

Solutions:

• Start fresh chat after 3-5 prompts, especially for unrelated tasks.
• Summarize previous work when starting new chat if needed.
• Break large changes into phases with fresh context per phase.
• Use @ to reference plan files to maintain continuity: @FEATURE_PLAN.md.
• Close unnecessary open files to reduce context size.

Cursor is slow or unresponsive

Problem: Long wait times for responses or the editor becomes sluggish.

Solutions:

• Close unnecessary files and tabs to reduce context size.
• Break large requests into smaller, focused questions.
• Restart Cursor if performance issues persist.
• Check your internet connection if using cloud-based features.
• Consider switching to Ask mode for simpler queries instead of Agent mode.

By following these guidelines and best practices, you'll be able to leverage Cursor AI effectively to accelerate your development workflow while maintaining high code quality and consistency with the SCAYLE Storefront Application's established patterns.