CursorAI/How To/Share Cursor Project Rules Across Repositories and Users

• How to share CursorAI/Project Rules across multiple projects and users

  • Overview

    • Cursor project rules are a unique set of Metaprogramming tools. A set of related cursor project rules define the CursorAI Agent Mode's Agentic System, each encapsulating a particular aspect of the overall capabilities of that system.
    • It is important for Cursor's users be able to share and collaborate on cursor project rules in a modular, open-source manner where possible, or on teams where that is not feasible, sharing private cursor project rules across the team or across certain scopes of repositories, while maintaining the ability to version the rules and obtain updates to the rules after they have been tested.
    • In my opinion, Cursor Project Rules may deserve a new type of Package Manager that allows for rapid prototyping, that is, that allowed one to install a particular version of a "package" of rules, and then modify the library on the fly in response to observed behavior, and have the option to easily offer those contributions back to the source as a merge request. The proposal for such a package manager is out of the scope of this page, however. This guide focuses on how to achieve collaborative sharing of versioned, vetted project rules across repositories and users.

  • Prerequisites

    • Your project must be a git repository
    • You must have git installed
    • You must have SSH access to GitHub configured (for GitHub-hosted rules)
    • Cursor version 0.47 or later (which supports project rules in subdirectories) - see CursorAI/Project Rule/Test/Agent/✅/Find MDC/in Subfolder

  • Steps (adapted from Person/codekiln/GitHub/logseq-cursor-rules README.md)

    • 1. Create the rules directory if applicable

      • First ensure you have a .cursor/rules directory in your project:
        • bash

          mkdir -p .cursor/rules

    • 2. Add the rules as a git submodule

      • Add the repository containing your cursor project rules as a submodule:
        • bash

          git submodule add <repository-url> .cursor/rules/<rules-directory-name>

        • Example:
          • bash

            git submodule add git@github.com:username/my-cursor-rules.git .cursor/rules/my-cursor-rules

    • 3. Commit the changes

      • bash

        git add .cursor/rules/<rules-directory-name> .gitmodules
        git commit -m "feat: add cursor project rules as submodule"

  • For Existing Projects

    • If you're cloning a project that already has cursor rule submodules:
      • bash

        git submodule update --init --recursive

  • Updating the Rules

    • To update to the latest version of the rules:
      • bash

        cd .cursor/rules/<rules-directory-name>
        git pull origin main
        cd ../../..
        git add .cursor/rules/<rules-directory-name>
        git commit -m "chore: update cursor project rules"

  • Alternatives (Not recommended)

    • Copy and paste

      • Of course, it's possible to copy and paste cursor project rules from one repository into the .cursor/rules directory of each project or user. Over time, though, there will be drift between the most up-to-date version of the rules from the upstream repository and the one that was copied in.

    • Use OS/File/System/Link/Soft

      • While I have not yet documented it under CursorAI Project Rule Tests, I have found that Cursor does follow rules that are symlinked under .cursor/rules. To achieve similar behavior to git submodules, one can clone a repository of project rules and then symlink in the rules.

      • Downsides

        • Extra Tooling

          • This approach opens up the need for a set of tools that can "deploy" a set of symlinks from another repository into the cursor rules.
          • To use cursor project rules in a systematic way, one would want a tool to deploy them systematically.

        • Issues with cross-platform compatibility

          • Symlinks work differently in Linux than in Windows.
          • Symlinks are only stable in git if they are relative paths. If relative paths are made from projects/my-project/.cursor/rules/link-*.mdc to projects/my-centralized-project-rules/link-*.mdc, then all users who edit my-project who wish to use the rules in my-centralized-project-rules will need to place it as a sibling directory to my-project. This is a hard requirement that may or may not make sense for all users.
            • On may work around this by using two symlinks - the first would go from projects/my-project/.cursor/rules/link-*.mdc to projects/my-project/user-rules/link-*.mdc, where my-project/user-rules is added to .gitignore and not in version control, treating it as a directory similar to .vscode or .idea for IDEA, which is allowed to vary between users. It would be a user's responsibility to create symlinks to the rules in this directory on their machine. However, again, there's a need for standardized tooling.