Claude Code 原生支持 AGENTS.md:如何与 CLAUDE.md 协同使用

详解 Claude Code 原生支持 AGENTS.md 后的文件加载优先级、配置切换方式、旧方案迁移指南,以及如何结合 Apifox CLI 用同一份规则驱动多款编码智能体自动测试 API。

用 Apifox,节省研发团队的每一分钟

Claude Code 原生支持 AGENTS.md:如何与 CLAUDE.md 协同使用

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

Claude Code 对 AGENTS.md 的原生支持已在 v2.1.277 中正式上线[待核实:具体版本号及插件行为请以 Claude Code 官方更新日志为准]:在没有 CLAUDE.md 的项目中,Claude Code 现在会直接将你的 AGENTS.md 作为项目指令读取。你不再需要配置导入(Import)、符号链接(Symlink)或额外设置。如果仓库中同时存在这两个文件,Claude 默认只读取 CLAUDE.md,除非你在 /config 中切换 Project instructions 设置以同时加载两者。

如果你的团队混用多款编码智能体,那么 Codex 和 Cursor 已经在读取的同一份 AGENTS.md 现在也能直接引导 Claude Code 了。本文将全面解析文件优先级、旧方案迁移方法,以及如何在 AGENTS.md 中编写规则,让任意智能体都能通过 Apifox CLI 自动测试你的 API。

AI Coding 交流群

如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。

AI Coding 交流群二维码

Claude Code 中的 AGENTS.md 是什么?

AGENTS.md 是一个面向编码智能体的纯 Markdown 指令文件,用于定义构建命令、测试命令、代码风格和项目规范。从 v2.1.277 开始,Claude Code 通过内置插件直接读取该文件,因此原本为其他智能体配置好的代码仓库无需添加额外文件即可直接在 Claude Code 中生效。它没有任何必填字段或特殊语法要求。

该格式本身是完全开放的。AGENTS.md 官网将其描述为“一种用于引导编码智能体的简洁、开放格式”,目前已被超过 60,000 个开源项目采用,并由 Linux 基金会旗下的 Agentic AI 基金会负责维护。OpenAI Codex 与 Cursor 均已在官方文档中支持 AGENTS.md,而在本次更新之前,Claude Code 一直是尚未原生支持的主流工具。

如果是第一次接触这种格式,可以先了解如何为 API 开发团队编写 AGENTS.md 文件。

以下是来自 Claude Code 官方更新日志的版本演进记录[待核实]:

版本号 更新内容
2.1.277 新增 AGENTS.md 支持:当不存在 CLAUDE.md 时,Claude Code 会自动读取 AGENTS.md;可在 /config 的“Project instructions”下修改行为
2.1.280 /memory 和 /context 会列出 Claude 直接读取的 AGENTS.md 文件
2.1.281 AGENTS.md 支持扩展至 Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM 网关以及禁用遥测(Telemetry)的会话
2.1.285 内置插件的 ID 更名为 cc-plugin-agents-md@builtin(原为 agents-md@builtin)

在依赖上述特性前,请先运行 claude --version 确认版本。如果低于 2.1.277,Claude Code 会完全忽略 AGENTS.md。

CLAUDE.md vs AGENTS.md:哪个优先级更高?

默认情况下,CLAUDE.md 优先级更高。只有当工作目录及其所有上级目录中都不存在 CLAUDE.md 时,Claude Code 才会读取 AGENTS.md。Claude Code 内存文档明确列出了以下三种情况:

代码仓库中的文件状态 Claude Code 实际读取的内容
存在 AGENTS.md,且工作目录及上级目录中没有 CLAUDE.md 或 CLAUDE.local.md 读取你的 AGENTS.md
存在 AGENTS.md,同时工作目录或上级目录中存在 CLAUDE.md 或 CLAUDE.local.md 仅读取你的 CLAUDE.md 系列文件
存在通过 @AGENTS.md 导入了 AGENTS.md 的 CLAUDE.md 读取你的 CLAUDE.md,并通过导入机制一并加载 AGENTS.md
展示 Claude Code 文件加载决策流程的示意图:当文件夹或上级目录存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时仅加载 CLAUDE.md,否则加载 AGENTS.md,而在 claude-md-and-agents-md 设置下同时加载两者

并非所有文件都会触发互斥拦截。只有以下三种文件会阻止 AGENTS.md 加载:

  • 工作目录或上级目录中的 CLAUDE.md
  • 工作目录或上级目录中的 .claude/CLAUDE.md
  • 工作目录或上级目录中的 CLAUDE.local.md

而以下文件不会阻止 AGENTS.md,并会与 AGENTS.md 一起加载:位于 ~/.claude/CLAUDE.md 的用户级文件、组织下发的受管(Managed)CLAUDE.md,以及 .claude/rules/ 目录下的规则文件。

特别留意 CLAUDE.local.md 陷阱:如果你为了记录个人未提交的笔记而在本地新建了一个 CLAUDE.local.md,Claude 就会停止为你读取团队共享的 AGENTS.md。

Claude Code 会加载哪些文件,以及何时加载?

在没有拦截文件的情况下,Claude Code 的读取逻辑如下:

  1. 会话启动时: 读取工作目录及所有上级目录中的每一个 AGENTS.md 和 .claude/AGENTS.md。交互式会话会打印类似 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 的提示。
  2. 子目录中: 当 Claude 使用 Read 工具打开某个子目录中的文件,且该子目录自身没有 CLAUDE.md 时,按需加载该子目录的 AGENTS.md。
  3. 导入语句: AGENTS.md 内部的 @path 导入会被自动展开,同时 claudeMdExcludes 排除规则依然生效。

Claude Code 不会读取 AGENTS.local.md、AGENTS.override.md 或 .agents/ 目录下的任何内容。如果你与支持 AGENTS.override.md 的 Codex 共用同一个代码仓库,请务必注意这一点。

如何修改 Claude Code 加载的指令文件策略

在会话中输入 /config,可以将 Project instructions 设置为以下四个值之一[待核实]:

配置值 Claude Code 读取的内容
claude-md-or-agents-md 读取 CLAUDE.md;若不存在 CLAUDE.md 则读取 AGENTS.md(默认值)
claude-md-and-agents-md 同时读取两者,在每个目录中先读取 CLAUDE.md,再读取 AGENTS.md。已通过导入或符号链接引用的 AGENTS.md 不会被重复读取
claude-md 仅读取 CLAUDE.md 文件
managed-only 启动时仅读取组织受管的 CLAUDE.md 与自动记忆(Auto Memory)

对于大多数混用多工具的团队,claude-md-and-agents-md 是最理想的选项:它既能保留你个人的 CLAUDE.local.md,又能同时加载团队共享的 AGENTS.md。

你也可以直接在配置文件中写入该项设置。Claude Code 会从 ~/.claude/settings.json、--settings 指定的文件或受管设置中读取以下配置,但会忽略项目级和本地级配置文件中的同名项:

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

在 v2.1.285 之前,该内置插件的 ID 为 agents-md@builtin。2.1.285 及更高版本同时兼容新旧两个 ID,因此如果有旧版本客户端共享同一份配置文件,建议使用旧 ID。修改从你的下一条消息开始生效。

如果在 /config 中看不到 Project instructions 选项,说明当前会话无法加载 AGENTS.md:原因可能是你的版本低于 2.1.277、通过 /plugin 禁用了内置插件,或者这是你升级后的第一个会话(从下一个会话起才会生效)。

如何迁移旧版 AGENTS.md 变通方案

在本次更新前,许多团队通过手动变通方案把 AGENTS.md 接入 Claude Code。官方文档建议按以下方式处理:

你原有的旧方案 现在的推荐做法
包含 @AGENTS.md 的 CLAUDE.md 保持原样即可。导入机制不会导致 Claude 重复读取 AGENTS.md;只有当 CLAUDE.md 里没有其他任何内容时才考虑删除
用自然语言写着“请阅读 AGENTS.md”的 CLAUDE.md 将这句话替换为 @AGENTS.md,或者直接删除该文件。自然语言提示只有在 Claude 决定主动调用工具打开文件时才会生效
指向 AGENTS.md 的 CLAUDE.md 符号链接(Symlink) 无需任何操作。无论哪种方式,Claude 都只会读取一次内容
打印 AGENTS.md 内容的 SessionStart 钩子(Hook) 务必移除。否则 Claude 的上下文中会出现两份重复的内容

如果团队中还有人使用低于 2.1.277 的版本,请保留 @AGENTS.md 导入写法——这是唯一能在所有版本上稳定生效的方案。

选择导入(Import)还是符号链接(Symlink)?

如果你需要在共享文件之上补充 Claude 专属规则,请使用导入语法。Claude 会先读取被导入的文件,再读取其余内容:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

如果不需要任何 Claude 专属规则,也可以使用符号链接:

ln -s AGENTS.md CLAUDE.md

不过符号链接有两个坑:Claude 的 Edit 和 Write 工具无法穿透符号链接写入文件;而且在 Windows 上,除非开启了 core.symlinks,否则 Git 检出已提交的符号链接时只会生成一个单行文本文件。如果团队中有成员使用 Windows,请选择导入(Import)方案。

无论采用哪种方式,都可以在下一次会话中运行 /context all,确认 CLAUDE.md 或 AGENTS.md 已出现在 Memory files 列表下。

用同一份 AGENTS.md 统一驱动 Codex、Cursor 与 Claude Code

最大的收益在于实现“单一事实来源(Single Source of Truth)”。将构建命令、测试命令与代码规范放在仓库根目录的 AGENTS.md 中,Codex、Cursor 和 Claude Code 都能直接读取。

一份 AGENTS.md 文件同时驱动 Codex、Cursor 与 Claude Code 的架构图,并附带可选的 CLAUDE.md 通过 @AGENTS.md 导入及添加 Claude 专属规则

一套经受住实战检验的目录布局如下:

  • 根目录下的 AGENTS.md: 放置所有智能体都需要了解的通用信息——常用命令、目录结构说明、代码风格规范以及禁止修改的红线区域。
  • 大型子目录中的 AGENTS.md: 放置仅适用于该模块的局部规则,例如 services/payments/AGENTS.md。当 Claude Code 读取该文件夹下的文件时会自动按需加载。
  • 可选的 CLAUDE.md: 仅在需要配置 Claude 专属行为(如 Plan 模式或 Hooks)时创建,并在文件开头写上 @AGENTS.md。

注意一个细节:通过配置项自动加载的 AGENTS.md 不会触发 InstructionsLoaded 钩子,也不会从 --add-dir 附加目录中加载。如果你依赖这两项特性,请改用 @AGENTS.md 导入方式。

在 AGENTS.md 中教会智能体使用 Apifox CLI 测试 API

只需编写一次 API 测试规则,无论哪个智能体打开仓库,都会按照相同的标准流程运行测试。Apifox CLI 能为智能体提供结构化的 JSON 输出,让整个测试闭环留在终端内完成[待核实:以下 Apifox CLI 安装指南链接、版本号、子命令及参数请以 Apifox 官方文档为准]。

在每台机器上执行一次初始化安装:

npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_TOKEN>
apifox skill install

快捷方式:你也可以直接告诉智能体“读取 https://apifox.com/apifox-cli-installation-guide.md 并配置好 Apifox CLI”[待核实]。该指南专为智能体编写,涵盖了安装、登录与技能安装流程。

随后在你的 AGENTS.md 中添加如下段落:

## API testing (Apifox CLI)

- Apifox project ID: 123456. Staging environment ID: 7890.
- Never build Apifox JSON payloads from memory. Run
  `apifox cli-schema get <key>` first, then
  `apifox cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apifox endpoint list --project 123456` and its cases with
  `apifox test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apifox test-case create --project 123456 --file case.json`.
- Run cases with
  `apifox run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apifox unless the task asks for it.

现在,无论在 Claude Code、Codex 还是 Cursor 中,只需一句提示词即可完成工作:

I changed POST /orders to require a currency field. Update the Apifox test
case for it and run it against staging, following AGENTS.md.

智能体会严格遵循你的规则并依次执行如下命令:

apifox endpoint list --project 123456
apifox test-case list --project 123456 --endpoint <endpointId>
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox test-case create --project 123456 --file case.json
apifox run --test-case <caseId> --project 123456 -e 7890 -r cli,json

上述所有参数均来自 Apifox CLI 2.2.12 的 apifox <cmd> --help[待核实]。同一条 apifox run 命令加上 -r junit 即可直接嵌入 CI 流水线,而 --upload-report 则会将运行概览上传到客户端供团队查看。关于 Claude Code 端的详细配置,可参考如何在 Claude Code 中使用 Apifox CLI;Codex 用户则可参考在 Codex 中使用 Apifox CLI。

故障排查:为什么我的 AGENTS.md 没有加载?

  1. 检查路径上是否存在 CLAUDE.md。 工作目录或上级目录中的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 默认具有更高优先级;而用户目录的 ~/.claude/CLAUDE.md 不会造成拦截。
  2. 检查版本号。 运行 claude --version。你需要 2.1.277 或更高版本;如果在 Bedrock、Vertex AI、Foundry、网关或关闭遥测的环境下使用,则需要 2.1.281 或更高版本。
  3. 检查配置项。 打开 /config,确保 Project instructions 没有被设为 claude-md 或 managed-only。
  4. 确认是否已加载。 运行 /memory,在列表中查找是否存在 AGENTS.md 的文件路径。

常见问题(FAQ)

Claude Code 现在能直接读取 AGENTS.md 了吗? 可以,自 v2.1.277 起支持。只要工作目录或上级目录中没有 CLAUDE.md,Claude Code 就会自动将 AGENTS.md 作为项目指令读取。

如果同时存在 CLAUDE.md 和 AGENTS.md,Claude Code 会使用哪一个? 默认只使用 CLAUDE.md。你可以在 /config 中将 Project instructions 设为 claude-md-and-agents-md 来同时加载两者(先加载 CLAUDE.md)。

我应该删掉通过 @AGENTS.md 导入的 CLAUDE.md 吗? 没必要。导入语句绝不会让 AGENTS.md 被重复加载两次,而且还能兼容团队中仍在运行 2.1.277 之前旧版本的成员。只有当该文件不包含任何其他内容且所有人都已升级时,才建议删除。

Claude Code 会像 Codex 一样读取 AGENTS.override.md 吗? 不会。Claude Code 会忽略 AGENTS.override.md、AGENTS.local.md 以及 .agents/ 下的所有文件。

AGENTS.md 在 Amazon Bedrock 或 Google Vertex AI 上可用吗? 自 v2.1.281 起可用。在更早的版本中,Bedrock、Vertex AI、Foundry、网关或关闭遥测的会话仅读取 CLAUDE.md,在这些环境下请使用 @AGENTS.md 导入方案。