统一管理本地 Code Agent 全局规则：从 AGENTS.md 到 Synology Drive 同步

dong4j2026-05-132026-05-13

random-pic-api

统一管理本地 Code Agent 全局规则：从 AGENTS.md 到 Synology Drive 同步

最近一段时间，我在本地同时使用了几类 Code Agent 工具，比如 Codex CLI、Claude Code、opencode、Gemini CLI，再加上平时也会用 Cursor。这些工具确实能显著提升开发效率，但用得越多，一个问题也越明显：

Agent 很强，但如果没有稳定的规则约束，它很容易“过度发挥”。

比如：

让它给一个实现建议，它直接开始改代码；
明明只是一个小需求，它生成一堆复杂抽象；
原本只需要局部修改，它顺手重构了一大片；
新增文件没有注释，没有上下文说明；
不同工具之间行为不一致，同一个需求在 Claude Code、Codex、Gemini 里表现完全不同；
一个工具记得“先给方案再修改”，另一个工具上来就落盘。

这些问题单看都不大，但在日常工程开发里会不断累积成摩擦：你需要反复提醒、反复纠偏、反复 review AI 生成的无关改动。

于是我今天做了一次整理：把多个 Code Agent 工具的全局规则统一起来，放到一个可同步的全局规则文件中，再通过软链接分发给各个工具使用。

背景：Code Agent 不是越主动越好

我一直觉得，使用 Claude Code、Codex 这类工具时，最危险的不是它“不会写代码”，而是它“太会写代码”。

很多时候我们需要的是：

先理解需求；
给出实现方案；
明确修改范围；
等待确认；
再做最小必要修改；
修改后说明改了什么，以及如何验证。

但默认情况下，Agent 很容易把“建议”理解成“执行”，把“实现一个点”扩大成“重构一片”。

这类问题本质上不是单纯的模型能力问题，而是 上下文和行为规则缺失。

这次触发我重新整理全局规则的契机，是看到 Andrej Karpathy 关于 Claude coding workflow 的讨论。他提到自己大量使用 Claude Code，并且软件工程工作流正在发生变化。围绕这条讨论，社区也出现了一些把这些经验沉淀成规则文件的项目，例如 andrej-karpathy-skills，它将核心原则总结为：Think Before Coding、Simplicity First、Surgical Changes、Goal-Driven Execution。这些原则正好对应我在使用 Code Agent 时遇到的几个问题：不先思考、过度复杂化、修改范围过大、缺少可验证目标。

所以我决定不再依赖每次对话时临时提醒，而是把这些约束沉淀成一份长期生效的全局规则。

问题：多个工具，各有一套规则文件

现在本地 Code Agent 工具越来越多，每个工具都有自己的“全局指令”或“项目规则”机制。

我目前主要整理了这几类：

工具	全局规则文件	项目级规则文件
Codex CLI	`~/.codex/AGENTS.md`	`./AGENTS.md`
Claude Code	`~/.claude/CLAUDE.md`	`./CLAUDE.md` / `./.claude/CLAUDE.md`
opencode	`~/.config/opencode/AGENTS.md`	`./AGENTS.md`
Gemini CLI	`~/.gemini/GEMINI.md`	`./GEMINI.md`
Cursor	Settings → Rules → User Rules	`.cursor/rules/*.mdc` / `AGENTS.md`

Codex CLI 支持通过 AGENTS.md 给 Agent 提供规则；Claude Code 使用 CLAUDE.md 作为 memory / instruction 文件；Cursor 有 User Rules、Project Rules，也支持 AGENTS.md；Gemini CLI 则使用 GEMINI.md 做分层上下文管理。

这些机制本身都很合理，但问题是：

如果每个工具都维护一份规则，最终一定会漂移。

今天在 Codex 里加了一条“修改前先确认”，明天忘了同步到 Claude Code；后天给 Gemini 加了“必须添加注释”，opencode 又没有。久而久之，每个工具表现都不一致。

这不是我想要的。

我希望所有本地 Code Agent 至少遵循同一套基础行为原则。

思考：全局规则应该管什么？

在整理之前，我先区分了两类规则。

第一类：个人全局偏好

这些规则应该对所有项目、所有工具都生效，例如：

始终使用中文回复；
每次回复开头和结尾称呼用户：【dong4j】；
用户提出需求时，先给实现方案并征求确认；
未确认前不要修改代码或配置；
如果用户明确要求“直接修改 / 现在写入 / 添加到文件”，可以执行，但仍需先说明修改范围；
代码必须添加必要注释；
新增完整代码文件时，必须补充模块级说明、关键类 / 函数说明、复杂逻辑注释；
遇到不明确的指令，必须指出并给出建议；
保持最小变更，避免无关重构；
不要自动执行 git commit、git push、git reset 等操作，除非明确要求。

这些是我的个人工作流偏好，适合放到全局规则里。

第二类：项目级规则

这些规则应该放在具体仓库里，例如：

当前项目使用 Java 21；
构建命令是 mvn clean verify；
Controller 不写业务逻辑；
DTO / Entity / VO 不允许混用；
项目 commit message 必须使用英文；
某个目录有特定架构约束。

这类规则不应该写到全局文件里，否则会污染其他项目。

所以最后的原则是：

全局规则管行为，项目规则管上下文。

全局规则约束 Agent “怎么做事”；项目规则告诉 Agent “这个项目是什么”。

规则加载方式：不是简单覆盖，而是上下文合并

在整理过程中，我顺手梳理了一下几个工具的规则加载方式。

Codex CLI

Codex 使用 AGENTS.md。全局文件通常是：

1	~/.codex/AGENTS.md

项目里可以放：

1	./AGENTS.md

Codex 会按层级加载规则：全局规则、项目根目录规则、子目录规则等会组成一条 instruction chain。也就是说，它不是简单“项目覆盖全局”，而是把多个规则文件一起作为上下文提供给 Agent。OpenAI Codex CLI 本身是运行在本地机器上的轻量 coding agent，适合这种本地规则注入方式。

Claude Code

Claude Code 使用：

1	~/.claude/CLAUDE.md

项目中可以放：

1 2	./CLAUDE.md ./.claude/CLAUDE.md

Claude Code 会把这些 memory / instruction 文件加载进上下文。全局规则适合放个人偏好，项目规则适合放仓库约束。

opencode

opencode 使用：

1	~/.config/opencode/AGENTS.md

项目级规则依然是：

1	./AGENTS.md

opencode 是一个开源 AI coding agent，定位也是本地 / 终端 / IDE 中的代码代理工具。它也支持通过规则文件给 Agent 提供上下文。

Gemini CLI

Gemini CLI 使用：

1	~/.gemini/GEMINI.md

项目级：

1	./GEMINI.md

Gemini CLI 的 GEMINI.md 是分层上下文机制。官方文档里 /memory show 可以显示当前拼接后的完整 hierarchical memory，/memory reload 可以重新扫描并加载所有 GEMINI.md，/memory add 会把内容追加到全局 ~/.gemini/GEMINI.md。

它的层级大致是：

1
2
3

~/.gemini/GEMINI.md
项目根目录/GEMINI.md
子目录/GEMINI.md

Gemini CLI 的文档也明确提到，context 是按层级加载的，可以用全局文件放通用规则，用项目和子目录文件放更具体的规则。

Cursor

Cursor 稍微特殊一点。

它有：

1	Cursor Settings → Rules → User Rules

也有项目级：

1	.cursor/rules/*.mdc

并且支持 AGENTS.md。Cursor 官方文档将规则分成 Project Rules、Team Rules、User Rules，并支持用这些规则配置持久化指令。

不过 Cursor 的全局 User Rules 更适合在 UI 里配置，不像其他 CLI 工具有一个明确的全局 Markdown 文件路径。因此这次统一方案里，Cursor 没有用软链接，而是把同一套规则手动放到 User Rules 中。

方案：自建统一全局规则文件

为了避免每个工具各维护一份规则，我新建了一个统一规则文件：

1	$HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

这个文件放在 Synology Drive 的同步目录里。

这样做有几个好处：

所有工具共用同一份规则源
规则变更只改一个文件
其他 Mac 可以通过群晖同步自动获得同一套规则
避免不同工具规则漂移
可以长期演进这份规则，把它当作个人 Code Agent 工作流的基础设施

目录大致是：

1
2
3

$HOME/Library/CloudStorage/SynologyDrive-driver/AI/
└── global/
    └── agents.md

实施：用软链接连接到各个工具目录

统一规则文件准备好后，各工具目录下不再维护真实文件，而是通过 ln -s 指向这份统一文件。

Codex CLI

mkdir -p ~/.codex

rm -f ~/.codex/AGENTS.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.codex/AGENTS.md

最终效果：

1	~/.codex/AGENTS.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

Claude Code

Claude Code 的文件名是 CLAUDE.md，但内容可以和 agents.md 共用：

mkdir -p ~/.claude

rm -f ~/.claude/CLAUDE.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.claude/CLAUDE.md

最终效果：

1	~/.claude/CLAUDE.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

opencode

mkdir -p ~/.config/opencode

rm -f ~/.config/opencode/AGENTS.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.config/opencode/AGENTS.md

最终效果：

1	~/.config/opencode/AGENTS.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

Gemini CLI

Gemini CLI 的文件名是 GEMINI.md：

mkdir -p ~/.gemini

rm -f ~/.gemini/GEMINI.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.gemini/GEMINI.md

最终效果：

1	~/.gemini/GEMINI.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

Cursor

Cursor 的全局规则在 UI 里配置：

1	Cursor Settings → Rules → User Rules

所以 Cursor 这里暂时不能像 CLI 工具一样用软链接统一，只能把同一份规则内容复制进去。

项目级规则仍然可以使用：

1	.cursor/rules/*.mdc

或者：

AGENTS.md

当前统一后的结构

现在本地大致变成了这样：

Synology Drive
└── AI
    └── global
        └── agents.md
              ↑
              │
              ├── ~/.codex/AGENTS.md
              ├── ~/.claude/CLAUDE.md
              ├── ~/.config/opencode/AGENTS.md
              └── ~/.gemini/GEMINI.md

用一条命令可以检查：

ls -l ~/.codex/AGENTS.md
ls -l ~/.claude/CLAUDE.md
ls -l ~/.config/opencode/AGENTS.md
ls -l ~/.gemini/GEMINI.md

输出中应该都能看到它们指向同一个 Synology Drive 里的 agents.md。

我的全局规则核心内容

这次统一的规则主要围绕几个目标。

1. 始终中文回复

1 2	- 请始终使用中文回复，除非用户明确要求使用其他语言。 - 技术术语可以保留英文，但解释说明应使用中文。

这个主要是为了减少来回切换语言的成本。

2. 明确用户称呼

1 2	- 用户称呼为：dong4j。 - 每次回复的开头和结尾都必须称呼用户：`【dong4j】`。

这条看起来有点形式化，但对我来说可以快速确认当前 Agent 是否真的加载了全局规则。

如果某个工具回复时没有带这个称呼，基本可以判断规则没有生效，或者被项目规则冲掉了。

3. 先方案，后修改

1
2
3

- 用户提出需求时，必须先给出实现方案并征求确认。
- 只有在用户确认后，才能修改代码、配置或执行落盘操作。
- 如果用户明确要求“直接修改”“现在写入”“添加到文件”等落盘动作，可以执行该明确指令，但仍需先说明修改范围。

这是最重要的一条。

Code Agent 的默认行为往往偏主动，但在真实项目中，我更希望它像一个谨慎的协作者：

先理解；
再规划；
再确认；
最后执行。

尤其是涉及架构、配置、依赖、数据库、Git 操作时，不应该直接动手。

4. 必须添加必要注释

- 代码必须添加必要注释。
- 新增完整代码文件时，必须补充模块级说明、关键类说明、关键函数 / 方法说明，以及必要的复杂逻辑注释。
- 注释应解释“为什么这样做”和“关键约束是什么”，避免只重复代码本身。
- 不允许只提交裸代码。

我不希望 AI 只给出一坨“能跑”的代码。

尤其是新增完整文件时，至少应该有：

这个模块是做什么的；
类的职责是什么；
关键方法的输入输出和约束；
复杂逻辑为什么这么写。

否则后面维护成本会很高。

5. 遇到不明确需求必须指出

1	- 遇到不明确、不完整或可能存在多种理解的指令时，必须告知用户不明确之处，并给出合理建议。

LLM 很容易在上下文不足时“脑补”。

这条规则的目标是让它承认不确定，而不是为了完成任务强行猜。

6. 保持最小变更

1
2
3

- 保持最小变更，避免无关重构。
- 不要擅自扩大需求范围。
- 不要引入与当前任务无关的依赖、抽象或架构调整。

这条对应 Karpathy 提到的 Surgical Changes 思路：修改应该像外科手术一样精确，只动该动的地方。andrej-karpathy-skills 也把 Surgical Changes 作为核心原则之一，用来减少 Agent 修改不该修改的代码。

为什么要放到 Synology Drive？

我现在不只一台 Mac。

如果全局规则只放在本机 ~/.codex/AGENTS.md、~/.claude/CLAUDE.md 里，那么换一台机器就要重新配置一遍，而且后续更新也要手动同步。

放到 Synology Drive 后，规则文件本身就变成了一个同步资产。

好处是：

新 Mac 只需要创建软链接；
后续修改一次，多台机器同步；
不依赖某个工具自己的云同步；
可以把这份规则纳入自己的知识库和备份体系；
后续也可以扩展出 project-template/AGENTS.md、cursor-rules/、skills/ 等目录。

这比每个工具各配一份更可控。

多设备初始化脚本

后续换新 Mac 时，可以准备一个初始化脚本：

#!/usr/bin/env bash
set -euo pipefail

GLOBAL_RULE="$HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md"

if [ ! -f "$GLOBAL_RULE" ]; then
  echo "全局规则文件不存在: $GLOBAL_RULE"
  exit 1
fi

mkdir -p ~/.codex
mkdir -p ~/.claude
mkdir -p ~/.config/opencode
mkdir -p ~/.gemini

ln -sf "$GLOBAL_RULE" ~/.codex/AGENTS.md
ln -sf "$GLOBAL_RULE" ~/.claude/CLAUDE.md
ln -sf "$GLOBAL_RULE" ~/.config/opencode/AGENTS.md
ln -sf "$GLOBAL_RULE" ~/.gemini/GEMINI.md

echo "Code Agent 全局规则链接完成："
ls -l ~/.codex/AGENTS.md
ls -l ~/.claude/CLAUDE.md
ls -l ~/.config/opencode/AGENTS.md
ls -l ~/.gemini/GEMINI.md

可以保存为：

1	~/bin/setup-ai-agent-rules

然后：

1 2	chmod +x ~/bin/setup-ai-agent-rules setup-ai-agent-rules

需要注意的问题

1. 软链接目标路径必须存在

如果 Synology Drive 还没同步完成，软链接虽然存在，但目标文件不可读。

这种情况下，工具可能无法加载规则。

所以新机器初始化时，最好先确认：

1	test -f $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

2. Cursor 仍然需要单独配置

Cursor 的 User Rules 是 UI 配置，不像 CLI 工具那样有一个稳定的 Markdown 文件路径可以直接软链接。

所以 Cursor 暂时还是单独复制进去。

如果项目级要统一，可以考虑在项目里放：

AGENTS.md

或者：

1	.cursor/rules/global.mdc

3. 全局规则不要写项目细节

不要在全局规则里写：

1
2
3

- 本项目使用 Spring Boot 3。
- 所有模块都必须使用 Maven。
- Controller 不能返回 ResponseEntity。

这些应该放到具体项目的 AGENTS.md、CLAUDE.md 或 GEMINI.md 中。

全局规则只写所有项目都适用的行为规范。

4. 项目规则可以显式覆盖全局规则

如果某个项目有特殊要求，可以在项目规则里明确写：

# Project Override

- 本项目 commit message 必须使用英文。
- 该规则覆盖用户全局规则中的中文 commit message 偏好。

因为这些规则最终大多会被拼接进上下文，所以不要写模糊冲突的规则，最好显式说明覆盖关系。

后续可以怎么继续演进

这次只是统一了全局规则，但后面还可以继续做几件事。

1. 把规则拆成多个模块

现在是一个 agents.md，后面可以拆成：

AI/
├── global/
│   └── agents.md
├── rules/
│   ├── git.md
│   ├── java.md
│   ├── spring-boot.md
│   ├── testing.md
│   └── shell-safety.md
└── templates/
    ├── AGENTS.md
    ├── CLAUDE.md
    └── GEMINI.md

全局只放最基础的行为准则，项目按需引用更具体的规则。

2. 给不同类型项目准备模板

比如：

templates/
├── java-backend/AGENTS.md
├── node-service/AGENTS.md
├── docs-site/AGENTS.md
└── ai-native-platform/AGENTS.md

新项目初始化时直接复制对应模板。

3. 将规则纳入 dotfiles 管理

如果后续本地环境配置越来越多，可以把软链接脚本放到 dotfiles 里：

dotfiles/
├── install.sh
├── ai/
│   └── setup-agent-rules.sh
└── shell/

Synology Drive 保存规则内容，dotfiles 保存安装逻辑。

4. 增加规则生效检测

例如写一个脚本检查软链接是否正常：

#!/usr/bin/env bash

files=(
  "$HOME/.codex/AGENTS.md"
  "$HOME/.claude/CLAUDE.md"
  "$HOME/.config/opencode/AGENTS.md"
  "$HOME/.gemini/GEMINI.md"
)

for file in "${files[@]}"; do
  if [ -L "$file" ] && [ -f "$file" ]; then
    echo "OK: $file -> $(readlink "$file")"
  else
    echo "FAIL: $file"
  fi
done

总结

这次改造的核心其实很简单：

不要让每个 Code Agent 各自长出一套行为习惯，而是用一份统一的全局规则约束它们。

我最后采用的方案是：

在 Synology Drive 中创建统一规则文件：

1	$HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

将各工具的全局规则文件软链接到这份文件：

~/.codex/AGENTS.md
~/.claude/CLAUDE.md
~/.config/opencode/AGENTS.md
~/.gemini/GEMINI.md

Cursor 通过 User Rules 单独配置同样的内容。
全局规则只放个人行为偏好，项目规则继续放项目上下文。

这件事本身不复杂，但收益很明显：
以后不管我使用 Codex、Claude Code、opencode 还是 Gemini CLI，它们都会遵循同一套基础规则，比如中文回复、先给方案、确认后修改、最小变更、必要注释、遇到不明确需求先说明。

对我来说，这其实就是一种面向 Code Agent 的本地工程治理。

以前我们给人写规范、给项目写规范；现在，也需要给 Agent 写规范。

统一管理本地 Code Agent 全局规则：从 AGENTS.md 到 Synology Drive 同步

背景：Code Agent 不是越主动越好

问题：多个工具，各有一套规则文件

思考：全局规则应该管什么？

第一类：个人全局偏好

第二类：项目级规则

规则加载方式：不是简单覆盖，而是上下文合并

Codex CLI

Claude Code

opencode

Gemini CLI

Cursor

方案：自建统一全局规则文件

实施：用软链接连接到各个工具目录

Codex CLI

Claude Code

opencode

Gemini CLI

Cursor

当前统一后的结构

我的全局规则核心内容

1. 始终中文回复

2. 明确用户称呼

3. 先方案，后修改

4. 必须添加必要注释

5. 遇到不明确需求必须指出

6. 保持最小变更

为什么要放到 Synology Drive？

多设备初始化脚本

需要注意的问题

1. 软链接目标路径必须存在

2. Cursor 仍然需要单独配置

3. 全局规则不要写项目细节

4. 项目规则可以显式覆盖全局规则

后续可以怎么继续演进

1. 把规则拆成多个模块

2. 给不同类型项目准备模板

3. 将规则纳入 dotfiles 管理

4. 增加规则生效检测

总结

参考

订阅本站文章：

dong4j