---
title: "在 Claude Code 和 Codex 中使用 AGENTS.md"
description: "Codex 默认读取 AGENTS.md。Claude Code 2.1.277 及以上版本会在项目没有 CLAUDE.md 时读取它。如果两个文件都要保留，在 CLAUDE.md 中写上 @AGENTS.md。"
canonical: "https://logbrew.co/zh-Hans/guides/agents-md"
last_updated: "2026-11-10"
---

# 在 Claude Code 和 Codex 中使用 AGENTS.md

Codex 默认读取 `AGENTS.md`。Claude Code 2.1.277 及以上版本会在项目没有 `CLAUDE.md` 时读取它。如果两个文件都要保留，在 `CLAUDE.md` 中写上 `@AGENTS.md`。

2026年11月10日 用 Claude Code 2.1.319和Codex CLI 0.167.0 实测

作者 [Furkan Erday](https://github.com/furkanerday). Furkan Erday 是 LogBrew 的创始人，每天用 Claude Code 和 Codex 开发 LogBrew。

Canonical: https://logbrew.co/zh-Hans/guides/agents-md

## 各智能体何时加载 `AGENTS.md`

| 项目中有 | Claude Code | Codex |
| --- | --- | --- |
| 只有 `AGENTS.md` | 已加载 | 已加载 |
| `AGENTS.md` 和 `CLAUDE.md` | 未加载 | 已加载 |
| 导入了 `@AGENTS.md` 的 `CLAUDE.md` | 已加载 | 已加载 |
| 符号链接到 `AGENTS.md` 的 `CLAUDE.md` | 已加载 | 已加载 |
| `AGENTS.md` 和 `CLAUDE.local.md` | 未加载 | 已加载 |

我们读取了每个智能体在第一个请求中发送的指令。

## 用 1 个文件同时配置两个智能体

### 在项目根目录编写 AGENTS.md

把构建命令、测试命令和代码规范写进 1 个文件。两个智能体都会从 Git 仓库根目录一直读到你当前所在的文件夹。

### 更新 Claude Code

Claude Code 从 2.1.277 版本起会自己读取 `AGENTS.md`。更早的版本需要下一步中的导入。

```bash
claude update
```

### 在 CLAUDE.md 中导入 AGENTS.md

只要当前文件夹或上级文件夹中有 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，Claude Code 就不会读取 `AGENTS.md`。在 `CLAUDE.md` 中加入这一行，两个文件都会加载。

```bash
@AGENTS.md
```

### 或者把 CLAUDE.md 链接到 AGENTS.md

如果 `CLAUDE.md` 里只有这一行导入，不如直接把它换成符号链接。

```bash
ln -s AGENTS.md CLAUDE.md
```

### 或者用设置同时加载两者

如果要保留 `CLAUDE.local.md`，同时仍加载 `AGENTS.md`，把这段配置加入 `~/.claude/settings.json`。在会话中，`/config` 里的 Project instructions 选项可以设置同样的值。

```bash
{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

### 查看 Codex 加载了什么

在你工作的文件夹中运行这条命令。Codex 文档给出了这条命令，用来让 Codex 复述它加载的指令。

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

## 我们实测看到的结果

我们让两个智能体都连到本地测试服务器，读取它们在第一个请求中发送的指令。这样就能准确看到每个智能体加载了哪些文件。

项目中没有 `CLAUDE.md` 时，Claude Code 加载了 `AGENTS.md`，调试日志显示 `no CLAUDE.md found; AGENTS.md loaded`。旁边有 `CLAUDE.md` 时，Claude Code 没有加载 `AGENTS.md`。使用 `@AGENTS.md` 导入或符号链接时，`AGENTS.md` 的内容只出现一次。

上面的 `pluginConfigs` 设置加载了这两个文件，项目中有 `CLAUDE.local.md` 时也一样。

Codex 先加载 `~/.codex/AGENTS.md`，再加载根目录的 `AGENTS.md`，最后加载当前文件夹中的文件。`AGENTS.override.md` 会替换同一文件夹中的 `AGENTS.md`。在我们把 `CLAUDE.md` 加入 `project_doc_fallback_filenames` 之前，Codex 一直跳过它。两个文件都存在时，即使设置了备用文件名，Codex 也只加载 `AGENTS.md`。

## AGENTS.md 与 CLAUDE.md 的区别

Codex 会读取每个文件夹中的 `AGENTS.override.md` 或 `AGENTS.md`，以及全局的 `~/.codex/AGENTS.md`，默认总共最多 32 KiB。只有把 `CLAUDE.md` 列入 `project_doc_fallback_filenames`，Codex 才会读取它。

Claude Code 优先读取 `CLAUDE.md`。只有在没有适用的项目 `CLAUDE.md` 时，它才会读取 `AGENTS.md` 和 `.claude/AGENTS.md`。你个人的 `~/.claude/CLAUDE.md` 不算在内，所以它会和 `AGENTS.md` 一起加载。

## GitHub 上的反馈怎么说

#6235 有 409 条评论，请求 Claude Code 支持 AGENTS.md。2026 年 8 月 17 日，一位 Anthropic 工程师给出上面的导入和符号链接方法后关闭了它。现在 Claude Code 已经能自己读取这个文件。#31005 还请求支持 `.agents/skills/`，目前仍未关闭。

## 常见问题

### Claude Code 会读取 AGENTS.md 吗？

会，从 2.1.277 版本起，前提是当前文件夹及上级文件夹中都没有 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`。我们在 2.1.319 上验证过。

### 该用 AGENTS.md 还是 CLAUDE.md？

只要团队里有人用 Codex 或其他智能体，就用 `AGENTS.md`。`CLAUDE.md` 只放仅适用于 Claude Code 的规则，并在其中导入 `@AGENTS.md`。

### 可以把 CLAUDE.md 做成指向 AGENTS.md 的符号链接吗？

可以。在我们的测试中，Claude Code 只加载了一次链接的文件，和导入的效果一样。

### Codex 会读取 CLAUDE.md 吗？

默认不会。在 `~/.codex/config.toml` 中加入 `project_doc_fallback_filenames = ["CLAUDE.md"]`。

## 把生产环境错误交给你的智能体

接入 LogBrew MCP 服务器后，Claude Code 或 Codex 就能读取你批准的项目中的错误、日志和链路。免费额度充足，无需绑卡。

[连接你的智能体](https://logbrew.co/zh-Hans/agents)

## 参考来源

- [Claude Code docs, How Claude remembers your project](https://code.claude.com/docs/en/memory#agents-md)
- [Codex docs, Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235)
- [anthropics/claude-code#31005](https://github.com/anthropics/claude-code/issues/31005)

## 更多 AI 编程智能体指南

- [在 Claude Code 和 Codex 中添加 MCP 服务器](https://logbrew.co/zh-Hans/guides/mcp-server-claude-code-codex)
- [解决 Claude overloaded 529 错误和 rate limit 429 错误](https://logbrew.co/zh-Hans/guides/claude-overloaded-rate-limit-error)
- [修复 Claude Code、Codex 和浏览器 JavaScript 中的错误](https://logbrew.co/zh-Hans/guides)