使用软链接解决LLM配置文件同步问题

又是一篇在 draft 目录里躺了不知几个月的post，趁今天晚饭后有时间，去图书馆把草稿润色完发表出来。标题即摘要，已经了解的可以退出观看了；TL;DR -> [[Soft Link & Hard Link#解决方案| See this chapter]]

Problems

当前 Coding Agent 生态正处在一个 勃勃生机、万物竞发 的阶段。不同厂商与工具在设计理念与实现方式上各有取舍，尚未形成统一的标准。

这种情况也不罕见，甚至十分合理。XDG Base Directory 规范^[1]要求软件的配置文件放在 $HOME/.config 目录，但也不是人人都听它的（例如Claude Code）

借用Michael Livshits^[2] 在文章 Every CLI coding agent, compared 中总结的表格，可以看出仅在 Project Memory 上，就有 CLAUDE.md、AGENTS.md、GEMINI.md、.clinerules 等多种命名。

Note: OpenCode 基本兼容了 Claude Code 规范；Claude Code 兼容 AGENTS.md 要等到猴年马月了 Feature Request: Support AGENTS.md. · Issue #6235 · anthropics/claude-code

解决方案

如果团队内同时使用多个 Agent，就得手动维护多份 AGENTS.md/SKILL.md/... 不方便。解决办法很简单——为主配置文件创建 soft link(也叫symbolic link/symlink)：

# 以 AGENTS.md 为主文件，为其他 Agent 创建软链接ln -s ./AGENTS.md ./CLAUDE.mdln -s ./AGENTS.md ./GEMINI.md

# 注意 mklink 参数顺序与 ln -s 不同# Ref: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/mklinkmklink CLAUDE.md AGENTS.md

之后无论编辑 AGENTS.md 还是 CLAUDE.md，修改的都是同一份文件，消除了维护成本

注意：使用git追踪 symlink 本身；避免将 symlink 指向仓库外部路径，否则其他人 clone 后会失效。

原理

Soft link 本质上是一个特殊文件，使用 eza 查看文件信息，发现 CLAUDE.md 的文件类型是 l(symlink)，AGENTS.md 文件类型是.

$ eza --long AGENTS.md CLAUDE.md.rw-r--r--@ 3.5k gjx 14 Mar 17:02 AGENTS.mdlrwxr-xr-x@    - gjx 15 Mar 18:33 CLAUDE.md -> ./AGENTS.md

当应用调用 open("CLAUDE.md", O_RDONLY) 时，内核在解析路径过程中会检测到 CLAUDE.md 是一个符号链接（symlink），读取其目标（./AGENTS.md），继续解析直到找到非 symlink 的最终 inode，然后为该 inode 创建内核级的 open file 对象并返回文件描述符。之后对该 fd 的 read(fd, buffer, size) 操作会直接返回目标文件的内容；对上层应用完全透明。

解析路径的过程可以参考如下由 LLM 生成的 Python 代码，

唉，Coding 能力 & 阅读非 Python 代码能力均已退化🗿

import osMAX_SYMLINK_DEPTH = 40def real_path(path):    path = os.path.abspath(path)    depth = 0    while True:        if depth > MAX_SYMLINK_DEPTH:            raise RuntimeError("symlink loop or too many levels")        if not os.path.islink(path):            return path        target = os.readlink(path)        if os.path.isabs(target):            path = os.path.abspath(target)        else:            parent = os.path.dirname(path)            path = os.path.normpath(os.path.join(parent, target))        depth += 1# 用法示例if __name__ == "__main__":    print(real_path("CLAUDE.md"))

 $ python ./symlink_parser.py/Users/gjx/Library/CloudStorage/OneDrive-Personal/Documents/posts/AGENTS.md

Symlink 其他用途

Symlink 在开发工具链中无处不在：

• pnpm：通过 symlink 实现 content-addressable store，同一个包只在磁盘上存一份，所有项目通过链接共享
• bun：类似地使用 symlink 优化 node_modules 的磁盘占用，参考我的这篇文章，使用 bun link 简化开发 Library/Blog 主题的工作流
• Homebrew：将安装在 Cellar/ 下的程序 symlink 到 /opt/homebrew/bin/，可以很方便的实现「切换软件版本」需求

此外，针对前文提到的「XDG Base Directory 规范并未完全普及」的问题，也可以通过 symlink 将散落在 ~/.config/、~/ 各处的配置文件集中到一个 git 仓库统一管理。感兴趣可以查看我介绍 dotbot 的文章