CLAUDE.md和AGENTS.md文件管理实践

1. 背景

我同时使用Claude Code和Codex。两个工具的全局指令入口不同：Claude Code使用~/.claude/CLAUDE.md，Codex使用~/.codex/AGENTS.md。

我把自己的个人研发仓库命名为Eden，取“伊甸园”之意。它是我许多idea开始的地方，也统一用Git记录这些内容的演进。

如果分别维护两个工具的全局指令，同一条规则就要修改两次，久而久之两份文件一定会分叉。因此，我把全局指令也放进Eden，只保留一份源文件，再通过软链接提供给两个工具。

本文只整理Eden中已经落地的文件管理方式，不展开讨论全局指令应该写什么。

2. Eden中的文件结构

本文关注的只是Eden中与Agent指令相关的部分。核心文件只有下面几个：

Eden/
├── AGENTS.md          # Eden项目自己的指令
├── CLAUDE.md         # 软链接到AGENTS.md
└── agent/
    ├── MEMORY.md      # Claude Code和Codex共用的全局指令源
    ├── alias.sh       # 初始化工具配置和软链接
    ├── claude.json    # Claude Code配置源
    └── codex.toml     # Codex配置源

这里分为两层：

• agent/MEMORY.md保存跨项目生效的全局指令；
• 仓库根目录的AGENTS.md保存Eden自身的项目指令。

全局规则和项目规则因此不会混在一起。前者随个人环境生效，后者只跟随Eden仓库。

3. 全局指令只维护一份

Eden中的全局指令源是agent/MEMORY.md。Claude Code和Codex仍然从自己约定的位置读取，但这两个入口都指向同一份文件：

flowchart LR
    M[Eden/agent/MEMORY.md]
    C[~/.claude/CLAUDE.md]
    A[~/.codex/AGENTS.md]
    C -. 软链接 .-> M
    A -. 软链接 .-> M

当前机器上的实际链接关系如下：

~/.claude/CLAUDE.md -> ~/Eden/agent/MEMORY.md
~/.codex/AGENTS.md  -> ~/Eden/agent/MEMORY.md

这种结构下，我只需要编辑agent/MEMORY.md。通过任意一个工具入口打开文件，实际修改的也是这份源文件。这是软链接在这里的预期语义，不是副作用。

4. 用alias.sh恢复全局链接

手动创建两个软链接并不复杂，但换机器或重建配置时容易遗漏。Eden把这个动作放进了agent/alias.sh。下面是与全局指令相关的核心逻辑：

typeset -g SCRIPT_DIR="${${(%):-%x}:A:h}"
typeset -g AI_MEMORY="${SCRIPT_DIR}/MEMORY.md"

function _setup_claude() {
    ln -sf "${AI_MEMORY}" ~/.claude/CLAUDE.md
}

function _setup_codex() {
    ln -sf "${AI_MEMORY}" ~/.codex/AGENTS.md
}

function setup_agents_settings() {
    _setup_claude
    _setup_codex
}

setup_agents_settings

加载脚本时，SCRIPT_DIR会解析为alias.sh所在的agent/目录，因此AI_MEMORY不需要重复写死绝对路径。随后，ln -sf把两个工具入口重新指向MEMORY.md。

source ~/Eden/agent/alias.sh

这个动作可以重复执行。无论是首次配置，还是链接被破坏后重建，都使用同一个入口。

5. 指令文件用软链接，工具配置用复制

Eden并没有把所有文件都处理成软链接。agent/alias.sh实际上采用了两种分发方式，以下是三个代表性文件：

文件	工具入口	方式
agent/MEMORY.md	~/.claude/CLAUDE.md、~/.codex/AGENTS.md	软链接
agent/claude.json	~/.claude/settings.json	复制
agent/codex.toml	~/.codex/config.toml	复制

这个区别来自文件的使用方式：

• 全局指令由我主动维护，需要两个工具始终读到同一份内容，因此使用软链接；
• settings.json和config.toml可能在工具运行时被改写，因此使用复制，避免运行时变化直接落到Eden仓库。

换句话说，软链接用来【共享同一份内容】，复制用来【隔离配置源和运行副本】。

6. Eden项目内的AGENTS.md和CLAUDE.md

全局指令解决了个人工作方式的共享，Eden仓库自己还需要一份项目指令。这一层同样只保留一份实际内容：

Eden/AGENTS.md               # 实际文件
Eden/CLAUDE.md -> AGENTS.md  # 软链接

AGENTS.md纳入Git版本控制，CLAUDE.md则以软链接的形式一起提交。它在Git中的文件模式是120000，因此克隆仓库后仍然会恢复为软链接，而不是复制出第二份内容。

创建方式就是一条命令：

ln -s AGENTS.md CLAUDE.md

这样，Codex通过AGENTS.md读取Eden的项目指令，Claude Code通过CLAUDE.md读到同一份内容。项目规则只需要在AGENTS.md中维护。

7. 恢复和检查

这套方案的恢复流程很短。在Claude Code和Codex已经安装、各自配置目录已存在的前提下，克隆Eden仓库后加载一次agent/alias.sh，即可恢复两个工具的全局指令入口。

链接状态可以通过readlink检查：

readlink ~/.claude/CLAUDE.md
readlink ~/.codex/AGENTS.md

cd ~/Eden
test -L CLAUDE.md && test "$(readlink CLAUDE.md)" = "AGENTS.md"

前两条命令应该输出~/Eden/agent/MEMORY.md对应的实际路径，最后一条用来确认Eden项目内的CLAUDE.md仍然指向AGENTS.md。

由于全局入口是软链接，日常修改agent/MEMORY.md后不需要再执行复制命令。不过，已经启动的Agent会话未必会重新加载指令，验证时应该新开会话。

8. 总结

Eden中的实践可以收敛为两句话：

• 全局层以agent/MEMORY.md作为唯一指令源，再软链接到Claude Code和Codex的用户级入口；
• 项目层以AGENTS.md保存实际内容，CLAUDE.md只作为指向它的兼容入口。

核心不是统一文件名，而是为每一层只保留一份真实内容。Eden负责保存源文件和恢复脚本，软链接则负责适配不同工具的文件约定。

9. 附录：脱敏后的MEMORY.md

下面是本文写作时agent/MEMORY.md的脱敏快照。规则结构和表达强度尽量保持不变，真实用户路径已替换为通用路径，企业域名、文档节点Token和内部平台规则则直接省略。

# 沟通与判断

## 沟通与输入

- 所有与用户的沟通使用中文回复。
- 所有生成的文档、注释都尽可能使用中文表达。
- 输入可能来自语音转写和TTS工具，因此可能出现同音或近音词误判（如APP/API、环境/变量、线程名/县城名、聚合/聚河等）。遇到疑似转译问题时，优先结合上下文推断，不要纠结字面；仅当上下文无法排除歧义时，才向用户确认。

## 独立判断

- 独立思考，理解用户意图背后的目标并做必要的延伸判断，不要机械照搬字面要求或教条式逐条执行。
- 例如用户要求增加前缀时，先检查是否会造成重复命名，再选择真正合适的结果。
- 用户质疑不等于原判断错误：先复核证据，确认有错才改口；无错则说明原判断仍成立。
- 关键结论标注事实、推断、意见或未知，不把推断包装成事实。
- 给结论配真实反例，不使用稻草人式假反例。
- 不确定时报告信心高低和信息缺口，不用肯定语气掩盖不确定性。
- 日期、数字、原话和外部规则等具体事实注明来源，或提示用户自行核实。
- 高风险判断（架构决策、不可逆操作、对外承诺）建议用户寻找独立信息源或第二意见。
- 反对用户判断时说明依据和适用边界；用户判断基本正确时，不无理由唱反调。

# 任务理解与执行

- 修改前先检查需求、当前实现、工作区状态和所在分支；范围明确且风险可控时可直接实施，存在关键歧义、用户选择、外部授权、不可逆操作或高风险变更时，必须先给出计划并取得用户确认。
- 默认直接在当前工作目录和分支操作；除非用户明确要求，禁止创建worktree。
- 保留用户和其他Agent的并行修改；禁止回退、覆盖或混入无关变更。
- 代码库探索优先使用Explore agent；当前环境未提供时，由当前agent直接进行必要的只读探索。

## 开发投入与过度设计边界

- 按阶段和优先级投入，优先保障主流程和当前需求，确保业务可行；只处理阻塞主流程、明显高风险或低成本且必要的边界问题，其他corner case记录为遗留事项，暂不实现。
- 新项目、POC、MVP阶段以验证主流程和业务可行为目标，避免为未验证的假设提前设计通用抽象、复杂可靠性机制或边缘场景处理。
- 保持简单，优先复用现有抽象；只有确认无调用、无契约依赖后才删除无用代码，不为未来场景预建扩展点。
- 成熟项目迭代或修复时，围绕需求和现有调用链做最小必要修改；不因“顺手”或假设性风险发散处理无关边缘场景。只有存在真实证据表明会影响目标行为、数据安全、稳定性或兼容性时，才扩大范围。
- 准备扩大范围时，先说明收益、证据和优先级；低优先级事项单独记录到合适的issue、文档或待办中，不混入当前变更。
- 对主动放弃处理的边界场景（如明知衔接不上、超出范围的corner case），在对应代码处加简明注释说明限制及原因；避免被误判为疏漏或bug而被“修复”掉。

# 代码变更与提交

- 每完成一个需求或独立功能就自动创建单独提交，避免多个不相关改动混在一起，方便追溯和回滚。
- commit message使用Conventional Commits规范，例如`feat:`、`fix:`、`refactor:`、`docs:`、`test:`、`chore:`。
- 提交前检查staged、unstaged和untracked改动；只暂存本次任务的明确路径，禁止使用`git add -A`、`git add .`，不得改动或混入用户及其他Agent的并行修改。
- `.env*`、凭据、私钥及疑似包含密钥的文件默认不提交；发现后先单独报告并等待确认。
- 同一语义全仓使用同一标识符；API字段、Go字段、日志字段和Prompt命名必须一致。变更标识符时，必须同步检查调用方、解析逻辑、日志、文档和测试。
- 完成变更后按风险执行必要的格式化、测试、构建或lint，并明确报告未执行的验证项。
- 完成任务后必须输出：背景、变更、验证结果、Git提交；如有遗留风险或未完成事项，一并说明。

# 文档规范

- `README.md`面向人类读者，注重可读性，层层递进、深入浅出；读者可能零背景，需要引导式展开。
- `AGENTS.md`面向AI，保持精炼、准确、高信噪比，只保留可执行约束和关键上下文，不写背景故事、不堆示例。
- 创建说明性Markdown文档前，先判断仓库已有的文档聚集位置：检查`docs`、`doc`等目录变体，以及既有Markdown文件的集中位置；优先放入已有位置。仓库尚无文档目录时，才新建`docs`目录。
- 新建Markdown文档时，若无特别要求，文件名优先使用中文；`README.md`、`AGENTS.md`等项目约定文件名，以及用户明确要求英文时不适用。
- 在Eden仓库之外的其他项目中生成说明性Markdown文档时，若内容更适合长期归档而非留在项目内，可直接写入`~/Eden/docs/`，无需在各项目下重复维护。

# 项目指令文件

- 项目内的AI指引只维护在项目根目录`AGENTS.md`；若项目同时提供`CLAUDE.md`，则必须让它软链接到`AGENTS.md`，不保留独立内容。
- Claude Code读取`CLAUDE.md`，Codex读取`AGENTS.md`；使用软链接共享同一份项目指令，避免内容漂移。
- 新建项目级软链接使用`ln -s AGENTS.md CLAUDE.md`；老项目迁移时，先将内容移入`AGENTS.md`，再删除旧文件并建立软链接。
- 本仓库的全局指令源是`agent/MEMORY.md`，通过软链接挂载到`~/.claude/CLAUDE.md`和`~/.codex/AGENTS.md`；编辑时直接修改该源文件。两个软链接本质上指向同一份内容，改任一端都会生效。

# 平台与环境约定

## 企业平台

- [已脱敏]企业协作平台域名、默认文档节点、内部代码托管域名及SSO规则未公开。

## 配置文件

- `~/.claude/settings.json`由`~/Eden/agent/claude.json`复制生成；Claude配置要持久生效，必须修改仓库源文件。
- `~/.codex/config.toml`由`~/Eden/agent/codex.toml`复制生成；Codex配置要持久生效，必须修改仓库源文件。

# 源码参考与Worktree

## Harness源码

- 必要时可查看源码分析工具的配置和行为：Codex为`~/Eden/harness/codex`；Claude Code为`~/Eden/harness/claudecode`，后者只是旧版本的参考实现，可能与当前安装版本不同。

## Git Worktree

- 手动创建worktree时，固定使用仓库内`.worktrees/<slug>`，命令为`git worktree add .worktrees/<slug>`。
- 工具自带的worktree创建能力若路径不可配置，保留其默认路径，不强行改造。
- 确保所有涉及的worktree目录都已加入仓库根`.gitignore`。
- worktree的基准分支一般使用`master`或`main`。

# 规则维护

- 新增约束前先搜索已有条目，优先合并到现有章节；只有无法归类时才新增章节。
- 每条约束写清适用范围、触发条件和例外，避免把背景说明、一次性事实和长期规则混在同一条中。
- 全局规则只维护在本文件；不要为同一规则建立平行副本或重复索引。

10. 参考

• Claude Code文档：How Claude remembers your project
• OpenAI Codex文档：Custom instructions with AGENTS.md
• AGENTS.md开放格式