Skip to content

Creating Cursor Rules Repositories

This guide explains how to create and structure your own cursor rules repository for use with AI Scaffolding.

Understanding these details is essential if you want to customize cursor rules for your organization or share them with others.

Cursor Rules Integration

The external repository integration in AI Scaffolding works through a simple mechanism:

  1. Configure the repository URL and branch (Configuration)
  2. When you run the cursor command, AI Scaffolding will:
    • Clones the specified repository at the specified branch
    • Extracts the cursor rules
    • Installs them into your project
    • Cleans up temporary files

This means you can maintain your cursor rules in a separate repository, potentially with different access controls and contributors than your main project.

Repository

File Structure

Any cursor rules repository should follow this file structure:

cursorrules-repo/
├── rules/                        # Main directory containing cursor rules
│   ├── .cursorrules              # Main cursor rules file
│   ├── .cursorrules.base         # Base rules applied to all packages
│   ├── .cursorrules.typescript   # TypeScript-specific rules
│   ├── hardhat/                  # Package-specific rules
│   │   └── .cursorrules          # Rules specific to Hardhat package
│   ├── nextjs/                   # Package-specific rules
│   │   └── .cursorrules          # Rules specific to Next.js package
│   └── vite/                     # Package-specific rules
│       └── .cursorrules          # Rules specific to Vite package
├── README.md                     # Documentation for your rules
├── LICENSE                       # License file
└── version                       # Version tracking file

Guidelines

  1. All rule files inside the rules folder should follow the pattern .cursorrules*
  1. Subdirectories within the rules folder are named after the specific packages they should be used with.
  1. Each package-specific directory contains its own .cursorrules file with instructions tailored to that package
  2. Version is a simple text file that contains the version of the cursor rules.

Understanding the Process

The cursor rules files contain specific instructions for the AI in markdown format. When AI Scaffolding imports cursor rules, it follows this process:

  1. Scans the rules directory and identifies the relevant rule files based on the packages you've selected
  2. Merges the content from these files into a single .cursorrules file
  3. Processes this merged file as a Handlebars template, allowing for dynamic customization based on your project configuration
  4. Writes the final processed .cursorrules file to the root of your newly created project

This approach enables powerful customization where your cursor rules can adapt to the specific packages, settings, and configurations of each project you create with AI Scaffolding.

Handlebars Templating

Since AI Scaffolding processes the cursor rules files as Handlebars templates, you can include dynamic content that changes based on the project configuration:

.cursorrules
# Project Guidelines
This is a {{projectType}} project using {{framework}} and follows these conventions:
 
{{#if usesTypeScript}}
- Use TypeScript for all new code
- Follow the TSConfig settings in the root directory
{{/if}}
 
{{#if usesNextjs}}
- Follow the Next.js App Router patterns
- Place page components in the app/ directory
{{/if}}

Best Practices

  1. Version your rules: Use semantic versioning for your rules repository
  2. Document extensively: Include a detailed README explaining your rules and how they should be used
  3. Test your rules: Verify your rules work correctly with different project configurations
  4. Keep dependencies minimal: Avoid relying on external resources in your rules
  5. Update regularly: Keep your rules updated with the latest best practices and technologies

Example: Package-Specific Rule

Here's an example of a package-specific rule file for Hardhat:

.cursorrules
# Hardhat Development Guidelines
 
- Always use the hardhat-deploy pattern for deployments
- Write tests for all smart contracts
- Include natspec documentation for all public and external functions
- Use OpenZeppelin contracts where possible instead of writing your own
- Follow the gas optimization patterns in our style guide

By following these guidelines, you can create a custom cursor rules repository that enhances the AI-assisted development experience for your team using AI Scaffolding and Cursor.

References

Here are some external references that can help you build your own cursor rules:

2025 Applied Blockchain