Claude Code兼容AGENTS.md：AI编程工具迈向统一项目指令，但Skills仍未统一

Claude Code加入AGENTS.md兼容能力

Claude Code从2.1.277版本开始支持AGENTS.md。当项目目录中没有自己的CLAUDE.md时，Claude Code会查找并加载AGENTS.md，用户也可以通过/config中的“Project instructions”调整行为。

该能力基于Claude Code Mods机制实现。Anthropic已将agents-md作为内置Mod，并在Claude Code官方GitHub仓库公开源码、测试和配置说明。

这项更新的直接意义，是已经采用AGENTS.md维护项目规则的团队，不必再专门为Claude Code复制一份内容相同的CLAUDE.md。但“支持”并不意味着两种文件格式和全部配套能力已经完全统一。

AGENTS.md为什么逐渐成为通用入口

AGENTS.md可以理解为写给编码智能体的项目说明书。它通常包含以下内容：

• 仓库结构与关键模块
• 依赖安装、构建和启动命令
• 测试、类型检查和代码格式化要求
• 编码风格与命名规范
• 允许或禁止修改的文件范围
• 数据库迁移、生成代码等特殊流程
• 完成任务前必须执行的验证步骤

README主要服务于人类开发者，AGENTS.md则强调让Agent快速掌握如何在仓库中安全工作。随着Codex、Cursor等工具采用或兼容这一入口，它开始具备跨产品项目规范的价值。

默认规则：CLAUDE.md仍然优先

Claude Code当前默认使用claude-md-or-agents-md模式。这不是同时加载，而是带有优先级的回退机制。

如果从项目根目录到当前工作目录的路径上存在项目级CLAUDE.md、.claude/CLAUDE.md或CLAUDE.local.md，Claude Code继续沿用原来的文件，内置Mod不会再为整个项目加载AGENTS.md。

只有不存在这些项目指令时，Claude Code才会读取路径上的AGENTS.md和.claude/AGENTS.md。因此，老项目升级后通常不会突然改变行为，也不会自动把两份指令合并。

子目录规则按层级加载

对于大型Monorepo，项目可以在不同目录放置独立的AGENTS.md。Agent读取子目录文件时，Mod会沿目录层级补充尚未加载的对应规则。

例如，根目录可以定义全局提交和测试要求，前端目录定义组件与样式规范，后端目录定义数据库和接口规则。这样能够避免把所有内容堆在一个超长文件中。

如果同级目录已有CLAUDE.md并接管该层级，默认模式仍遵循Claude Code原有规则。

四种项目指令模式怎么选

官方内置Mod提供四种instructionFiles模式。

claude-md-or-agents-md

默认模式。有CLAUDE.md就使用它；没有时回退到AGENTS.md。适合希望保持现有Claude Code行为，又要兼容其他Agent仓库的用户。

claude-md

只加载CLAUDE.md，完全关闭AGENTS.md补充。对依赖Claude专属上下文设计、暂时不准备迁移的团队更稳妥。

claude-md-and-agents-md

同时加载两类文件。适合把公共工程规范放在AGENTS.md，把Claude专属说明放在CLAUDE.md的团队。

官方实现会对已通过@导入、符号链接或内容相同的文件进行去重，但无法自动解决两份文件中的语义冲突。团队仍需明确优先级和职责边界。

managed-only

移除项目、本地和个人指令，只保留组织托管的CLAUDE.md与引擎记忆。它主要面向需要统一管控项目上下文的企业环境。

如何开启同时加载

用户可以直接在Claude Code的/config界面修改“Project instructions”，也可以在用户设置中配置：

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

该配置可放在~/.claude/settings.json、命令行--settings或组织托管设置中。官方说明明确指出，项目内的.claude/settings.json不会用于读取这一Mod选项。

配置变化会在下一次上下文构建时生效，例如下一轮对话、新会话、执行/clear或上下文压缩后。

为什么跨工具统一如此重要

避免维护多份相似规则

当团队同时使用Claude Code、Codex和其他Agent时，如果每个工具都有专属文件，测试命令和安全约束很容易出现版本差异。不同开发者使用不同Agent，最终得到的行为也会不同。

建立软链接或在CLAUDE.md中通过@AGENTS.md导入，曾是常见解决方案。但大型Monorepo会在多层目录中继承规则，人工维护链接和导入关系容易产生额外复杂度。

降低工具迁移成本

当核心项目规范跟随仓库，而不是绑定特定AI产品时，团队更容易试用或更换编码Agent。新工具只要理解通用指令，就能快速进入项目。

项目指令成为代码库基础设施

编码Agent已从偶尔使用的辅助工具变成日常开发入口。项目指令也不再只是个人偏好，而是与README、测试和CI类似的工程资产，需要代码评审、版本管理和持续维护。

兼容并不等于完全统一

Skills目录仍然分离

Claude Code使用.claude/skills等专属能力，而其他Agent可能采用.agents/skills。此次更新主要统一项目指令入口，并没有自动兼容所有技能目录、命令和插件格式。

团队仍需决定哪些内容属于跨工具规范，哪些能力依赖某个平台。强行把平台专属指令放入公共文件，反而可能让其他Agent误解。

系统提示词和执行框架不同

即使读取同一份AGENTS.md，不同模型和Harness对指令的理解、工具调用与权限控制仍然不同。同一规则不会保证完全一致的执行结果。

Anthropic此前强调，Claude模型对Skills、系统提示词和项目上下文的组织方式有特定偏好。通用入口解决的是维护成本，不会抹平模型与产品设计差异。

当前Mod仍有实现边界

官方文档列出了agents-md与引擎原生CLAUDE.md行为的差异。例如，部分嵌套规则主要在文本Read时附加，而IDE选中文件、提示词中的@引用或其他工具路径未必触发完全相同的加载行为。

因此，生产项目不应只因为“已支持”就删除原有配置。迁移前应验证实际上下文和关键任务。

团队如何平稳迁移

先划分公共与专属规则

跨工具都要遵守的构建、测试、安全和目录规范放入AGENTS.md；Claude独有的技能、命令或上下文要求保留在CLAUDE.md。

不要复制两份完整内容

重复文件会增加上下文占用和同步风险。如果使用同时加载模式，应避免两边出现相同但稍有差异的规则。

让规则可执行、可验证

与其写“保证代码质量”，不如明确写出测试命令、允许改动范围和验收条件。高质量项目指令应该帮助Agent做出确定决策。

用CI守住硬约束

项目指令只能影响模型行为，不能替代自动化检查。格式化、静态分析、测试、依赖审计和密钥扫描仍应由CI强制执行。

在典型任务上做回归测试

迁移后可选取修复Bug、添加接口、修改数据库和更新文档等任务，分别用不同Agent验证加载结果、命令执行和最终差异。

Claude Code Mods释放了什么信号

AGENTS.md支持建立在Claude Code Mods之上。公开实现显示，Mod可以通过prompt.context调整发送给模型的项目指令，也能参与会话启动、Agent派生和文件读取事件。

这意味着Claude Code未来可能允许开发者更深入地定制Harness，而不仅是增加一个外部工具。团队可以围绕上下文选择、合规要求或内部工作流开发自己的Mod。

但Mods仍处于逐步推出阶段，接口和行为可能变化。企业应锁定版本、保留测试，并避免未经验证就把实验性Mod用于关键仓库。

总结

Claude Code支持AGENTS.md，推动AI编程工具向共享项目指令靠拢。对于多Agent团队，这是减少重复配置和降低迁移成本的重要一步。

不过，当前默认仍是CLAUDE.md优先、AGENTS.md回退。两类文件同时加载需要手动配置，Skills、插件和系统提示词也尚未统一。更准确的判断是：主流工具开始共享“Agent README”，但完整的跨平台Agent标准仍在形成中。