Claude Code开始支持AGENTS.md：跨工具项目指令终于能复用，默认仍以CLAUDE.md优先

核心消息：Claude Code加入AGENTS.md支持

Claude Code团队成员Thariq在X平台宣布，Claude Code开始支持AGENTS.md。相关功能从2.1.277版本开始提供，并建立在Claude Code Mods机制之上。官方仓库已经公开agents-md内置Mod的代码、测试和说明文档。

这项变化解决了一个长期存在的兼容问题：过去，Claude Code主要读取CLAUDE.md作为项目指令，而许多其他编码Agent采用AGENTS.md。同一个代码仓库为了适配不同工具，往往需要维护两份内容相似的说明。

不过，“支持AGENTS.md”不代表Claude Code默认会同时加载两类文件。官方当前默认策略是：项目存在自己的CLAUDE.md时继续使用它；只有项目没有相应Claude指令文件时，才回退读取AGENTS.md。

AGENTS.md解决什么问题

AGENTS.md是一种面向编码智能体的项目说明文件。开发团队可以在其中记录：

• 项目结构与关键目录
• 构建、测试和代码检查命令
• 编码风格与命名规范
• 禁止修改的文件或生成目录
• 提交前必须执行的验证步骤
• 特定模块的业务约束

它的作用类似“给AI开发者看的README”。当Agent进入仓库工作时，先读取这些约束，可以减少错误命令、无关改动和违反团队规范的代码。

与特定产品命名的CLAUDE.md相比，AGENTS.md更适合作为跨工具共享的项目指令。对于同时使用Claude Code、Codex及其他Agent的团队，这能降低重复维护成本。

默认加载规则并非两份文件叠加

官方agents-md文档提供四种instructionFiles模式。理解它们非常重要，否则项目可能出现指令未生效或重复加载。

claude-md-or-agents-md：默认模式

这是默认配置。Claude Code会优先检查项目是否已有自己的CLAUDE.md、.claude/CLAUDE.md或CLAUDE.local.md。

如果其中任何一个存在，内置Mod不会再为整个项目加载AGENTS.md；如果都不存在，则按Claude Code读取CLAUDE.md的方式加载路径上的AGENTS.md和.claude/AGENTS.md。

因此，已有CLAUDE.md的老项目升级后，行为通常不会突然改变。想测试AGENTS.md，不能只是在旁边新增文件并期待默认自动合并。

claude-md：只读取CLAUDE.md

该模式保持传统行为，完全不增加AGENTS.md。如果团队需要严格维持现有配置，可以使用这一选项。

claude-md-and-agents-md：同时读取

该模式会把AGENTS.md与CLAUDE.md一起作为项目指令加载，并覆盖从项目根目录到当前工作目录的层级结构。

如果CLAUDE.md已经通过@导入同一文件，或者两份文件实际是链接关系，Mod会按路径和内容去重，避免重复注入。

同时读取虽然灵活，但也可能产生冲突。团队应明确两类文件的职责，例如把跨工具规则放进AGENTS.md，只把Claude专属配置留在CLAUDE.md。

managed-only：只保留组织托管指令

该模式会从上下文中移除项目、本地和用户个人指令，仅保留组织托管的CLAUDE.md及引擎记忆。它更适合需要集中控制的企业环境，而不是普通个人项目。

如何配置项目指令模式

作为内置Mod时，用户可以在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或上下文压缩之后。

分层AGENTS.md如何工作

大型Monorepo通常不会只使用根目录的一份规则。前端、后端、移动端和基础设施目录可能各有不同的测试命令与代码规范。

在支持AGENTS.md的模式下，Claude Code会沿项目根目录到当前工作目录的路径查找指令文件。读取子目录中的文件时，还可以附加对应目录下尚未交付给当前Agent的AGENTS.md。

这意味着团队可以采用分层设计：

• 根目录保存全局架构、通用命令和安全约束
• frontend/AGENTS.md说明前端测试和组件规范
• backend/AGENTS.md说明数据库迁移和接口约束
• 更深层目录只记录该模块独有的要求

但官方也列出了当前Mod与引擎原生CLAUDE.md加载行为之间的一些差异。例如，部分嵌套文件主要在文本Read操作时附加，某些IDE选中文件、提示词@引用和非文本工具路径的行为仍不完全相同。

Claude Code Mods是什么信号

Thariq在推文中表示，AGENTS.md支持建立在Claude Code Mods之上，这是即将推出的Claude Code执行框架定制方式。agents-md属于内置Mod，但官方已经把实现放入公开仓库，开发者可以查看其Hook注册、上下文修改和测试方式。

从公开实现看，Mod可以通过prompt.context调整送入模型的项目指令列表，也能监听会话启动、Agent派生和文件读取等事件。这意味着未来开发者可能不只配置命令和工具，还能更细粒度地修改Claude Code如何构建上下文和运行Agent。

需要注意，Mods目前仍属于正在展开的能力。具体接口、配置名称和行为可能继续变化，生产环境不应只依据社交媒体片段进行升级。

对多Agent团队有什么价值

减少重复文件

过去同时使用多个AI编程工具时，团队可能维护CLAUDE.md、AGENTS.md以及其他产品专属规则。内容一旦不同步，Agent就会执行互相矛盾的命令。

现在可以把公共规范集中到AGENTS.md，再通过默认回退、同时加载或显式导入等方式让Claude Code使用。

降低工具迁移成本

项目指令不再完全绑定某个产品名称后，团队更容易比较或切换Agent。核心工程规则跟随代码仓库，而不是跟随开发者本机上的某个工具。

推动项目指令标准化

当多种编码Agent都能识别同一份说明，AGENTS.md有机会成为更通用的仓库级协作接口。它不能替代README、CI和测试，但可以为Agent提供一致的工作入口。

迁移时应该注意什么

不要直接复制两份相同内容

如果团队选择同时加载模式，把相同规则完整复制到CLAUDE.md和AGENTS.md会浪费上下文，也可能因后续修改不同步造成冲突。更好的办法是划分公共规则和工具专属规则，或者通过导入与链接减少重复。

保持指令简洁且可执行

项目指令应优先写具体命令、边界和验证要求，而不是堆砌背景介绍。比如“修改后运行某个测试命令”比“确保高质量”更容易被Agent执行。

用CI验证而不是只靠文本要求

无论AGENTS.md还是CLAUDE.md，都只是上下文指令，不能保证模型绝对遵守。格式检查、类型检查、测试和安全扫描仍应由CI强制执行。

升级后验证实际加载结果

已有CLAUDE.md的项目在默认模式下不会自动加载AGENTS.md。升级Claude Code后，应检查版本、/config选项和会话提示，确认实际使用的是哪种模式。

总结

Claude Code支持AGENTS.md，是AI编程工具从产品专属配置走向跨工具项目规范的重要一步。它让使用多个Agent的团队有机会维护一份共享指令，减少重复和迁移成本。

但当前默认逻辑仍然是CLAUDE.md优先、AGENTS.md回退，并非无条件同时读取。想要两者并用，需要在“Project instructions”中切换到对应模式。对于开发团队，最实际的做法是先梳理公共规则与Claude专属规则，再逐步迁移，并通过CI验证关键约束。