Cursor と Claude Code のルールを symlink で共有してはいけない — 生成して同期するSharing rule files between Cursor and Claude Code via symlinks causes…

Cursor and Claude Code

Cursor and Claude Code each support project rule files when used in the same repository. These files hold persistent instructions in Markdown and can be loaded either continuously or according to file paths, making their compatibility important when maintaining instructions for both tools.

Although their rule systems initially appear compatible, their formats differ in ways that can cause silent breakage. Sharing one physical rules directory through a symlink therefore does not provide a reliable common configuration.

YAML frontmatter

Both systems place Markdown files with YAML frontmatter in project directories. Rules can apply continuously or be scoped with glob patterns, but the tools represent and interpret that behavior differently.

Cursor reads rules from .cursor/rules/*.mdc. A rule can use a globs value such as extensions/app/**/*.{ts,tsx,js}, and Cursor determines the rule’s type through a combination of three fields. It also has a mode in which the agent makes a decision based on the description.

Claude Code reads rules from .claude/rules/*.md. Its model is simpler: a rule containing a paths list is loaded only when a matching file is read. A rule without paths is loaded during every session, with the same priority as .claude/CLAUDE.md. Claude Code has no equivalent to Cursor’s description-based agent decision mode.

Symlinks cause breakage

A setup such as linking .cursor/rules to .claude/rules may seem to let both tools use one directory. However, the arrangement breaks along independent compatibility axes.

One explicit incompatibility is the filename extension. Cursor’s rule loader reads only .mdc files and ignores ordinary .md files. Claude Code looks for .md files and ignores .mdc files. Consequently, a shared directory cannot make one unchanged set of files visible to both rule loaders.

Generate and sync

The proposed alternative is to maintain one source of truth and use a small script to generate both required formats. The generated rules can then be synchronized into the directories and extensions expected by each tool.

This approach avoids relying on superficial similarities between the two rule systems. It preserves separate Cursor and Claude Code outputs while allowing their shared instructions to be managed from one source.