1. 项目概述与核心价值

如果你和我一样，同时在使用 Claude Code 和 Cursor 这两款 AI 编程助手，那你一定遇到过这个烦人的问题：同一个项目，在两边的配置、规则、技能和计划文件总是不同步。在 Claude Code 里精心调教好的 docs/rules/ 规则，到了 Cursor 里得手动复制到 .cursor/rules/ ；在 Cursor 里写的 .cursor/plans/ 项目计划，回到 Claude Code 的 docs/plans/ 下又得重新整理一遍。更别提全局的 MCP 服务器配置了，两边各有一套，维护起来简直是灾难。这种割裂感严重影响了开发效率，也让项目的一致性难以保证。

今天要聊的 cursor-claude-compat 项目，就是专门为解决这个痛点而生的。它不是什么复杂的平台或服务，而是一个用 Bash Shell 编写的轻量级工具包，核心目标就一个： 在 Claude Code 和 Cursor 之间，实现项目配置和全局设置的自动化、无缝同步 。简单来说，它帮你把在两款工具间手动搬运配置文件的重复劳动，变成了一键执行的自动化流程。

这个工具的价值，对于深度依赖 AI 编程助手的开发者来说，是立竿见影的。它不仅仅是复制文件，更重要的是理解了两者配置格式的差异并做了智能转换。比如，Claude Code 的规则文件（ docs/rules/*.md ）和 Cursor 的规则文件（ .cursor/rules/*.md ）在元数据（Frontmatter）格式上就有细微差别，工具会自动处理这些转换，确保规则在两边的 AI 模型中都能被正确识别和执行。这背后体现的是对两款工具生态的深入理解，而不仅仅是简单的文件操作。

2. 核心设计思路与同步策略解析

2.1 为什么选择 Bash Shell 作为实现语言？

看到这个项目是用 Bash Shell 脚本实现时，你可能会有点意外。毕竟现在各种现代化的脚本语言选择很多。但深入想一下，这个选择其实非常精妙，体现了工具设计的务实性。

首先， 极致的轻量化和零依赖 。Bash 是 *nix 系统（包括 macOS 和 Linux）以及 WSL 环境下的原生组件，无需安装任何额外的运行时或解释器。对于这样一个定位为“基础设施工具”的项目来说，最大限度地降低使用门槛和潜在冲突是第一要务。你只需要 git clone 然后运行安装脚本，几乎不可能遇到“环境配置失败”这种劝退新手的坑。

其次， 完美的场景契合度 。这个工具的核心操作是什么？是文件系统的增删改查、路径解析、符号链接创建、JSON 配置合并。这些恰恰是 Shell 脚本的“主场优势”。用 Bash 来实现，代码直观（无非是 cp , ln , mkdir , jq 等命令的组合），执行效率高，而且调试起来也相对简单——你完全可以在命令行里手动执行其中的某条命令来验证逻辑。

最后， 与目标环境的无缝集成 。无论是 Claude Code 还是 Cursor，它们作为桌面应用，其技能（Skills）或命令（Commands）的触发机制，底层往往就是调用一个外部脚本。一个健壮的 Bash 脚本，可以很容易地被封装成两者的技能，通过快捷键或命令面板调用，用户体验非常流畅。如果换成 Python 或 Node.js，你首先得确保用户机器上有对应的环境，这反而增加了不确定性。

当然，选择 Bash 也意味着要更小心地处理跨平台兼容性（比如 macOS 和 GNU 核心工具集的细微差异）、错误处理以及脚本的健壮性。从项目的源码看，它通过 set -euo pipefail 等严格模式，以及大量的路径检查和备份机制，很好地弥补了 Bash 在这些方面的天生不足。

2.2 分层同步策略：项目级与全局级

工具的核心同步逻辑被清晰地分为了两层： 项目级同步 和 全局级同步 。这个划分非常符合实际的使用场景。

项目级同步 ，关注的是你手头正在开发的 单个代码仓库 。它的同步源通常是项目根目录下的 docs/ 文件夹（Claude Code 的约定），目标则是 Cursor 约定的 .cursor/ 文件夹。同步的内容包括：

• 计划（Plans） : docs/plans/*.md <-> .cursor/plans/*.md
• 技能（Skills） : docs/skills/*.md <-> .cursor/skills/*.md
• 规则（Rules） : docs/rules/*.md <-> .cursor/rules/*.md
• MCP 配置 : .mcp.json <-> .cursor/mcp.json

这里的设计亮点在于“同步方法”的智能化。对于计划和技能，工具会优先尝试创建 符号链接（Symbolic Link） 。这意味着你在一边修改文件，另一边会实时看到变化，真正实现了“单点维护，两端生效”。只有当创建符号链接失败（例如在部分 Windows 环境或没有权限时），它才会降级为文件复制。而对于规则文件，由于涉及格式转换，所以采用“转换后复制”的方式。

全局级同步 ，管理的则是你开发者账户层面的配置，通常位于用户家目录（ ~ ）。它主要处理一个关键配置： MCP（Model Context Protocol）服务器列表 。Claude Code 将其定义在 ~/.claude.json 文件的 mcpServers 字段中，而 Cursor 则使用 ~/.cursor/mcp.json 文件。这个同步的核心是“安全合并”：它会读取 Claude 的配置，然后智能地合并到 Cursor 的配置里，确保不覆盖你已在 Cursor 中手动配置的其他 MCP 服务器，并且会过滤掉 Claude 特有的、Cursor 不支持的字段（如 type , envFile 等）。

一个重要提示 ：根据项目说明，Cursor 其实已经原生支持读取 ~/.claude/ 目录下的大部分配置，如 CLAUDE.md 、 agents/ 、 skills/ 和 settings.json 。因此，工具明智地没有对这些路径进行重复同步，避免了不必要的操作和潜在冲突。这体现了开发者对两个生态的熟悉程度，不做无用功。

2.3 配置驱动与状态管理

为了实现灵活和可追溯的同步，工具引入了两个 JSON 配置文件：

1. 项目配置 ( .cursor/claude-compat.json ): 保存在每个项目内部，记录了该项目下源路径和目标路径的映射、采用的同步方法、上一次同步的时间及状态。这保证了每个项目都可以有自己的独立配置，互不干扰。
2. 全局配置 ( ~/.cursor/claude-compat-global.json ): 保存在用户目录，管理全局 MCP 配置的同步状态。

这种配置驱动的设计好处很多。首先，它使得同步行为是可预测和可重现的。其次，通过记录 lastSync 和 lastSyncStatus ，为未来实现增量同步或状态检查提供了基础。最后，配置文件本身是纯文本的 JSON，高级用户可以手动编辑以应对一些特殊场景，增加了工具的灵活性。

3. 从零开始：安装与首次配置实操

3.1 环境准备与工具安装

在开始之前，我们需要确保系统满足基本要求。打开你的终端（Terminal），执行以下命令进行快速检查：

# 检查 Bash 版本（需要 4.0+）
bash --version

# 检查核心工具是否可用
which ln mkdir realpath

如果你的系统是标准的 macOS 或 Linux 发行版，这些通常都已预装。对于 Windows 用户， 强烈建议通过 WSL2 使用 Ubuntu 等 Linux 发行版 来运行此工具，以获得最佳体验。纯 Windows 环境下的符号链接支持和路径处理会复杂很多。

接下来是安装 cursor-claude-compat 本身。过程非常简单：

# 1. 克隆仓库到本地，建议放在一个固定的工具目录，比如 ~/Tools/
git clone https://github.com/tochitatebuilding/cursor-claude-compat.git ~/Tools/cursor-claude-compat
cd ~/Tools/cursor-claude-compat

# 2. 运行安装脚本
./installer/install.sh

这个 install.sh 脚本做了几件关键事情：

• 将项目中的 技能（Skill）文件 复制到 Cursor 能识别的全局技能目录（通常是 ~/.cursor/skills-cursor/ ）。
• 将 规则（Rule）文件 复制到 Cursor 的全局规则目录。
• 使得你可以在任意 Cursor 项目中，通过输入 /sync-claude-docs 或 /sync-claude-global 命令来触发对应的同步技能。

安装完成后，你可以验证一下技能是否安装成功。在 Cursor 中打开任意项目，按下 Cmd/Ctrl + K 打开命令面板，输入 /sync ，你应该能看到 sync-claude-docs 和 sync-claude-global 这两个技能选项。

3.2 在项目中首次运行同步

现在，我们找一个同时包含 Claude Code 的 docs/ 配置和 Cursor 的 .cursor/ 配置的项目来测试。如果没有，可以临时创建一个测试目录，并手动建立几个文件。

在 Cursor 中打开目标项目，然后通过命令面板执行 /sync-claude-docs 技能。如果你是第一次在该项目运行， 工具会进入交互式设置模式 。

这时，脚本会在终端输出类似以下的信息，并等待你的确认：

首次运行，未找到项目配置文件。
检测到以下可能的源目录：
1) /path/to/your/project/docs
请确认源目录是否正确（输入编号或完整路径），或直接按回车使用上述检测结果：

这里有一个非常重要的实操细节 ：工具检测的是 docs 目录。但你的 Claude Code 配置可能并不在项目根目录的 docs 下，或者你的项目结构比较特殊。因此，不要盲目按回车。你应该根据自己项目的实际情况，输入正确的路径。例如，如果你的配置在 specs/ai/ 目录下，就输入这个完整路径。

确认源目录后，工具会生成 .cursor/claude-compat.json 配置文件，并立即开始首次同步。你会看到它逐项处理计划、技能、规则和 MCP 配置，并标明使用的是创建符号链接（ [SYMLINK] ）还是复制（ [COPY] ）以及格式转换（ [CONVERT] ）。

首次同步成功后，下次再运行 /sync-claude-docs ，它就会直接读取配置文件进行快速同步，不再询问。

3.3 全局配置同步实操

项目级配置搞定后，我们来同步全局的 MCP 设置。同样在 Cursor 的命令面板中，执行 /sync-claude-global 技能。

这个脚本会做以下几件事：

1. 定位你的 ~/.claude.json 文件（Claude Code 的全局配置）。
2. 定位或创建 ~/.cursor/mcp.json 文件（Cursor 的 MCP 配置）。
3. 使用 jq 工具，提取 ~/.claude.json 中的 mcpServers 对象。
4. 执行“安全合并”：将 Claude 的 MCP 服务器配置合并到 Cursor 的配置中。 “安全”体现在两点 ：一是如果某个服务器 ID 在两边的配置中都存在，Cursor 原有的配置优先级更高，不会被覆盖；二是会过滤掉 Claude 特有的、Cursor 无法识别的字段。
5. 将合并后的结果写回 ~/.cursor/mcp.json 。
6. 在 ~/.cursor/claude-compat-global.json 中记录本次同步状态。

关键依赖提示 ：全局同步功能 强烈依赖 jq 这个命令行 JSON 处理器 。如果系统没有安装 jq ，脚本会输出警告并跳过 MCP 同步。在 macOS 上，你可以通过 brew install jq 安装；在 Ubuntu/Debian 上，使用 sudo apt install jq 。务必确保它已安装，这是实现智能 JSON 合并的基础。

4. 高级用法与命令行参数详解

虽然通过 Cursor 技能菜单调用非常方便，但工具也提供了完整的命令行接口，让你能在终端中直接运行，这对于自动化集成、调试或了解内部机制非常有帮助。

4.1 项目同步脚本 ( sync.sh ) 参数解析

进入工具安装目录的 src/scripts/ ，我们可以直接调用 sync.sh 。

cd ~/Tools/cursor-claude-compat/src/scripts/

# 查看所有可用选项
./sync.sh --help

核心参数如下：

• --yes 或 -y : 非交互模式 。这是我最常用的参数之一。在 CI/CD 流水线或者你确定要同步时，使用这个参数可以跳过所有确认提示。它的默认行为是：如果目标文件已存在，会先创建备份（在 ~/.cursor/.claude-compat-backup/ 下），然后覆盖。
• --skip-existing : 跳过已存在的文件 。如果你只想同步新增的文件，而不想触动任何已有文件（无论其内容是否变化），就使用这个选项。这在部分同步或试探性同步时有用。
• --force 或 -f : 强制覆盖 。与 --yes 类似，但语义更强。它会直接覆盖已存在的文件，同样也会先创建备份。注意， --force 不会跳过格式转换等操作，会对所有目标文件执行动作。
• --dry-run 或 -n : 模拟运行 。这是另一个极其重要的调试和验证参数。它不会实际执行任何文件操作，而是会详细打印出它会做什么：哪些文件会被链接、复制、转换或合并。在第一次对一个重要项目运行同步前， 务必先执行一次 --dry-run ，确认它的行为符合你的预期。
• --no-backup : 不创建备份 。不推荐使用。备份是数据安全的重要防线，除非你百分百确信操作无误且磁盘空间极度紧张，否则请保留备份功能。
• --help 或 -h : 显示帮助信息。

一个典型的自动化脚本用例 ：假设我想在每天开始工作前，自动同步所有项目的配置，并且我完全信任源文件，可以这样写一个 cron job 或启动脚本：

#!/bin/bash
# 遍历我所有的重要项目目录
PROJECT_ROOT="/path/to/my/projects"
for dir in "$PROJECT_ROOT"/*/; do
  if [ -f "$dir/.cursor/claude-compat.json" ]; then
    echo "Syncing project: $(basename "$dir")"
    # 非交互模式运行同步，并跳过已存在的文件（避免不必要的覆盖）
    (cd "$dir" && ~/Tools/cursor-claude-compat/src/scripts/sync.sh --yes --skip-existing)
  fi
done

4.2 全局同步脚本 ( sync-global.sh ) 参数解析

sync-global.sh 的参数与 sync.sh 基本一致，因为它的操作对象是全局文件，所以 --skip-existing 这类参数的意义略有不同，主要体现在合并策略上。

• --dry-run : 对于全局同步，这个参数尤其有用。它会展示将从 ~/.claude.json 中提取出哪些 MCP 服务器配置，并模拟如何合并到 ~/.cursor/mcp.json 中，让你清晰看到合并结果，避免配置冲突。
• --force : 在全局同步中， --force 会确保执行合并操作，即使 ~/.cursor/mcp.json 已经存在。合并逻辑依然是“Cursor 优先”，但会强制将 Claude 中独有的新服务器添加进去。

4.3 备份与恢复机制剖析

工具的数据安全设计值得称道。无论是项目级还是全局同步，只要涉及覆盖现有文件的操作，它都会自动创建备份。

备份位置 ：所有备份都集中存放在 ~/.cursor/.claude-compat-backup/ 目录下。这个目录是隐藏的，符合 Unix 下工具配置的惯例。

备份策略 ：

1. 每次覆盖操作前，会将目标文件或目录复制到备份区，并以时间戳命名（例如 mcp.json.2026-02-03T12-00-00 ）。
2. 工具会自动管理备份数量， 只保留最新的 5 份备份 ，更旧的会自动删除。这既保证了能回滚到近期几个版本，又避免了备份文件无限膨胀占用磁盘空间。

手动恢复示例 ：假设一次同步后，你发现 .cursor/rules/ 下的某个重要规则文件被意外更改了，你可以从备份中手动恢复。

# 1. 列出可用的备份
ls -la ~/.cursor/.claude-compat-backup/

# 2. 找到包含你需要文件的那个时间戳备份目录，假设是 project_xyz_rules.2026-02-03T10-30-00
# 3. 复制回目标位置
cp ~/.cursor/.claude-compat-backup/project_xyz_rules.2026-02-03T10-30-00/my-rule.md /path/to/project/.cursor/rules/

这种基于时间戳的备份清晰明了，比复杂的版本管理更简单直接，非常适合这个工具的场景。

5. 常见问题排查与实战经验分享

在实际使用中，你可能会遇到一些问题。下面是我在深度使用过程中总结的一些典型场景和解决方案。

5.1 同步失败或没有效果的排查步骤

问题现象 ：在 Cursor 中执行了 /sync-claude-docs ，但 .cursor/ 目录下的文件没有任何变化，或者技能执行后报错。

排查思路 ：

1. 检查配置文件 ：首先确认项目根目录下是否生成了 .cursor/claude-compat.json 。如果没有，说明是首次运行且可能交互确认环节出了问题。直接删除这个文件（如果存在），重新运行同步技能，并仔细查看终端的提示信息，正确输入源目录路径。
2. 使用 --dry-run 模式 ：在终端中，进入项目目录，手动运行工具脚本并加上 --dry-run 参数。这会打印出详细的执行计划。

   cd /path/to/your/project
   ~/Tools/cursor-claude-compat/src/scripts/sync.sh --dry-run
   

   观察输出：
   • 它是否找到了正确的源文件？（检查 Source: 路径）
   • 它计划对每个文件执行什么操作？（ [SYMLINK] , [COPY] , [CONVERT] , [MERGE] ）
   • 是否有任何错误或警告信息？（例如“源文件不存在”）
3. 检查文件权限 ：工具需要读取源文件和写入目标目录的权限。确保你对项目目录有读写权限。在极少见的情况下，如果目标目录 .cursor/ 的权限设置异常（如属于 root），也会导致失败。
4. 检查符号链接支持 ：如果工具一直尝试创建符号链接但失败，并回退到复制，可能是环境不支持。在 WSL 中访问 Windows 文件系统（ /mnt/c/... ）时，创建符号链接可能需要开发者模式或特殊配置。这种情况下，复制模式也能工作，只是无法实现实时双向更新。

5.2 规则文件格式转换的细节与坑点

这是工具的一个核心智能点，也是容易出问题的地方。

Claude Code 规则格式 (在 docs/rules/ 下)：

# 规则标题
- **触发器**: `@code-review`
- **严格度**: 高
- **适用范围**: 所有Python文件

这里是具体的规则描述和行为...

Cursor 规则格式 (在 .cursor/rules/ 下)：

---
name: 规则标题
description: 这里是具体的规则描述和行为...
triggers:
  - @code-review
strictness: high
scope:
  - "*.py"
---

（规则的具体描述可以继续在这里写）

工具需要将前者转换为后者。这个转换大部分时候是可靠的，但你需要关注：

• 元数据提取 ：工具会尝试从 Claude 格式的 Markdown 中提取 **触发器** 、 **严格度** 等列表项，并映射到 Cursor 的 Frontmatter 字段。如果你的 Claude 规则文件没有严格使用 **字段名**: 值 的格式，转换可能会丢失信息。
• 内容合并 ：Claude 规则中“字段列表”之后的内容，会被全部移到 Cursor 规则的 description 字段和 Frontmatter 之后的主体部分。
• 实操建议 ：在首次同步后， 务必人工检查一下 .cursor/rules/ 下生成的规则文件 。打开看看 Frontmatter 是否完整，描述是否准确。如果转换不理想，你有两个选择：一是优化你的 Claude 规则文件格式，使其更规范；二是在 Cursor 侧手动调整一次生成的文件，之后工具在“复制”模式下会保留你的修改（如果用符号链接，则修改会同步回源文件）。

5.3 全局 MCP 配置合并冲突处理

当 ~/.claude.json 和 ~/.cursor/mcp.json 中配置了同一个 MCP 服务器（通过相同的 id 或 name 识别），但配置不同时，工具的合并策略是 “Cursor 配置优先” 。

这意味着，Cursor 中已有的配置会被保留，Claude 中的配置不会被合并进去。这通常是你期望的行为，因为 Cursor 是你当前正在使用的环境，其配置应该具有最终决定权。

但是，如果你 希望用 Claude 的配置覆盖 Cursor 的 ，工具没有提供直接参数。你需要手动处理：

1. 先备份当前的 ~/.cursor/mcp.json 。
2. 临时删除或重命名 ~/.cursor/mcp.json 。
3. 运行 sync-global.sh 。此时由于目标文件不存在，工具会将 Claude 的配置作为基础创建新文件。
4. 再将你希望保留的、Cursor 特有的其他服务器配置，手动合并到新文件中。

这个过程略显繁琐，但也反映了工具“安全第一”的设计哲学。在大部分情况下，“Cursor 优先”的策略避免了误覆盖导致 Cursor 功能异常的风险。

5.4 在团队协作中如何使用

cursor-claude-compat 本质上是一个本地工具，它的配置文件（ .cursor/claude-compat.json ）是保存在每个项目中的。这为团队协作提供了便利。

推荐的工作流 ：

1. 团队统一约定 AI 辅助开发的配置存放于 docs/ 目录下（Claude Code 格式）。这是“源真理”。
2. 将 .cursor/claude-compat.json 文件 纳入版本控制 （如 Git）。这样，任何克隆该项目的团队成员，在本地首次运行同步工具时，都会使用相同的源路径和同步方法配置。
3. 团队成员本地安装 cursor-claude-compat 工具。
4. 任何成员在更新了 docs/plans/ , docs/skills/ , docs/rules/ 下的文件后，除了提交代码，也应该运行同步工具，更新本地的 .cursor/ 目录，并可以考虑将 .cursor/ 目录添加到 .gitignore 中，避免个人化的 Cursor 配置被提交。

这样，团队就拥有了一个统一的、版本化的 AI 助手配置源，同时每个成员可以在本地拥有适配 Cursor 的、实时同步的配置副本。

6. 项目维护、扩展与安全考量

6.1 理解项目的开源理念与 AI 使用声明

cursor-claude-compat 来自 Tochitatebuilding，一家利用 AI 改造传统仓储地产业务的公司。他们将内部工具开源，本身就体现了一种务实和分享的精神。在项目 README 中，他们明确声明了会使用 AI 辅助进行 Issue 回复、生成 PR 和优化文档，并承诺所有 AI 生成内容都会经过维护者审核。

这对我们使用者意味着什么？ 首先，你可以更放心地使用和贡献，因为项目的沟通和演进是透明的。其次，如果你在 GitHub 上提交 Issue，可能会收到 AI 辅助生成的初步回复，这能加快问题处理速度。但最终决策和代码合并权仍在人类维护者手中。这种“AI 辅助，人类决策”的模式，是当前很多高效开源项目的常见实践。

6.2 如何参与贡献与自定义

如果你觉得这个工具很好用，并发现了一些 Bug，或者有改进的想法，完全可以参与贡献。项目遵循标准的 GitHub 工作流：Fork -> 修改 -> 提交 Pull Request。

几个潜在的贡献方向 ：

• 支持更多配置项 ：目前主要同步计划、技能、规则和 MCP。也许 Claude Code 或 Cursor 未来会新增其他配置目录。
• 增强转换逻辑 ：比如更智能、更健壮的规则文件格式转换器。
• 提供图形界面（GUI） ：对于不习惯命令行的用户，一个简单的图形配置界面会很有帮助。
• 编写更多文档和示例 ：比如针对不同编程语言（Python、JavaScript、Go）的最佳实践规则模板。

进行本地自定义 ：如果你不想修改上游代码，只是想调整工具在本地的行为，最好的方式是修改你本地的技能脚本副本。技能文件安装在 ~/.cursor/skills-cursor/sync-claude-docs/ 目录下，你可以直接编辑这里的 SKILL.md 或底层的 sync.sh 脚本。但请注意，下次你通过 install.sh 更新工具时，这些修改可能会被覆盖。

6.3 安全与隐私提醒

这是一个处理你开发配置的工具，其中可能包含一些个人信息或项目敏感信息（尽管 MCP 配置主要是服务器地址）。从安全角度，请注意：

1. 脚本权限 ：确保你从官方仓库克隆代码，并检查安装脚本 installer/install.sh 的内容。它只会进行文件复制操作，不会执行任何远程下载或可疑命令。
2. 配置文件内容 ：同步的 ~/.claude.json 和 ~/.cursor/mcp.json 可能包含访问本地或内部 MCP 服务器的令牌（Tokens）。这些信息只会留在你的本地磁盘上，工具不会将其发送到任何远程服务器。
3. 备份文件 ：备份目录 ~/.cursor/.claude-compat-backup/ 同样包含这些配置的历史版本。请像对待你的 SSH 密钥一样，保护好这个目录的访问权限。

总的来说， cursor-claude-compat 是一个设计精巧、解决实际问题的“螺丝刀”式工具。它没有追求大而全，而是精准地切入了一个特定场景，用简单的技术方案提供了巨大的便利性。它的成功在于对开发者工作流的深刻理解，以及稳健的实现。如果你同时是 Claude Code 和 Cursor 的用户，花十分钟设置一下它，可能会为你节省未来数十小时的手动同步时间。