claude-code-sync

用途

Claude Code Sync 用于更新一个已经存在的 Claude Code 配置，同时不破坏用户的自定义内容。它是幂等的，因此可以安全地按周、按月或按计划重复运行。

主要能力

重新指纹识别（Re-fingerprint）：扫描仓库，识别自上次设置以来的技术栈变化，例如新框架、新数据库、新 CI/CD 工具。
增量传播（Delta propagation）：将插件规则更新（cc-always.md、cc-patterns.md）推送到仓库的 .claude/rules/ 目录。
分节合并 CLAUDE.md：当技术栈变化时，更新「Build & Test」「Tech Stack」「Key Paths」等章节，保留自定义章节不变。
修复漂移（--fix-drift 标志）：查找与插件默认值发生漂移的配置，例如缺失的 hooks、缺失的 MCP 服务器、过时的技能版本，并进行修复。
传播到子仓库：对于 monorepo，遍历工作区子包，将变更应用到它们的 .claude/ 目录。
搭建 docs/context/（若不存在）：创建由 22 个模板组成的知识库，作为 .claude/ 的补充。
自动安装 LSP：根据技术栈检测缺失的 LSP 服务器，并提供安装命令。
持久化同步状态：将时间戳、插件版本、增量摘要写入 .claude/sync-state.json。

使用方式

CLAUDE.md 分节合并协议

CLAUDE.md 的章节通过 ## 标题识别。同步协议如下：

章节	操作
## Build & Test	替换（根据指纹重新生成）
## Tech Stack	替换
## Key Paths	替换
## Architecture	保留（用户维护）
## Conventions	合并（保留用户新增内容，更新检测到的条目）
## Don't Touch	合并（保留用户新增内容）
## Knowledge Library (Obsidian)	若存在 managed-by-plugin 标记则替换
任何其他章节	原样保留

受管章节带有  标记。未标记的章节永远不会被触碰。

漂移检测（--fix-drift）

将当前状态与插件基线进行比较：

检查项	修复方式
缺失 .claude/rules/cc-always.md	从插件复制
缺失 .claude/rules/cc-obsidian-intro.md	从插件复制
cc-patterns.md 比插件版本旧	提供更新（用户确认）
Hook 脚本路径与注册的 hook 不匹配	协调或移除失效注册
Settings 允许列表包含已移除工具的条目	清理
.mcp.json 中的 MCP 服务器没有对应的安装	警告
.claude/skills/ 中的技能属于旧插件版本	提供替换

永远不会删除用户添加的配置。所有破坏性修复都需要明确确认。

子仓库传播

对于 monorepo（turbo/nx/lerna/pnpm-workspaces），同步会遍历工作区包并执行：

如果包有自己的 .claude/ → 同步它（与根目录相同的协议）。
如果包没有 .claude/ → 创建一个最小的 .claude/，引用根目录的 CLAUDE.md。
为 LOC > 10k 的包生成每个包的 CLAUDE.md 存根。

docs/context/ 搭建

如果 docs/context/ 不存在，则从 22 个模板创建，包括：

docs/context/README.md
docs/context/architecture/overview.md
docs/context/architecture/modules.md
docs/context/conventions/code-style.md
docs/context/conventions/git-workflow.md
docs/context/conventions/testing.md
docs/context/decisions/0001-use-claude-code.md
docs/context/runbooks/deploy.md
docs/context/runbooks/rollback.md
docs/context/glossary.md
...（完整列表可通过 cc_kb_docs_context_templates 获取）

同步状态文件

.claude/sync-state.json 示例：

{
  "version": "1.0",
  "last_synced": "2026-04-16T14:00:00Z",
  "plugin_version": "8.0.0",
  "stack_fingerprint": "node-ts-nextjs-postgres-prisma-jest-vercel",
  "sub_repos_synced": 0,
  "drift_fixed": ["added missing cc-obsidian-intro.md", "pruned 2 dead hook registrations"],
  "next_check_due": "2026-05-16"
}

MCP 委托

需求	工具
技术栈变化后的 hook 包推荐	cc_docs_hook_pack_recommend(signals)
新检测到语言的 LSP 配置	cc_kb_lsp_config(language)
新工作模式的拓扑	cc_docs_team_topology_recommend(...)

适用场景

需要定期更新已有 Claude Code 配置，同时保留用户自定义内容的项目。
技术栈发生变化（新框架、新数据库、新 CI/CD 工具）后，希望同步更新规则、文档和上下文。
使用 monorepo 并需要将配置变更传播到各个子包。
希望检测并修复配置漂移，保持与插件基线一致。

限制与注意事项

反模式

不读取 .claude/sync-state.json 就运行同步 → 无法判断自上次同步以来发生了什么变化。
未经用户确认就使用 --fix-drift → 会破坏看起来像漂移的自定义配置。
在子仓库所有者不知情的情况下同步子仓库 → 会造成意外。
重新运行 setup 而不是 sync → 会覆盖用户自定义内容。

参考

drift-rubric.md — 定义什么算作漂移，什么算作有效的自定义。

暂未提供的信息

关于该工具的收费、价格、具体平台支持范围、安装命令等细节，资料中暂未提供。