别再只盯 AGENTS.md 了，Codex 和 Claude Code 真正重要的是这几层配置

别再只盯 AGENTS.md 了，Codex 和 Claude Code 真正重要的是这几层配置

很多人刚开始接触 Codex 和 Claude Code 时，都会先问一个很自然的问题：

这两个工具里，最重要的文件到底是什么？

表面上看，这个问题像是在问文件名。

但真用一段时间就会发现，真正决定工具表现的，往往不是某一个文件，而是配置处在哪一层、最后被谁覆盖、它到底影响了什么能力。

这也是很多人一开始最容易理解错的地方。

因为很多人会先记住这些名字：

• AGENTS.md
• CLAUDE.md
• config.toml
• settings.json
• SKILL.md
• auth.json

然后以为把这些名字记住了，就算懂了。

实际上，这些文件真正有价值的地方，不是"它们存在"，而是：

• 它们在哪一层生效
• 谁先加载，谁后加载
• 谁离当前工作目录最近
• 它们到底改变了 AI 的什么行为

如果这几件事没看懂，就算把文件名背下来，也很难真正用明白 Codex 和 Claude Code。

一、为什么说背文件名没用，先看懂"三层配置"才有用？

如果只想快速抓重点，我更建议先从"三层配置"开始理解。

这里说的三层，不是功能分类，而是作用域分层。

也就是：

1. 用户全局层
2. 项目层
3. 当前目录层

为什么这一层比文件名更重要？

因为同一个工具，往往不是只读一个地方的规则，而是会把不同层级的配置叠加起来一起看。

而且有一个特别关键的原则：

越接近当前工作目录的配置，通常越晚加载，也越容易直接影响当前任务。

这句话非常重要。

因为很多人会遇到一种现象：

• 明明全局已经配好了
• 明明上层目录已经写了规则
• 但进入某个项目或某个子目录后，工具的行为还是变了

这背后的原因，往往不是工具"变笨了"，而是离当前目录更近的那层配置接管了更多当前行为。

这就是为什么理解"层级"比记住文件名更重要。

二、用户全局层到底管什么？为什么它决定了默认工作方式？

这一层最好理解。

用户全局层，指的是工具在用户主目录下保存的默认配置。

它不只服务一个项目，而是服务当前用户使用这个工具的整体习惯。

1. Codex 的全局层主要看什么？

在 Codex 里，这一层通常集中在 ~/.codex/。

常见内容包括：

• ~/.codex/config.toml
• ~/.codex/auth.json
• 全局 AGENTS.md
• 全局 agents/
• 全局 skills/

这一层最核心的作用，不是告诉 Codex 当前项目做什么，而是告诉它：

• 平时默认怎么工作
• 默认加载哪些能力
• 默认用什么身份连接服务
• 默认有哪些长期规则

简单说，这一层决定 Codex 的"基础人格"和"基础环境" 。

2. Claude Code 的全局层主要看什么？

在 Claude Code 里，对应的通常是 ~/.claude/。

比较关键的对象包括：

• ~/.claude/settings.json
• ~/.claude/CLAUDE.md

其中：

• settings.json 更像默认设置
• CLAUDE.md 更像长期行为说明

这一层的意义和 Codex 很像，都是给工具一个"默认起点"。

也就是说，当项目里什么都还没写的时候，工具首先会继承这一层的习惯。

三、项目层为什么最容易踩坑？它到底怎么改变一个仓库里的 AI 行为？

很多人真正踩坑的地方，其实就在项目层。

因为 AI 工具最怕的一件事，就是把所有项目都按同一种方式处理。

现实情况是，不同仓库的目标、规范、输出风格、目录分工可能完全不同。

所以项目层才是 AI 工具真正"有上下文"的开始。

1. Codex 进入项目后，哪些配置开始接管行为？

在 Codex 里，项目层通常会看到这些对象：

• 项目级 AGENTS.md
• 项目自己的 agents/
• 项目自己的 skills/
• 以及项目相关的配置文件

这一层的作用非常直接：

• 告诉 Codex 这个仓库是干什么的
• 收到任务之后优先去哪里工作
• 当前输出应该遵守什么风格
• 哪些默认行为需要被修改

所以项目层不是补充信息，而是真正把全局工具变成当前仓库协作者的一层。

2. Claude Code 进入项目后，为什么会像换了一个助手？

Claude Code 的项目层更清晰一些，因为它的官方结构本来就比较明确。

常见对象包括：

• .claude/settings.json
• 项目根目录下的 CLAUDE.md

这一层的含义也很明确：

• 全局层解决"平时怎么工作"
• 项目层解决"在这个仓库里怎么工作"

也就是说，同一个 Claude Code，在不同项目里完全可能像两个不同的助手。

这不是模型变化，而是项目层规则在起作用。

四、为什么离当前目录最近的配置影响最大？

这一层是最容易被忽略、但实际影响最大的。

很多人以为只要在项目根目录配好规则就够了。

但在真实工作里，一个仓库往往并不只做一件事。

例如一个大型仓库里可能同时有：

• 前端目录
• 后端目录
• 文档目录
• 脚本目录

这些目录的工作方式，往往并不一样。

这时候如果每次都让 AI 只吃一份项目总规则，效果通常并不好。

因为它拿到的是大而全的约束，而不是当前任务最需要的那一层。

这也是为什么目录级说明文件很重要。

1. 在 Codex 里，AGENTS.md 为什么越靠近当前目录越有用？

在 Codex 里，AGENTS.md 真正强的地方，不只是它像一份提示词文档，而是它可以承担分层规则载体的作用。

例如：

• 仓库根目录有一份 AGENTS.md
• 某个子目录里还有一份 AGENTS.md

这意味着：

• 根目录负责总规则
• 子目录负责当前模块规则

而且越接近当前工作目录，规则通常越具体，对当前输出的影响也越直接。

这也是很多人真正把 Codex 用顺手之后会发现的一点：

AGENTS.md 重要，不是因为它名字特殊，而是因为它能把规则"压到离任务最近的地方"。

2. Claude Code 读的是 CLAUDE.md，它和 AGENTS.md 到底有什么区别？

这一点需要特别说清楚。

Claude Code 的官方记忆/说明文件是 CLAUDE.md，而不是 AGENTS.md。

也就是说：

• Codex 重点看的是 AGENTS.md
• Claude Code 重点看的是 CLAUDE.md

这两个思路很像，但文件名并不一样，不能混着讲。

而且 Claude Code 一个很有代表性的特点是：

它会沿当前工作目录向上查找 CLAUDE.md。

这意味着什么？

意味着你当前在哪个目录里干活，会直接决定 Claude Code 最后读到哪几层说明文件。

离当前目录越近的那份 CLAUDE.md，通常越贴近当前任务。

所以这一层真正影响工作的地方，不在"它存在"，而在：

• 当前目录决定了读取链路
• 最近的说明文件决定了当前任务的上下文密度

五、这些文件不是"重要"就完了，它们到底改变了什么？

很多文章的问题，不是信息不对，而是只会说：

• 这个文件很重要
• 那个目录也很重要

但重要在哪里，一笔带过，读者看完还是不知道实际影响。

如果要把 Codex 和 Claude Code 讲明白，就必须直接回答：

这些文件到底改变了什么？

1. AGENTS.md、CLAUDE.md 这类说明文件，真正改变了什么？

例如：

• AGENTS.md
• CLAUDE.md

它们真正改变的，不是"能不能运行"，而是 AI 在处理任务时的判断路径。

比如它会影响：

• 先去哪个目录工作
• 优先遵守哪些规则
• 输出偏工程化还是偏说明化
• 当前任务应该保守处理还是主动扩展

所以这类文件最核心的作用，不是"提供信息"，而是改写 AI 的工作方法。

2. config.toml、settings.json 这类环境文件，真正影响了什么？

例如：

• config.toml
• settings.json
• settings.local.json

它们更像是在调整工作现场。

这类文件的作用通常包括：

• 默认启用哪些能力
• 工具能看到哪些扩展配置
• 哪些设置在当前项目里会覆盖全局行为

这类文件真正影响的是：

AI 在什么环境里做事，以及它的工作边界到底画在哪里。

3. auth.json 这类身份文件，为什么决定了 AI 能不能把事做完？

例如：

• auth.json
• API Key
• 登录态缓存

很多人觉得这一类"没那么值得讲"，其实恰好相反。

因为如果没有身份和连接能力，前面所有规则再漂亮，最后也只是纸上谈兵。

这一类改变的，是最底层的问题：

• 能不能连上服务
• 能不能调用能力
• 能不能把任务真正执行完

六、为什么我建议把"三层配置"和"三类配置"分开讲？

前面讲的是"三层配置"，也就是作用域分层。

这是理解 AI 工作环境的第一步。

在这个基础上，再讲"三类配置"，才不会混。

这三类，我更建议分开说。

1. 什么是智能体配置？它具体影响哪些工作结果？

这一类决定的是 AI 应该怎么做事。

典型对象包括：

• AGENTS.md
• CLAUDE.md
• SKILL.md
• agents/
• skills/

它们影响的是：

• 角色
• 规则
• 工作方法
• 能力调用方式

2. 什么是环境工作配置？它为什么决定规则怎么生效？

这一类决定的是 AI 在哪里做事，以及当前规则怎么生效。

典型对象包括：

• config.toml
• settings.json
• settings.local.json
• 工作区结构
• 目录约束

它们影响的是：

• 当前工作上下文
• 覆盖关系
• 默认能力和局部能力的边界

3. 什么是 API 与身份配置？它为什么不只是"登录一下"这么简单？

这一类决定的是 AI 能不能真正开始做事。

典型对象包括：

• auth.json
• API Key
• 登录态缓存

它们影响的是：

• 可用性
• 连接能力
• 服务调用权限

这样拆开以后，读者就会更容易同时看懂两件事：

• AI 当前所处的环境是什么
• 每个文件到底会对工作结果产生什么影响

七、agents/、skills/、SKILL.md 到底意味着什么？为什么很多人用久了才意识到它们重要？

如果只讲到 AGENTS.md 和 CLAUDE.md，这篇文章其实还不够。

因为当一个人开始真的想把 Codex 或 Claude Code 用深一点时，他很快就会遇到这些对象：

• agents/
• skills/
• SKILL.md

它们不是简单的"补充目录"，而是能力组织方式。

1. agents/ 为什么不是普通目录，而是角色分工系统？

agents/ 的意义，不是单纯多放几个配置文件，而是把不同职责拆给不同 agent。

这件事在复杂任务里非常有用。

比如一个任务可能同时需要：

• 搜集信息
• 改代码
• 跑验证
• 检查风险

如果全都压在一个主代理身上，它很容易出现两个问题：

• 上下文太乱
• 不同目标相互打架

这时候子代理或多智能体的价值就出来了。

它们最核心的作用是：

• 分工
• 降低上下文混乱
• 提高复杂任务的稳定性

简单说，子代理不是为了看起来高级，而是为了把复杂任务拆开做。

2. 子代理和多智能体到底解决了什么问题？

很多人第一次听到多智能体，会觉得像是"更高级的噱头"。

其实不是。

多智能体最实际的作用，就是解决单代理在复杂任务里的三个老问题：

• 信息太多，容易混
• 目标太多，容易顾此失彼
• 任务跨度太大，容易做着做着偏题

拆成多个 agent 之后，可以让它们分别负责：

• 代码实现
• 文档整理
• 调研分析
• 质量检查

这时候主代理更像一个调度者，而不是所有事情都亲自做的人。

所以多智能体真正影响工作结果的地方，在于：

它改变的不是知识量，而是任务组织方式。

3. skills/ 和 SKILL.md 为什么能把经验变成可复用能力？

skills/ 和 SKILL.md 的意义，很多人一开始也会理解浅了。

它们不是"给 AI 塞更多说明"，而是把某类任务的处理方法固化下来。

比如某个 skill 里，可能不只有说明文字，还会带上：

• 脚本
• 模板
• 资源文件
• 参考流程

这说明一个 skill 的本质，不只是描述能力，而是把一套做事方法打包。

它真正带来的变化是：

• 相同任务不必每次都从零发挥
• 结果更稳定
• 输出更可控

4. 为什么有些 skill 里面还会带 agents/？

这个问题非常值得讲，因为它能让很多读者一下子明白"能力组织"到底是什么。

如果一个 skill 里面还带有 agents/，说明什么？

说明这个 skill 不只是一个静态说明，而是可能自带更细的角色拆分。

也就是说，一个 skill 可能本身就是一套小工作流：

• 有自己的规则
• 有自己的脚本
• 有自己的子代理分工

这时候 skill 的意义就不只是"能做什么"，而是：

遇到这一类任务时，整个工作流应该怎么组织。

这就是为什么越往后用，越会发现重要的不是单个文件，而是配置、能力、角色这三件事怎么拼在一起。

八、如果只想快速上手，Codex 和 Claude Code 到底该先看什么？

如果是刚开始接触 Codex 和 Claude Code，我更建议按这个顺序理解：

第一步，先看三层配置：

• 用户全局层
• 项目层
• 当前目录层

这里最关键的是先理解：

越接近当前工作目录的配置，通常越晚加载，也越影响当前任务。

第二步，再看三类配置：

• 智能体配置
• 环境工作配置
• API 与身份配置

第三步，再去看能力组织方式：

• agents/
• skills/
• SKILL.md
• 子代理
• 多智能体

这样再回头看 AGENTS.md、CLAUDE.md、config.toml、settings.json、auth.json，就不会只是在背文件名，而是真的开始理解这些工具为什么会那样工作。

九、结论：真正该记住的不是文件名，而是它们如何共同影响当前任务

如果一定要回答"Codex 和 Claude Code 最重要的文件是什么"，更准确的答案不是某一个文件名，而是：

最重要的是几层配置、几类配置，以及它们最终如何共同作用在当前任务上。

从作用域上看，最关键的是三层：

• 用户全局层
• 项目层
• 当前目录层

从功能上看，最值得优先理解的是三类：

• 智能体配置
• 环境工作配置
• API 与身份配置

而从真正影响工作结果的角度看，AGENTS.md、CLAUDE.md、config.toml、settings.json、SKILL.md、agents/、skills/、auth.json 这些对象之所以重要，不是因为它们名字显眼，而是因为它们分别决定了：

• AI 怎么想
• AI 在哪儿做
• AI 能不能做
• AI 是单独做，还是分工做

真正把 Codex 和 Claude Code 用明白，不是记住某一个文件，而是看懂这套配置和能力组织逻辑。