AI 编程 CLI 的指令文件怎么生效：CLAUDE.md、AGENTS.md 与 OpenCode 对比

很多人第一次接触 AI 编程 CLI 时，最容易混淆的不是模型，而是“项目规则到底写在哪个文件里”“子目录会不会继承”“多层文件同时存在时怎么合并”。

这篇文章只讲指令文件机制，不展开权限控制。如果你想先看整体选型，再判断自己该深入哪一块，建议先从总览文开始。

总览文入口：AI 编程 CLI 工具怎么选：Claude Code、Codex CLI 与 OpenCode 对比

写在前面

可以把指令文件理解成给 AI 准备的一份“项目作战手册”：

文件名和存放位置，决定工具能不能找到它。
目录继承规则，决定子目录是否自动拿到上层约定。
多文件合并策略，决定不同层级的规则会不会互相覆盖。

如果这些机制没搞清楚，多仓库项目里最常见的问题就是“规则明明写了，AI 却像没看见一样”。而这恰好是三款工具差异最明显的地方之一。

如果你后面还准备配置权限边界，可以接着看这篇：

AI 编程 CLI 的权限怎么配：Claude Code、Codex CLI 与 OpenCode 对比

工具概览

维度	Claude Code	Codex CLI	OpenCode
开发方	Anthropic	OpenAI	SST（开源）
指令文件名	`CLAUDE.md`	`AGENTS.md`	`AGENTS.md`（优先）/ `CLAUDE.md`（兼容）
开源	❌ 闭源	✅ 开源	✅ 开源
多模型支持	❌ 仅 Claude	❌ 仅 OpenAI	✅ 支持多家提供商

文件名与位置

指令文件用于向 AI 提供项目上下文、编码规范、工作流约定等自然语言说明，相当于 AI 的"项目说明书"。

Claude Code — `CLAUDE.md`

层级	路径	说明
系统托管	`/etc/claude-code/CLAUDE.md`（Linux） `/Library/Application Support/ClaudeCode/CLAUDE.md`（macOS）	IT 管理员下发，最高优先级
用户全局	`~/.claude/CLAUDE.md`	对当前用户所有项目生效，独立加载，非目录遍历结果
目录遍历	从当前工作目录向上逐级查找	沿途所有层级全部加载，越过 git root 继续向上（实测验证）
子目录	`./src/CLAUDE.md` 等	懒加载，Claude 读取该目录文件时才加载

可通过 /context 命令查看当前会话实际加载的文件列表。

Codex CLI — `AGENTS.md`

层级	路径	说明
用户全局	`~/.codex/AGENTS.md`	对所有项目生效
项目路径	从项目根目录到当前工作目录逐级查找	每层最多加载一个文件，靠近当前目录的规则排在后面
Override	`AGENTS.override.md`	同一目录内优先于 `AGENTS.md`，适合临时覆盖
兼容文件名	`project_doc_fallback_filenames` 配置项	可把其他文件名加入项目说明文件查找列表

注意：Codex CLI 会在启动 / 新 run / TUI 新 session 时构建指令链，但只沿“项目根目录 → 当前工作目录”这条路径加载；不会因为后续读到某个兄弟子目录文件，就自动加载那个子目录下的 AGENTS.md。项目指令合并大小受 project_doc_max_bytes 限制，默认 32 KiB。

OpenCode — `AGENTS.md`（优先）/ `CLAUDE.md`（兼容回退）

层级	路径	说明
用户全局	`~/.config/opencode/AGENTS.md`	对所有项目生效，不提交 git
目录遍历	从当前目录向上遍历至 git root	每层取一个文件（AGENTS.md 优先，无则找 CLAUDE.md）
Claude 兼容（回退）	`./CLAUDE.md`（无 AGENTS.md 时）	两者同时存在时忽略 CLAUDE.md
扩展引用	`opencode.json` 的 `instructions` 字段	支持 glob 模式和远程 URL

兼容说明：若同时存在 AGENTS.md 和 CLAUDE.md，只读取 AGENTS.md。

目录继承行为

场景结构

1
2
3
4
5
6
7
8
9
~/projects/
├── CLAUDE.md / AGENTS.md              ← 多仓库共享层
├── order-service/                      ← git repo ①
│   ├── CLAUDE.md / AGENTS.md          ← 项目级
│   └── src/
│       └── order/
│           └── CLAUDE.md              ← 子模块级（当前工作目录）
└── notify-service/                     ← git repo ②
    └── CLAUDE.md / AGENTS.md          ← 项目级

Claude Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
当前工作目录：~/projects/order-service/src/order/

加载顺序（启动时全量加载）：
  1. ~/.claude/CLAUDE.md                           ← 用户全局（独立加载）
  2. ~/projects/CLAUDE.md                          ← 越过 git root 继续向上（实测验证）
  3. ~/projects/order-service/CLAUDE.md            ← 项目根目录
  4. ~/projects/order-service/src/CLAUDE.md        ← 沿途（如存在）
  5. ~/projects/order-service/src/order/CLAUDE.md  ← 当前工作目录

子目录懒加载（按需）：
  当 Claude 读取 src/payment/ 中的文件时，
  才加载 src/payment/CLAUDE.md（如果存在）

关键特性：

遍历终止条件官方未明确，但实测越过 git root 继续向上
~/.claude/CLAUDE.md 是独立的用户全局配置，并非遍历结果
子目录采用懒加载策略，不影响启动性能

Codex CLI

1
2
3
4
5
6
7
8
9
当前工作目录：~/projects/order-service/src/order/

加载顺序（从根到当前目录）：
  1. ~/.codex/AGENTS.md                            ← 用户全局
  2. ~/projects/order-service/AGENTS.md            ← git 仓库根目录
  3. ~/projects/order-service/src/AGENTS.md        ← 沿途（如存在）
  4. ~/projects/order-service/src/order/AGENTS.md  ← 当前工作目录

不会加载 ~/projects/AGENTS.md（不在项目根到当前目录这条路径内）。

关键特性：

启动时沿项目根到当前工作目录加载，不会全仓库扫描
同一目录优先 AGENTS.override.md，其次 AGENTS.md，再看 fallback 文件名
任务过程中读取兄弟子目录文件时，不会自动补加载该子目录的 AGENTS.md
~/projects/ 层的共享文件无法被自动加载

OpenCode

1
2
3
4
5
6
7
8
9
当前工作目录：~/projects/order-service/src/order/

加载顺序：
  1. ~/.config/opencode/AGENTS.md                   ← 用户全局
  2. ~/projects/order-service/src/order/AGENTS.md   ← 当前目录
  3. ~/projects/order-service/src/AGENTS.md         ← 若存在
  4. ~/projects/order-service/AGENTS.md             ← git root，停止

不会加载 ~/projects/AGENTS.md（遍历止于 git root）。

关键特性：

停在 git root（源码验证：const root = git ?? input.cwd）
无 git 仓库时不向上遍历，以 cwd 为根
~/projects/ 层无法自动加载，需借助 instructions 字段显式引入

多文件合并策略

工具	合并方式	优先级规则
Claude Code	✅ 全部合并，所有层级的文件都加入上下文	越靠近当前目录优先级越高；冲突指令 Claude 可能随机选择一个
Codex CLI	✅ 全部合并，启动路径上的项目文件拼接	越靠近当前目录的文件内容排列在后，隐式优先
OpenCode	⚠️ 每层级取一个文件；可通过 `instructions` 字段显式引入多文件	越靠近当前目录优先级越高

Claude Code — Import 语法

在 CLAUDE.md 中可用 @ 引用其他文件，启动时一并加载：

1
2
3
4
@./docs/coding-standards.md
@./docs/api-guidelines.md
@~/.claude/personal-preferences.md
@/absolute/path/to/shared-rules.md

如果一个项目已经维护 AGENTS.md，想兼容 Claude Code，最薄的做法是在项目根目录新增 CLAUDE.md：

1
@AGENTS.md

Claude Code 会解析这个 import，把 AGENTS.md 内容作为 CLAUDE.md 的一部分加载进上下文。注意这不是“零 token 引用”，导入后的内容同样占用上下文。

OpenCode — instructions 字段

通过 opencode.json 显式引入多个文件，支持 glob 和远程 URL：

1
2
3
4
5
6
7
8
{
  "instructions": [
    "./AGENTS.md",
    "./docs/coding-standards.md",
    "packages/*/AGENTS.md",
    "https://example.com/shared-rules.md"
  ]
}

多仓库场景实践

多服务项目中，每个服务是独立的 git repo，服务间通过 HTTP 调用。核心问题是：AI 每次只在一个 repo 里工作，如何获取其他服务的接口信息？

Claude Code 方案（推荐）

利用目录遍历越过 git root 的特性，在 ~/projects/ 下放共享文件：

文件职责划分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
~/.claude/CLAUDE.md
  → 个人偏好（沟通语言、代码风格）

~/projects/CLAUDE.md
  → 多仓库共享约定（技术栈、服务目录、跨服务调用约定）

~/projects/order-service/CLAUDE.md
  → 本服务职责、对外接口、依赖的上游接口契约

~/projects/order-service/src/*/CLAUDE.md
  → 子模块特殊说明（可选）

~/projects/CLAUDE.md 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# 多服务共享规范

## 技术栈
- Java 8 + Spring Boot 2.x
- 服务间通信：HTTP REST，统一使用 Feign Client
- 统一响应结构：{ code: int, message: String, data: T }

## 服务目录
| 服务 | 职责 | 内网地址 |
|------|------|----------|
| user-service    | 用户账户、余额管理 | http://user-service:8001    |
| order-service   | 订单生命周期管理   | http://order-service:8002   |
| notify-service  | 短信/Push 通知     | http://notify-service:8003  |

## 跨服务开发约定
- 修改任何对外接口前，先确认所有下游调用方
- Feign Client 定义在各服务的 api 模块，不在 core 模块直接调用
- 接口字段变更（新增除外）需同步更新所有调用方

~/projects/order-service/CLAUDE.md 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# order-service

## 本服务职责
管理订单全生命周期：创建 → 支付确认 → 发货 → 完成 / 取消

## 模块结构
- order-api    对外 Feign Client 接口定义（供其他服务引用）
- order-core   业务逻辑层
- order-server 启动入口 + Controller

## 本服务对外接口
- POST /api/orders              创建订单
- PUT  /api/orders/{id}/pay    支付回调
- GET  /api/orders/{id}        查询订单详情

## 依赖的上游接口（修改时需同步）

### user-service
- GET  /api/users/{id}/balance
  响应：{ code: 0, data: { balance: BigDecimal } }
- POST /api/users/{id}/balance/freeze
  请求：{ amount: BigDecimal, orderId: String }
  响应：{ code: 0, data: { freezeId: String } }

### notify-service
- POST /api/notify/send
  请求：{ userId: String, type: "ORDER_CREATED"|"ORDER_PAID", bizId: String }
  响应：{ code: 0, data: { msgId: String } }

Codex CLI 方案

无法加载 ~/projects/ 层，跨项目共享内容只能放进用户全局文件：

文件职责划分：

1
2
3
4
5
6
~/.codex/AGENTS.md
  → 必须承担所有跨项目内容（技术栈、服务目录、跨服务约定）
  → 内容较多时注意 token 消耗，保持精简

~/projects/order-service/AGENTS.md
  → 本服务职责、对外接口、依赖的上游接口契约

~/.codex/AGENTS.md 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 全局规范

## 技术栈
- Java 8 + Spring Boot 2.x，Feign Client 跨服务调用
- 统一响应结构：{ code, message, data }

## 服务目录
- user-service:8001   用户账户余额管理
- order-service:8002  订单生命周期
- notify-service:8003 消息通知

## 约定
- Feign Client 定义在 api 模块
- 接口变更必须同步更新调用方

OpenCode 方案

遍历止于 git root，通过 _shared/ 目录 + instructions 字段共享内容：

推荐目录结构：

1
2
3
4
5
6
7
8
9
~/projects/
├── _shared/                               ← 共享契约目录（非 git repo）
│   ├── conventions.md                     ← 技术栈、服务目录、跨服务约定
│   └── api-contracts/
│       ├── user-service.md
│       └── notify-service.md
└── order-service/
    ├── AGENTS.md                          ← 本服务职责与对外接口
    └── opencode.json                      ← 通过 instructions 引入共享内容

opencode.json 示例：

1
2
3
4
5
6
7
8
{
  "instructions": [
    "./AGENTS.md",
    "~/_shared/conventions.md",
    "~/_shared/api-contracts/user-service.md",
    "~/_shared/api-contracts/notify-service.md"
  ]
}

三方案对比

维度	Claude Code	Codex CLI	OpenCode
共享层位置	`~/projects/CLAUDE.md`（自动加载）	`~/.codex/AGENTS.md`（手动维护）	`_shared/` + `instructions`（显式引入）
跨项目一致性	✅ 单一来源，自动同步	⚠️ 靠人工保证	✅ 单一来源，显式引入
配置成本	最低（放文件即生效）	最高（全塞全局文件）	中等（需配置 instructions）

横向对比总表

特性	Claude Code	Codex CLI	OpenCode
文件名	`CLAUDE.md`	`AGENTS.md`	`AGENTS.md`（优先） `CLAUDE.md`（兼容回退）
用户全局路径	`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`	`~/.config/opencode/AGENTS.md`
向上目录遍历	✅ 越过 git root 继续（实测）	✅ 项目根到当前目录	✅ 停在 git root
多仓库共享层	✅ `~/projects/CLAUDE.md` 自动加载	❌ 不支持	⚠️ 需 `instructions` 显式引入
子目录懒加载	✅ 按需触发	❌ 仅启动路径	❌
多文件全量合并	✅ 全部合并	✅ 启动路径文件合并	⚠️ 每层取一个
Import / 引用语法	✅ `@path`	⚠️ fallback 文件名配置，不是正文 import	✅ `instructions` 字段
系统级策略文件	✅	❌	⚠️ 远程 `.well-known/opencode`
兼容对方格式	❌	❌	✅ 兼容 CLAUDE.md
上下文压缩后	根 `CLAUDE.md` 会重新读取注入；嵌套文件按需再加载	不应假设 `AGENTS.md` 原文完整保留	取决于当前会话上下文
禁用项目文件	`claudeMdExcludes`	可通过项目文档相关配置控制	无

总结

如果你最看重“目录向上继承 + 多仓库共享层”，Claude Code 的行为最完整，也最接近“放对位置就能生效”的体验。

如果你更接受“项目根到当前目录”的启动路径规则，Codex CLI 会更容易理解，但跨项目共享内容需要自己精简维护。

如果你想兼顾兼容性和灵活性，OpenCode 的 instructions 能补足很多场景，只是配置成本会比前两者更高一些。

还有一个容易忽略的差异是上下文压缩：Claude Code 明确会在 /compact 后重新读取并注入项目根目录的 CLAUDE.md，嵌套 CLAUDE.md 和路径规则则等再次触达对应文件时再加载；Codex 的公开手册只说明长任务会 compact 上下文，没有承诺 AGENTS.md 原文在压缩后逐字完整保留。因此关键规则最好放在文件顶部，长篇细则放到专门文档里，再由指令文件引用阅读入口。

文中的加载行为和合并策略基于 2026-03-18 左右公开资料与实测整理；其中 Claude Code 的上下文压缩行为、@AGENTS.md 兼容写法，以及 Codex AGENTS.md 的项目路径加载规则，已按 2026-06-12 前后官方文档补充。真正落地前还是建议对照一下最新官方文档。

参考资料：

AI 编程 CLI 的指令文件怎么生效：CLAUDE.md、AGENTS.md 与 OpenCode 对比

写在前面

工具概览

文件名与位置

Claude Code — CLAUDE.md

Codex CLI — AGENTS.md

OpenCode — AGENTS.md（优先）/ CLAUDE.md（兼容回退）

目录继承行为

场景结构

Claude Code

Codex CLI

OpenCode

多文件合并策略

Claude Code — Import 语法

OpenCode — instructions 字段

多仓库场景实践

Claude Code 方案（推荐）

Codex CLI 方案

OpenCode 方案

三方案对比

横向对比总表

总结

Claude Code — `CLAUDE.md`

Codex CLI — `AGENTS.md`

OpenCode — `AGENTS.md`（优先）/ `CLAUDE.md`（兼容回退）