Codex AGENTS.md 与 Claude CLAUDE.md：配置差异、使用方法和本质

摘要

AGENTS.md 和 CLAUDE.md 看起来只是两个 Markdown 文件，但它们背后代表的是同一个工程问题：如何让 AI 编程代理在进入项目时拥有稳定、清晰、可执行的上下文。

Claude Code 使用 CLAUDE.md。Codex 使用 AGENTS.md。它们都解决“新会话冷启动”的问题，但最佳使用方式不同：

Claude Code：更适合较完整、解释性更强的项目背景
Codex：更适合精简项目规则 + Skills + Hooks + Rules 的分层体系

这篇文章面向初学者，从本质、配置、使用方法、适用场景、常见误区几个角度讲清楚它们的区别。

一句话理解

AGENTS.md 和 CLAUDE.md 的本质都是：

给 AI 编程代理看的项目工作说明书。

它们不是给最终用户看的产品文档，也不是普通 README。

它们的读者是 AI 编程代理，目标是让模型在开始工作前理解：

• 项目是做什么的。
• 当前仓库有哪些约定。
• 应该遵循什么流程。
• 哪些事情不能做。
• 什么时候需要验证。
• 哪些任务应该调用特定能力。

为什么需要项目上下文文件

Codex 和 Claude Code 每次开启新会话时，默认都不会自动记住上一次项目里的规则、约定和背景。

如果没有上下文文件，你就要反复告诉它：

这个项目是做什么的
使用什么技术栈
代码风格是什么
文档放在哪里
修改后要跑什么测试
哪些目录不要随便改
有哪些已知问题

这就是上下文文件的意义。

Claude Code 中，这个文件通常叫：

CLAUDE.md

Codex 中，这个文件通常叫：

AGENTS.md

它们都是一种“持久项目简报”。

两者共同点

AGENTS.md 和 CLAUDE.md 有很多共同点。

第一，它们都是 Markdown 文件。

这意味着它们适合被 Git 管理，也适合团队一起维护。

第二，它们都用于降低冷启动成本。

AI 进入项目后，可以先读取规则，再开始做任务，而不是每次都靠用户临时解释。

第三，它们都应该写长期有效的信息。

适合写：

项目用途
技术栈
目录结构
代码规范
测试命令
工作流程
完成标准
安全边界

不适合写：

一次性聊天记录
某个临时 bug 的完整排查日志
大量历史会议记录
某个模块的超长细节

第四，它们都不是越长越好。

上下文文件的价值在于“始终相关”，不是“包罗万象”。

Claude Code 的 CLAUDE.md：特点和适合内容

Claude Code 的 CLAUDE.md 更适合放比较详细的项目说明。

它适合写：

项目目标
架构说明
技术栈
代码规范
常见开发模式
已知问题
团队约定
设计取舍

为什么？

因为 Claude Code 的典型使用场景更偏向：

• 探索性讨论。
• 架构设计。
• 复杂规划。
• 创意型方案分析。
• 长背景下的推理。

这类任务需要模型理解更多“为什么”。

例如，不只是写：

不要引入新依赖。

还可以解释：

这个项目是学习型仓库，目标是理解 Codex 项目规则和 skill 组织方式。为了保持示例小而清晰，默认不引入外部依赖。

这类解释性背景对 Claude Code 很有价值。

CLAUDE.md 的风险

CLAUDE.md 的优势也是它的风险。

因为它通常是一个单文件上下文，所以很容易越来越长。

如果你把所有东西都写进去：

架构背景
模块细节
历史 bug
会议记录
调试日志
一次性命令

最后会变成一个很大的文件。

问题是：只要它被加载，里面的所有内容都会进入上下文。即使你今天只想改一个小功能，也可能带着大量无关背景。

所以 CLAUDE.md 可以比 AGENTS.md 更详细，但仍然应该定期清理。

Codex 的 AGENTS.md：特点和适合内容

Codex 的 AGENTS.md 更适合写精简、明确、可执行的项目规则。

它适合写：

项目目的
基本目录结构
编码规范
测试命令
工作流程
不要做什么
完成标准
项目本地 skills 位置

例如当前学习项目的 AGENTS.md 包含：

Purpose：这是一个学习 Codex 项目规则、工作流和 skills 组织方式的仓库
General Rules：先读项目结构，示例要小，不随意加依赖
Workflow：理解请求、检查文件、说明计划、修改、验证、总结
Skill Usage：项目本地 skills 放在 .agents/skills/<skill-name>/SKILL.md
Completion Criteria：请求的文件或行为存在，结构仍然容易理解，重要下一步已记录

Codex 的 AGENTS.md 不应该写成大百科。

原因是 Codex 更强调：

• 长时间执行。
• 自动化任务。
• 技能系统。
• 上下文效率。
• 仓库内实际修改。

如果 AGENTS.md 写得太长，每次新聊天都会浪费上下文空间。

Codex 不应该只依赖 AGENTS.md

这是理解 Codex 的关键。

Codex 不应该只靠 AGENTS.md 承载所有知识。

更合理的结构是：

AGENTS.md：放通用规则
SKILL.md：放具体工作流程
Hooks：放确定性自动化
.rules：放命令权限策略

例如：

内容	应该放哪里
项目目的、目录结构、完成标准	AGENTS.md
每日问答记录格式	daily-qa-log skill
SVN 提交说明格式	svn-commit-message skill
代码审查检查项	code-review-checklist skill
每轮回答后自动记录	Stop hook
禁止危险命令	.rules 或 PreToolUse hook

这样 AGENTS.md 可以保持简洁，而复杂流程放到 skill 中，需要时再调用。

Codex 如何发现 AGENTS.md

Codex 会在启动时构建一条指令链。

顺序大致是：

全局规则
↓
项目根目录规则
↓
当前子目录规则

常见例子：

~/.codex/AGENTS.md
项目根目录/AGENTS.md
services/payments/AGENTS.override.md

如果从 services/payments 启动，Codex 会读取三层。

如果只从项目根目录启动，Codex 只会读取：

1. ~/.codex/AGENTS.md
2. 项目根目录/AGENTS.md

不会继续扫描：

services/payments/AGENTS.override.md

原因是：

Codex 只读取从项目根目录到当前工作目录这条路径上的规则文件。

AGENTS.override.md 和 fallback 文件名

AGENTS.override.md 是覆盖文件。

同一目录下，Codex 优先读取：

AGENTS.override.md

如果它存在，就不会再读取同目录下的：

AGENTS.md

fallback 文件名是另一回事。

Codex 默认只认识：

AGENTS.override.md
AGENTS.md

如果项目里有：

TEAM_GUIDE.md
PROJECT_RULES.md
CONTEXT.md
.agents.md

Codex 默认不会把它们当成项目规则读取。

这时可以配置：

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

之后 Codex 在每个目录里会按顺序找：

1. AGENTS.override.md
2. AGENTS.md
3. TEAM_GUIDE.md
4. .agents.md

每个目录最多读取一个文件。

所以 fallback 的本质是：

默认规则文件不存在时的备用文件名。

不是读取所有文档。

Codex 和 Claude 的核心差异

维度	Codex AGENTS.md	Claude CLAUDE.md
文件本质	项目工作规则	项目上下文说明
推荐长度	更精简	可以更详细
适合内容	始终相关的执行规则	架构背景、设计取舍、探索性说明
配套能力	Skills、Hooks、.rules、fallback、CODEX_HOME	更依赖 CLAUDE.md 本身
适合任务	长时间执行、自动化、仓库修改	探索、规划、架构讨论
主要风险	AGENTS.md 写太长会浪费上下文	CLAUDE.md 容易变成臃肿单文件

一句话：

Claude 更适合承载详细背景，Codex 更适合分层组织工作流。

五个评估维度

如果比较项目上下文系统，可以从五个维度看。

1. 阅读频率

这个文件什么时候被读取？

如果每次会话都读取，就应该控制长度。

2. 令牌成本

上下文文件越长，消耗越多。

Codex 特别需要注意这一点，因为它强调长时间执行和上下文效率。

3. 适用范围

规则是全局、项目级、还是子目录级？

Codex 支持全局、项目根目录、当前子目录这条路径上的多层规则。

4. 可移植性

Markdown 文件本身可移植。

同一个项目可以同时存在：

AGENTS.md
CLAUDE.md

分别给 Codex 和 Claude Code 使用。

5. 可操作性

规则是否真正影响行为？

如果只是写一句“请认真一点”，意义不大。

更好的写法是：

修改 JavaScript 后运行 npm test
文档写入 技术文档/每日记录/
不要新增生产依赖，除非用户明确要求

Skills：Codex 的重要优势

Codex 的一个核心优势是 Skills。

Skill 是一个可复用能力模块：

.agents/skills/<skill-name>/SKILL.md

它可以定义：

• 什么时候触发。
• 按什么步骤做。
• 输出什么格式。
• 需要哪些模板。
• 是否使用脚本。

当前项目示例 skills 包括：

codex-project-setup
code-review-checklist
svn-commit-message
daily-qa-log

全局 skill 可以放在：

C:\Users\your_username\.agents\skills

调用方式通常是：

$skill-name 任务描述

例如：

$daily-qa-log 今天的问答记录整理一下
$svn-commit-message 根据当前修改生成 SVN 提交说明

Codex 也可以根据 skill 的 description 隐式触发。

Skill 不是 Prompt

Skill 不是一段临时 prompt。

一个真正好用的 skill 应该有：

name
description
workflow
output format
examples
references
scripts

例如写博客方向可以拆成：

blog-writer
technical-writing
markdown-publisher
screenshot-explainer
reverse-engineering-blog
create-diagram
seo-blog-optimizer
windows-performance-blogger

这些名字体现了一个设计思路：不要让一个 skill 负责所有事情，而是按任务类型拆分。

后来这些博客相关全局 skills 被删除，也说明 skill 应该保持有用、必要、可维护；不是安装越多越好。

Hooks：Codex 的可执行规则

Hooks 是 Codex 的生命周期脚本。

它和 AGENTS.md 的区别是：

AGENTS.md：告诉 Codex 应该怎么做
Hooks：在某个时机真正运行脚本

常见位置：

~/.codex/hooks.json
~/.codex/config.toml
<repo>/.codex/hooks.json
<repo>/.codex/config.toml

全局 hooks 对所有项目生效。

项目 hooks 只对当前仓库生效，并且项目 .codex/ 层需要被信任才会加载。

注意：

多个地方的 hooks 会合并执行，不是覆盖。

这和 AGENTS.md 不一样。

AGENTS.md：更像后面的规则优先级更高
Hooks：只要事件和 matcher 匹配，就都会运行

Hooks 的典型事件

事件	适合做什么
SessionStart	会话开始时加载备注或补充上下文
UserPromptSubmit	用户提交 prompt 时检查敏感信息
PreToolUse	工具执行前阻止危险操作
PermissionRequest	权限请求出现时自动允许或拒绝
PostToolUse	工具执行后检查输出
Stop	回答结束时自动记录或要求继续

例如：

PreToolUse：阻止 rm -rf、git reset --hard 等危险命令
PostToolUse：检查测试输出
Stop：把当前问答写入每日记录

用户级 Hook 和项目级 Hook

如果 hook 配置在：

C:\Users\your_username\.codex\config.toml
C:\Users\your_username\.codex\hooks\daily_qa_log.py

它就是用户级 hook。

它理论上会对这个 Windows 用户下的所有 Codex 项目生效。

如果 hook 配置在：

D:\your_project\.codex\config.toml
D:\your_project\.codex\hooks\daily_qa_log.py

它才是当前项目级 hook。

用户级 daily log hook 的特点是：

hook 本身：用户级，跨项目可用
日志文件：根据当前 cwd 写到当前项目的 技术文档/每日记录/

.rules、Hooks、AGENTS.md 的区别

这三个机制初学者容易混。

可以这样区分：

机制	解决什么问题
AGENTS.md	项目规则和上下文
Skills	可复用任务流程
.rules	命令权限控制
Hooks	生命周期自动化脚本

.rules 控制的是命令能不能运行。

常见 decision：

allow
prompt
forbidden

Hooks 是脚本机制，可以在工具使用前后做检查。

AGENTS.md 是软规则，主要影响模型行为。

多智能体系统：不是越多越好

每日记录里还讨论了多智能体系统。

核心结论是：

多智能体系统不是越多越好。

如果一个智能体成功率是 90%，把三个智能体串联起来，整体可靠性不一定更高，反而可能因为每一步都可能失败而下降。

多智能体会增加：

• 延迟。
• 成本。
• 状态管理复杂度。
• 交接错误。
• 调试难度。

所以普通任务不应该强行拆成多个智能体。

单智能体代码审查的问题

代码审查需要两种不同能力：

1. 理解代码改了什么
2. 找出代码里的风险和漏洞

单智能体同时做这两件事时，容易先进入“解释模式”。

例如一个发票折扣功能：

return subtotal * (1 - discount_pct)

如果 discount_pct 直接来自用户输入，而且没有校验，就会有风险：

discount_pct < 0：价格被抬高
discount_pct > 1：总价变成负数
没有新增边界测试
功能开关直接 100% 上线

单智能体可能只发现“缺少测试”和“建议加类型提示”，却漏掉计费逻辑风险。

双智能体方案为什么有效

双智能体有效，不是因为“数量变多”，而是因为任务拆分合理。

可以拆成：

Analyzer：分析器，只负责理解变更
Risk Reviewer：风险审查器，只负责质疑假设

Analyzer 输出结构化对象，例如：

变更目的
受影响文件
变更接口
配置变更
迁移风险
代码作者隐含假设
涉及测试
可能需要补充的测试

Risk Reviewer 再基于这个对象提问：

这个假设有没有被代码保证？
用户输入有没有校验？
测试有没有覆盖边界条件？
功能开关是否上线太激进？
有没有业务逻辑风险？

这套设计的本质是：

一个负责建立上下文
一个负责挑战上下文

这和 AGENTS.md、Skills、Hooks 的分工是一致的：不要让一个东西承担所有职责。

Human-in-the-loop：严重问题要让人确认

双智能体代码审查还有一个重要环节：人工介入，也就是 Human-in-the-loop。

如果 Risk Reviewer 发现了严重问题，例如：

用户输入未校验
折扣可以小于 0 或大于 1
缺少边界测试
功能开关 100% 立即上线

系统不应该直接把这些结论发到 GitHub 或强行阻塞流程。因为 AI 也可能误判。

更稳妥的方式是：

发现 critical/high 风险
↓
暂停工作流
↓
把结构化发现交给人工审核
↓
人工选择接受或删除部分发现
↓
工作流继续输出最终审查结果

在 LangGraph 这类工作流里，可以用类似下面的机制表示：

interrupt()
Command(resume={...})

interrupt() 表示暂停，让人看当前的风险发现；Command(resume=...) 表示人工给出决定后，工作流从暂停点继续。

这说明多智能体系统不只是“多个模型聊天”。可靠的多智能体系统还需要：

结构化交接
风险分级
人工确认
可恢复的执行状态

多智能体什么时候值得用

每日记录总结了三类适合多智能体的场景。

第一类是对抗性任务。

例如：

一个智能体写代码
另一个智能体找漏洞

一个智能体写邮件
另一个智能体检查合规风险

第二类是工具隔离任务。

例如：

一个智能体访问网页
另一个智能体执行数据库查询

这样可以降低安全风险。即使网页内容包含提示注入，也只影响负责网页的智能体，不直接影响数据库执行智能体。

第三类是大规模上下文处理任务。

例如：

多个小智能体并行读取 100 个日志文件
每个智能体提取关键错误
最后交给一个高级智能体做判断

多智能体什么时候不该用

如果任务很简单，或者不能清晰拆分，就不要强行使用多智能体。

这种情况下，一个设计良好的单智能体，加上清晰 prompt、严格工具边界和干净状态结构，通常更可靠。

Codex、Claude、多智能体的共同本质

看起来这些话题不同：

AGENTS.md
CLAUDE.md
Skills
Hooks
.rules
多智能体

但它们背后的本质是同一个：

把上下文、任务流程、权限边界和角色职责拆清楚。

更完整地说：

问题	机制
AI 进入项目前应该知道什么	AGENTS.md / CLAUDE.md
某类任务怎么重复执行	Skills
哪些命令可以运行	.rules
某个生命周期节点要自动做什么	Hooks
不同思维模式如何分工	多智能体

这就是上下文工程。

应该选择 Codex 还是 Claude Code

如果你更需要：

• 仓库内执行。
• 长时间任务。
• 自动化记录。
• 可复用 skills。
• hooks 和 rules。
• 精简上下文。

更适合用 Codex。

如果你更需要：

• 架构讨论。
• 探索性规划。
• 长背景分析。
• 创意性方案比较。
• 用一个较详细文件承载项目背景。

更适合用 Claude Code。

两者可以一起用

同一个项目可以同时存在：

AGENTS.md
CLAUDE.md

推荐分工是：

Claude Code：用来想清楚
Codex：用来做清楚

更具体地说：

• 用 Claude Code 做架构探索、方案讨论、背景梳理。
• 用 Codex 做仓库修改、文档生成、skills 调用、hooks 自动化。
• 用 CLAUDE.md 保存较完整背景。
• 用 AGENTS.md 保存精简执行规则。
• 用 Skills 保存可复用流程。
• 用 Hooks 保存必须自动执行的动作。

不要直接把 CLAUDE.md 改名成 AGENTS.md

这是一个常见误区。

虽然两者概念相似，但不建议直接把 CLAUDE.md 改名成 AGENTS.md。

更好的迁移方式是：

从 CLAUDE.md 提炼始终相关的执行规则 -> AGENTS.md
把专项流程拆成 Skills
把确定性动作写成 Hooks
把历史记录放进文档

这样才能发挥 Codex 的分层优势。

初学者推荐配置

如果你刚开始建立 AI 编程工作流，可以这样配置。

Codex 侧

~/.codex/AGENTS.md
项目根目录/AGENTS.md
项目根目录/.agents/skills/
~/.agents/skills/
~/.codex/config.toml
~/.codex/hooks/
~/.codex/rules/default.rules

职责：

路径	作用
~/.codex/AGENTS.md	个人全局偏好
项目根目录/AGENTS.md	项目规则
.agents/skills/	项目本地技能
~/.agents/skills/	全局技能
config.toml	Codex 配置
hooks/	自动化脚本
rules/default.rules	命令权限规则

Claude Code 侧

CLAUDE.md
~/.claude/CLAUDE.md

职责：

路径	作用
CLAUDE.md	项目背景、架构意图、团队约定
~/.claude/CLAUDE.md	个人全局偏好

实践建议

对初学者来说，不要一开始就追求复杂。

可以按这个顺序：

1. 先写一个简洁的 AGENTS.md。
2. 把重复任务拆成 Skills。
3. 配置 .rules 管住危险命令。
4. 配置 Stop hook 自动记录问答。
5. 把每日记录整理成博客。
6. 如果同时用 Claude，再写 CLAUDE.md 保存更完整背景。
7. 只有在任务确实需要不同角色分工时，再考虑多智能体。

总结

AGENTS.md 和 CLAUDE.md 的区别，不是文件名的区别，而是上下文组织方式的区别。

它们共同解决：

AI 编程代理进入项目时，如何获得稳定上下文。

但成熟的做法不是写一个越来越长的上下文文件，而是分层：

始终相关 -> AGENTS.md / CLAUDE.md
任务相关 -> Skills
权限相关 -> .rules
执行相关 -> Hooks
角色相关 -> 多智能体

当你理解这套分层后，Codex 和 Claude Code 就不再只是两个“聊天式编程工具”，而是可以被配置、复用、审计和持续改进的工程系统。