最近一直在折腾一个挺实际的工程问题我日常开发同时依赖 Claude Code、zcode 和 WorkBuddy 三个 AI Coding Agent它们各有各的强项但各自的配置方式完全不一样。规则文件放的位置不同技能包的加载路径不同MCP 的注册命令也不同最痛苦的是换一台电脑或者重装一次系统三套配置要重新肝一遍。后来我把它们收敛成一套五层体系用 Git 仓库统一管理所有配置再通过符号链接和初始化脚本分发到各个工具最终实现了在一台机器上配置、在多台机器和三个工具之间同步使用。这篇文章把整套方案的思路和实操步骤完整写出来适合手里同时维护多款 AI 编程助手、并且经常跨设备工作的开发者。1. 为什么需要一套五层体系多个 Agent 并存时的配置混乱1.1 三个工具各自的配置现状先说 Claude Code。它是终端形态的 AI 编程工具配置集中在用户目录下的.claude文件夹里包括CLAUDE.md全局规则、skills技能目录和 MCP 服务配置。项目里还可以放项目级的CLAUDE.md让 Agent 按项目调整行为。这套体系本身已经很完整问题是它只对 Claude Code 自己生效不会自动带给其他工具。zcode 是另一个终端形态的 AI Coding Agent生态上和 Claude Code 有不少重合的地方很多配置格式可以复用但注册方式和默认模型不同。实际使用中 zcode 经常被用来接不同的模型后端比如 DeepSeek、智谱 GLM 这类国内模型服务它和 Claude Code 之间的配置并不能直接双向通用。我遇到过一种很典型的情况Claude Code 里配好的 MCP 服务在 zcode 里需要重新注册一遍zcode 自定义的技能目录Claude Code 也不会主动去读。WorkBuddy 是工作台形态的 AI 工具配置以自定义指令和图形界面为主。它的优点是入口集中、适合日常交互式操作但规则、技能、MCP 的存放位置和 CLI 工具完全不同。同时用三个工具的时候最直观的感受就是“一份规则写三遍一个 MCP 注册三次”。如果你只是偶尔用一两个工具手动同步还能忍一旦开始天天切换着用配置漂移的问题就会变得非常明显。1.2 从“复制粘贴”到“五层体系”的转变一开始我也用过最笨的办法手动同步。写好规则之后复制到 Claude Code 的目录再复制到 zcode 的目录再复制到 WorkBuddy 的规则栏里。短时间看没什么问题一旦规则开始迭代几乎每次改动都会出现“某个工具没同步到新版”的情况。更麻烦的是 MCP 配置每个工具的注册命令不一样复制文件只是第一步还得在工具里执行导入动作。后来我重新梳理了这些配置的本质发现它们虽然分布在不同位置但用途可以归纳成五层环境接入层决定 Agent 能不能启动包括 Node.js、Python、CLI 安装与环境变量。规则配置层决定 Agent 如何理解任务包括全局规则、项目规则、自定义指令。技能扩展层决定 Agent 能执行的复杂能力包括 skills 技能包。工具协议层决定 Agent 能调用哪些外部服务包括 MCP 配置和模型路由。同步维护层决定以上四层如何在多台机器、多个工具之间保持一致。五层各自独立、又逐层依赖。底层没配好上层配置再全也跑不起来。比如 Node.js 版本太低MCP 服务可能根本启动不了规则层没写好技能包给了 Agent 也不知道什么时候该用。所以必须先从环境层开始搭再逐层往上。1.3 这套方案的适用边界这套方案不是让三个工具完全变成同一个工具而是让“公共部分”只维护一份。适合的场景是团队或个人维护多台开发机需要快速 Clone 一份同样好用的 AI 开发环境或者你同时重度使用多个 Agent希望规则、技能、MCP 保持一致。不适合的场景也有比如你只用其中一个工具并且完全不需要跨设备迁移那直接按照官方文档配置就行没必要引入符号链接和同步脚本反而增加复杂度。另外如果公司有强制安全策略不允许在用户目录下维护符号链接这套方案也需要先做合规评估。2. 核心细节解析三个工具配置的差异点与统一路径2.1 全局规则层CLAUDE.md 与自定义指令的兼容Claude Code 的规则体系核心是CLAUDE.md它在用户目录和项目目录两个层级生效。用户目录下的~/.claude/CLAUDE.md是全局规则所有会话都会加载项目根目录下的CLAUDE.md是项目规则优先级更高。zcode 在设计上和 Claude Code 的规则体系兼容所以全局规则文件也可以命名为CLAUDE.md放在对应的 zcode 配置目录里。WorkBuddy 的情况不太一样它通常使用自定义指令Custom Instructions来配置全局行为形式上和 Claude Code 的 Markdown 规则文件有差异但本质上都是给 Agent 提供上下文。我在实操中采用的策略是公共规则写一份global-rules.md放在统一目录里然后让CLAUDE.md和 WorkBuddy 的自定义指令都指向这份公共文件。Claude Code 和 zcode 通过符号链接读取同一个文件WorkBuddy 则通过“导入规则文件”的方式把内容加载进去。这里有一个细节值得注意CLAUDE.md里适合写稳定的行为准则比如代码风格、提交信息规范、测试要求不适合写太临时的任务指令。临时指令每次会话里说清楚就行写进规则文件反而容易让 Agent 在后续会话里过度遵循旧指令。我见过不少人把“这次帮我改一下登录页”这种一次性需求写进CLAUDE.md结果后面每次对话 Agent 都在强调登录页非常蛋疼。2.2 Skills 技能包SKILL.md 的文件结构与加载机制技能包Skills是给 Agent 准备的一组预定义能力核心文件是SKILL.md里面通过 YAML frontmatter 声明技能的名称和描述正文里写清楚执行步骤。Claude Code 的技能目录默认在~/.claude/skills/每个技能一个子目录zcode 也有类似的技能目录加载机制非常相似。我在统一方案里维护一个skills/目录下面每个技能一个子目录结构长这样skills/ ├── code-review/ │ ├── SKILL.md │ ├── prompt.md │ └── scripts/review.py ├── git-commit/ │ ├── SKILL.md │ └── prompt.md └── unittest/ ├── SKILL.md └── scripts/runner.shSKILL.md的 frontmatter 至少要有name和descriptiondescription尤其重要因为 Agent 是靠它来判断什么时候应该调用这个技能的。description 写得太泛比如“用于代码审查”Agent 可能忽视写得太窄比如“只审查 Python 文件”遇到 JavaScript 项目它就不会用了。我的经验是 description 里写清楚触发条件和输入输出例如“当用户要求审查代码改动时使用会扫描当前分支的 diff 并输出问题清单与修改建议”。2.3 MCP 配置一份 JSON 如何在三个工具间复用MCPModel Context Protocol是 Agent 连接外部工具的通用协议Claude Code、zcode、WorkBuddy 都支持通过 MCP 调用文件系统、数据库、浏览器之类的服务。这部分是三个工具差异比较明显的地方注册命令不一样配置文件格式也略有区别。Claude Code 使用claude mcp add命令注册也支持在项目根目录放.mcp.json文件来声明项目级 MCP。zcode 提供了类似命令但服务名和参数格式可能略有差异。WorkBuddy 一般是在设置界面里管理 MCP 服务部分版本支持直接读取 JSON 配置。为了统一我在仓库里维护一份mcp/mcp.json作为所有 MCP 配置的源文件。然后针对每种工具写一条注册命令执行的时候读取这份 JSON逐个添加服务。这样新增一个 MCP 服务时只需要改源文件再跑一下同步脚本三个工具就都会更新。2.4 模型路由让不同工具各用各的模型Claude Code 默认绑定 Anthropic 的模型zcode 则可以配置 DeepSeek、GLM 这类国产模型WorkBuddy 的模型选择通常在图形界面里完成。三个工具的模型配置并不需要强求一致看场景选择就好。我的习惯是Claude Code 保持官方默认zcode 接入 DeepSeek 作为日常轻量任务的主力WorkBuddy 里配置团队常用的模型服务。模型相关的 API Key 都放在models/keys.env文件里启动脚本负责加载而这个文件通过.gitignore排除掉不进入版本库。这样既方便切换模型又不会把密钥提交到 Git 仓库里。3. 实操过程从零搭建一套可复现的五层同步体系3.1 目录结构设计与 Git 仓库初始化我建议把整个体系放在一个独立的目录里比如~/agents-stack/并初始化为 Git 仓库。这样所有配置文件都能纳入版本管理换机器时只要 Clone 仓库再跑一次初始化脚本就行。这是我实际使用的目录结构~/agents-stack/ ├── README.md ├── .gitignore ├── config/ │ ├── global-rules.md # 公共规则源文件 │ ├── claude/CLAUDE.md # Claude Code 规则入口 │ ├── zcode/CLAUDE.md # zcode 规则入口 │ └── workbuddy/ │ └── custom-instructions.md ├── skills/ │ ├── code-review/ │ │ └── SKILL.md │ ├── git-commit/ │ │ └── SKILL.md │ └── unittest/ │ └── SKILL.md ├── mcp/ │ ├── mcp.json # 统一 MCP 配置源文件 │ └── README.md ├── models/ │ ├── keys.env.example │ └── README.md ├── scripts/ │ ├── init.sh # 新机器初始化脚本 │ ├── sync.sh # 配置同步脚本 │ └── backup.sh └── templates/ └── SKILL.md.tpl.gitignore里至少要排除环境变量文件.env .env.* keys.env node_modules/ .DS_Store注意.gitignore的规则要写在仓库初始化之后、第一次提交之前。如果你先把keys.env提交进去了再写.gitignore就晚了历史记录里已经泄露了密钥必须用工具清理或者直接重开仓库。3.2 规则层接入符号链接打通三个工具规则层的核心操作是把公共规则文件通过符号链接挂到各个工具的配置目录。macOS 和 Linux 直接用ln -sfn就行Windows 需要用mklink或者管理员权限的开发者模式。我在init.sh里写的规则层逻辑#!/usr/bin/env bash set -euo pipefail STACK_HOME$HOME/agents-stack CLAUDE_DIR$HOME/.claude ZCODE_DIR$HOME/.zcode WORKBUDDY_DIR$HOME/.workbuddy mkdir -p $CLAUDE_DIR $ZCODE_DIR/skills $WORKBUDDY_DIR # 规则层Claude Code 与 zcode 共用同一份公共规则 ln -sfn $STACK_HOME/config/global-rules.md $CLAUDE_DIR/CLAUDE.md ln -sfn $STACK_HOME/config/global-rules.md $ZCODE_DIR/CLAUDE.md # WorkBuddy 的自定义指令目录按实际版本调整 ln -sfn $STACK_HOME/config/workbuddy/custom-instructions.md \ $WORKBUDDY_DIR/custom-instructions.md这里有几个关键点。第一ln -sfn的-f参数会自动覆盖已有的链接重跑脚本不会报错这个操作是幂等的。第二global-rules.md被两个工具共同引用改文件内容两边都会更新但要注意两边对 Markdown 里 YAML frontmatter 的解析可能有差异所以公共规则文件里我尽量不用复杂的前置元数据纯 Markdown 最稳妥。第三符号链接指向的是文件路径如果路径里有空格记得用双引号包起来。3.3 技能层接入批量创建技能链接技能层同样用符号链接但比规则层多一个步骤需要遍历skills/目录下的所有子目录逐个链接到各个工具的技能目录。如果手动敲命令技能数量一多就很烦而且容易漏我直接用脚本解决。# 技能层遍历 skills 目录为每个技能创建链接 for skill_dir in $STACK_HOME/skills/*/; do skill_name$(basename $skill_dir) ln -sfn $skill_dir $CLAUDE_DIR/skills/$skill_name ln -sfn $skill_dir $ZCODE_DIR/skills/$skill_name # WorkBuddy 若支持技能目录同样链接 if [ -d $WORKBUDDY_DIR/skills ]; then ln -sfn $skill_dir $WORKBUDDY_DIR/skills/$skill_name fi done链接建好之后一定要验证工具真的加载到了技能。Claude Code 可以用claude mcp list或相关命令查看已注册的技能zcode 也有类似的列表命令。我踩过的坑是链接建好之后忘了重启工具的会话结果技能一直不加载。CLI 工具一般在会话启动时扫描技能目录所以修改链接或者更新技能内容之后重启会话是必要的。3.4 MCP 层接入多工具注册与验证MCP 层是三个工具差异最大的地方。我先在mcp/mcp.json里声明所有服务然后写脚本分别注册。这是一个最小化的mcp.json示例{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] }, git: { command: npx, args: [-y, modelcontextprotocol/server-git] } } }实际开发中我常把 Blender MCP 这类特殊服务也写进去方便在做 3D 相关项目时直接调用。但要注意Blender MCP 需要本地先启动 Blender 并开启对应插件MCP 服务更多是建立一个通信通道Blender 没开的时候Agent 调用会失败。注册脚本的关键是处理跨平台命令差异。在 macOS 和 Linux 上MCP 服务经常用npx启动在 Windows 上很多环境需要用npx.cmd才能被 MCP 客户端拉起这是一个非常经典的坑。我的脚本里写了一个平台判断if [[ $(uname -s) MINGW* || $(uname -s) MSYS* ]]; then MCP_RUNNERnpx.cmd else MCP_RUNNERnpx fi注册命令因工具而异Claude Code 用claude mcp addzcode 用类似命令WorkBuddy 则在设置界面里导入mcp.json。注册完成后用工具内置的 MCP 列表命令验证服务状态确保每个服务都显示为 “connected”。3.5 同步脚本编排一台机器配置多台机器生效有了基本的三层链接接下来要处理的是“这台机器配好了另一台怎么同步”。我的方案是在仓库里维护一份完整的配置在任何机器上执行init.sh都能把五层体系建立起来。sync.sh则负责增量更新比如新增技能、调整规则后跑一次同步脚本让本机所有工具生效。我通常这样组织sync.sh#!/usr/bin/env bash set -euo pipefail cd $HOME/agents-stack # 1. 拉取远端最新配置 git pull --rebase # 2. 重跑初始化刷新所有符号链接 bash scripts/init.sh # 3. 重新加载模型环境变量 set -a source models/keys.env set a # 4. 输出当前状态 echo agents-stack 同步完成 echo Claude Code 技能数: $(ls -1 $HOME/.claude/skills | wc -l) echo zcode 技能数: $(ls -1 $HOME/.zcode/skills | wc -l)同步脚本和初始化脚本的边界很重要init.sh负责一次性建立目录、链接和依赖适合新机器sync.sh负责日常更新配置内容适合已经初始化过的机器。如果混在一起每次同步都会重新创建链接虽然通常无副作用但一旦你手动在技能目录里加了临时文件重跑初始化可能会覆盖或者干扰所以我建议还是分开。4. 常见问题与排查技巧实录4.1 WorkBuddy 报 502 write eacces 权限错误这个报错我一开始很困惑“502”像个网络错误实际它是 Node.js 层的 EACCES 写权限错误通常是 WorkBuddy 在尝试写入某个目录时没有权限。最常见的原因是安装时用的用户和运行时的用户不一致或者目录所有权不对。排查步骤很简单先看错误日志里具体是哪个路径写入失败然后用ls -ld检查该目录的所有者权限。在 Linux 或 macOS 上直接把目录所有权调整给当前用户即可sudo chown -R $USER:$USER $HOME/.config/WorkBuddy在 Windows 上右键目录修改安全属性或者检查是否被某个进程锁住。这个报错还有一个隐藏来源如果你用了 OneDrive 或云同步目录文件可能处于“仅在线”状态本地写入会失败把相关目录排除出云同步就能解决。4.2 技能包死活不加载技能包不加载八成是SKILL.md的 frontmatter 格式问题。Claude Code 和 zcode 都要求文件开头有 YAML frontmatter并且必须包含name和description。常见错误是description只写了半句话或者name里用了空格导致解析失败。排查方法是先用工具自带的技能列表命令确认技能是否被扫描到。如果列表里根本没出现多半是路径问题如果出现了但 Agent 不调用多半是description写得太差Agent 判断不到触发条件。还有一种情况是缓存改完SKILL.md之后旧会话还挂着旧内容重启会话通常能解决。4.3 Windows 下 MCP 服务起不来Windows 下 MCP 服务起不来首先要检查npx的路径。很多终端里npx能用但 MCP 客户端拉起子进程时用的是系统的 PATH和你的终端 PATH 可能不一致。解决方式有几种一是把node目录手动加到系统 PATH二是使用npx.cmd的完整路径三是在 MCP 配置里直接指定 Node 脚本的绝对路径。还有一种情况是防火墙弹窗阻止了 MCP 服务监听的端口。部分 MCP 服务走 stdio 通信不涉及端口但有些走 SSE 或 HTTP 的服务需要监听本地端口第一次运行杀毒软件或防火墙会弹窗没点允许的话服务起不来而日志里又看不出明显错误。4.4 zcode 与 Claude Code 的版本差异导致配置失效zcode 虽然兼容部分 Claude Code 的规则和技能格式但版本迭代速度不同偶尔会出现“这个配置在 Claude Code 里正常、在 zcode 里被忽略”的情况。我遇到过的实例是某些较新的规则语法只被 Claude Code 识别zcode 直接跳过但也不报错排查起来很隐蔽。我的建议是公共配置尽量使用两边都支持的稳定语法别用太新的特性。遇到疑似配置失效时用最小化排除法先只留一条规则确认 zcode 能识别再逐步加内容。这比盯着配置文档猜快得多。4.5 符号链接在 Git 仓库中的特殊处理符号链接本身在 Git 仓库里也受版本控制但不同平台的链接类型不一样。macOS 和 Linux 上符号链接天然支持Windows 上默认的 Git 配置可能不保留符号链接导致 Clone 仓库后所有链接变成普通文本文件里面内容是一段路径字符串。解决方案是在 Windows 上执行git config core.symlinks true并且开启开发者模式。如果仓库已经在多台机器之间来回 Clone更保险的做法是脚本生成链接而不是把链接直接提交到仓库。我的仓库里其实没有提交符号链接所有链接都是由init.sh在运行时建立的这样就完全规避了跨平台链接兼容性问题。5. 落地这套方案之后的几点体会这套五层体系跑通之后我最大的感受是“配置漂移”这件事基本被消灭了。以前三个工具各自为政我经常得记着这个规则改过没、那个技能在 WorkBuddy 里要不要更新。现在公共部分只有一份源文件所有工具都通过链接指向它改完即生效不用再维护三份副本。还有一个意外的收获因为所有配置进了 Git 仓库我有机会做配置版本回滚。有一次我把全局规则改得太激进Agent 开始强制所有代码用某种风格同事的项目直接编译不过。我立刻回滚到上一个提交问题马上消失。这在以前的手动同步模式下基本不可能快速做到。如果你也要搭这套体系我建议从最简单的规则层开始不要一开始就铺开所有技能和 MCP。先把global-rules.md和一个技能跑通确认三个工具都能读到再逐步加内容。配置这种东西滚动的轮子跑起来以后保持简单才是长期能维护的关键。最后再分享一个小技巧每个技能目录里都放一个README.md记录这个技能在三个工具里的测试情况。你可能会觉得多余但过两个月再回来改配置时这份记录能帮你省下大量重新试错的时间。