Claude Code 兼容 AGENTS.md：版本要求、共存规则与迁移指南全解

Claude Code 从 Anthropic 发布的 v2.1.277 起可以原生读取 AGENTS.md，现有 Codex、Cursor 等多工具仓库不必再复制一套项目规则。默认情况下，仓库只有 AGENTS.md 时 Claude 会直接加载；如果路径上同时存在 CLAUDE.md 或 CLAUDE.local.md，则默认优先使用 Claude 文件，也可以在 /config 中把 Project instructions 调整为同时读取。对旧版本、第三方模型提供商或无法获取功能开关的环境，最稳妥的兼容方式仍是在 CLAUDE.md 中写入 @AGENTS.md。本文给出版本要求、共存矩阵、迁移步骤、验证方法与常见故障处理。

Claude Code 兼容 AGENTS.md，是指 Claude 能把该文件作为项目指令自动载入，而不是仅靠对话临时要求它读取文件。原生支持需要 Claude Code v2.1.277 或更高版本；不满足条件时可通过 CLAUDE.md 导入实现兼容。

Claude Code 是否原生支持 AGENTS.md？

Claude Code 已经原生支持 AGENTS.md，但支持状态取决于版本、项目中是否存在 Claude 专属指令文件，以及当前会话能否获取 Anthropic 的功能开关。

根据 Anthropic 2026 年官方文档，原生支持的最低版本是 v2.1.277。可以先检查本机版本：

claude --version

满足版本要求后，只有 AGENTS.md 的仓库可以直接被 Claude Code 使用，不需要额外创建 CLAUDE.md。如果当前会话看不到该能力，重新启动一次会话再检查，因为安装或升级后的第一个会话可能尚未启用该功能。

AGENTS.md 与 CLAUDE.md 有什么区别？

AGENTS.md 更适合作为跨工具共享的项目规范，CLAUDE.md 则适合承载 Claude Code 专属规则、导入和路径化配置。

AGENTS.md 官方站点在 2026 年称该格式已用于 超过 6 万个开源项目，并指出 OpenAI 主仓库当时包含 88 个 AGENTS.md 文件。这说明它已从单一工具约定发展为跨 Agent 的项目协作格式。

同时存在两个文件时，Claude 会读取哪个？

默认选择取决于当前工作路径上是否存在 CLAUDE.md 或 CLAUDE.local.md；需要双文件并存时，应显式选择同时读取，而不是假设 Claude 会自动合并。

在 Claude Code 中输入 /config，找到 Project instructions。需要共享规则与 Claude 专属规则同时生效时，将其设为 claude-md-and-agents-md；如果该选项完全不存在，当前会话通常不具备原生支持条件。

如何让 Claude 与其他 Agent 共用一份规则？

对需要同时服务 Claude Code 与 Codex 的仓库，维护一份 AGENTS.md 作为事实来源，再按兼容条件决定是否保留一个极薄的 CLAUDE.md。

方案一：直接使用 AGENTS.md

这是 Claude Code v2.1.277 以上、且仓库没有其他 Claude 指令文件时最简单的方案。

1. 在仓库根目录提交 AGENTS.md。

2. 写明构建、测试、格式化、安全限制和 PR 规则。

3. 启动新 Claude Code 会话。

4. 检查界面是否出现 AGENTS.md loaded，或直接询问当前项目指令。

方案二：从 CLAUDE.md 导入

旧版本、第三方模型提供商、关闭遥测或需要明确兼容时，可创建以下文件：

# CLAUDE.md

@AGENTS.md

## Claude-specific rules

- Use Claude Code subagents only for isolated tasks.

@AGENTS.md 是文件导入，不是让模型“自行决定是否读取”的自然语言提醒。Anthropic 文档说明，保留这种导入不会导致支持原生加载的新版 Claude 重复读取同一内容。

方案三：符号链接

纯 macOS 或 Linux 团队可以使用：

ln -s AGENTS.md CLAUDE.md

跨 Windows 团队更适合 @AGENTS.md 导入，因为 Windows 创建符号链接可能需要管理员权限或开发者模式，Git 也可能把链接检出成普通文本文件。

Monorepo 应该怎样组织 AGENTS.md？

Monorepo 的共享规则应放在根目录，子项目只补充局部差异，避免把所有语言和测试命令塞进一个超长文件。

repo/
├── AGENTS.md
├── CLAUDE.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── services/
    └── api/
        └── AGENTS.md

Codex 会从项目根目录向当前工作目录逐层合并指令，默认项目指令总量上限为 32 KiB，来源为 OpenAI 2026 年官方文档。Claude Code 建议单个 CLAUDE.md 控制在 200 行以内；文件虽然可加载到 4 MiB，但过长会占用上下文并降低规则遵循度，来源为 Anthropic 2026 年官方文档。

团队可以把稳定的跨工具约定留在 AGENTS.md，把 Claude 专属的按路径规则放到 .claude/rules/。在需要整合多款主流大模型与编程工具时，七牛云的 AI 编程工具配置大全可作为额外的配置索引，但不应替代仓库自己的规则文件。

AGENTS.md 不生效时如何排查？

Claude 没有读取 AGENTS.md 时，最常见原因是版本过旧、路径上已有 Claude 指令文件，或当前会话无法获取原生支持所需的功能开关。

1. 运行 claude --version，确认版本不低于 v2.1.277。

2. 检查当前目录及其上级目录是否存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。

3. 打开 /config，确认 Project instructions 不是 claude-md 或 managed-only。

4. 如果使用 Amazon Bedrock 或其他第三方提供商，改用 CLAUDE.md 中的 @AGENTS.md 导入。

5. 升级后新建第二个会话；首个会话可能只完成能力初始化。

6. 不要只看 /context 的 Memory files：Claude 直接加载 AGENTS.md 时，该文件不会显示在这里。

常见问题

Q：有 AGENTS.md 后还需要 CLAUDE.md 吗？

不一定。新版 Claude Code 且仓库没有 Claude 专属规则时，只保留 AGENTS.md 即可。需要 Claude 专属指令、旧版本兼容或第三方提供商支持时，再保留一个导入 @AGENTS.md 的精简 CLAUDE.md。

Q：Claude 会重复读取导入的 AGENTS.md 吗？

不会。Anthropic 官方文档明确说明，CLAUDE.md 保留 @AGENTS.md 导入时，无论 Project instructions 如何设置，都不会让同一份 AGENTS.md 被读取两次。

Q：如何确认 AGENTS.md 已加载？

原生加载时查看会话中的 AGENTS.md loaded 提示，或询问 Claude 当前项目指令。通过 CLAUDE.md 导入时，可运行 /context，此时导入链会作为 Memory files 的一部分出现。

Q：AGENTS.md 能替代权限与安全策略吗？

不能。它属于行为指令，不是强制执行层。必须禁止的命令、路径或工具调用，应使用 Claude Code permissions、hooks 或组织级 managed settings；不要只写一句“禁止执行”就视为安全控制。

Q：应该把所有项目文档都放进 AGENTS.md 吗？

不应该。只保留每次编码都需要的规则，例如测试命令、代码风格和安全约束。架构长文应放在独立文档中，按需引用，以减少上下文占用和冲突概率。

结论与参考资料

Claude Code 已经能够原生兼容 AGENTS.md，但可靠迁移的关键不是简单删除 CLAUDE.md，而是确认版本、共存策略和运行环境。跨工具团队可把 AGENTS.md 作为共享规则源，把 Claude 专属能力留在精简的 CLAUDE.md 或 .claude/rules/ 中。

本结论依据 Anthropic Claude Code 文档、OpenAI Codex 官方文档和 AGENTS.md 开放格式说明。本文内容基于 2026 年 9 月 20 日资料，后续版本可能调整默认加载策略，建议升级后重新运行 /config 和加载验证。

• Anthropic：How Claude remembers your project

• OpenAI：Custom instructions with AGENTS.md

• AGENTS.md 开放格式说明

• 七牛云AI 大模型广场