Claude Code 现在可读取 AGENTS.md：CLAUDE.md 与 AGENTS.md 的区别及 .claude 目录

什么是 claude.md，你应该在其中写些什么？

CLAUDE.md 是一个纯文本 Markdown 文件，其中包含 Claude Code 会读取到会话上下文中的指令。你可以在这里记录原本需要反复说明的信息：构建和测试命令、编码约定、项目架构以及工作流规则。

文档没有规定的格式。你可以使用普通的 Markdown 标题和列表来组织内容，选择便于理解项目指令的结构。Claude Code 的 /init 命令会根据项目生成一个初始文件，具体说明见 官方最佳实践文档.

可以先从以下四个方面入手：

• 构建和测试命令： 贡献者构建项目和检查更改时应使用的命令。
• 编码规范： 与仓库相关的命名、格式及其他规范。
• 项目架构： 主要组件及其相互关系。
• 工作流规则： 你希望 Claude 在进行和检查更改时遵循的步骤。

将这些内容视为持久指导。指令会进入 Claude 的上下文，但并不是强制执行的配置。如果你需要配置 Claude Code 本身，请使用相应的设置文件，而不要指望 CLAUDE.md 中的文字能充当设置值。

组织仓库时，这一区别很重要：项目知识应放在指令文件中，应用配置则应放在设置中。 Claude Code 指南中心 可作为了解相关工作流的起点。

CLAUDE.md 应放在哪里

Claude Code 支持在多个位置存放共享项目指令和个人指令。 指令文件文档 介绍了这些既定位置，以及指令发现机制的工作方式。

祖先目录中的指令文件会在启动时加载。子目录中的文件则按需加载，让 Claude 在处理项目的相应部分时获得相关指令。

对于共享指令，请选择适合团队的位置。根目录下的 CLAUDE.md 会将指导内容与仓库中的其他顶层文件放在一起。 .claude/CLAUDE.md 会将其与项目中 Claude 专用的文件放在一起。

个人指令的影响不止于文件组织

CLAUDE.local.md 与共享项目文件的用途不同：它保存你针对该项目的个人指令。在 2.1.277 版本中，它是否存在还会影响 Claude Code 是否回退到 AGENTS.md.

这意味着，添加本地指令文件可能会改变哪些共享指令进入上下文。在依赖 AGENTS.md的仓库中创建此类文件之前，请检查下文介绍的“项目指令”设置。

上述位置来自持续更新的文档，其在 19 年九月的确切措辞尚未核实。下一节中的回退行为则有专门针对带标签的 2.1.277 版本的文档记录。

Claude Code 会自动读取 AGENTS.md 吗？

会，但有条件。 Claude Code 2.1.277 版本说明 中写道：“新增 AGENTS.md 支持：在没有 CLAUDE.md 的项目中，Claude Code 会改为读取 AGENTS.md”。

默认行为是一种回退机制，因此，仅仅存在一个 AGENTS.md 文件并不意味着它会被加载。在此版本中，检查范围不只包括根目录下的 CLAUDE.md.

什么会阻止默认回退？

从文件系统根目录到工作目录的路径上，任何位置只要存在以下任一文件，就会阻止默认的 AGENTS.md 回退：

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

托管指令、位于以下位置的个人指令 ~/.claude/CLAUDE.md，以及 .claude/rules/ 会 并不能 阻止该回退。

例如，假设一个仓库有共享的 AGENTS.md ，且祖先目录路径上没有符合条件的 Claude 指令文件。默认模式会读取 AGENTS 指令。如果你随后添加 CLAUDE.local.md，默认回退就会被阻止，即使新文件中包含的是个人指令，而非团队的共享指导。

AGENTS.md 的发现机制如何工作

内置支持由以下插件提供： agents-md 插件，版本为 0.1.0。它会发现以下两者： AGENTS.md 和 .claude/AGENTS.md ，搜索范围沿祖先目录路径展开；当 Claude 读取项目根目录下的文件时，它还会附加嵌套目录中的指令。

通过导入或链接已经加载的内容会被去重。如果 Claude 指令文件已经引入了相同的 AGENTS 内容，这一点就很重要。

截至 19 年九月的发布截止时间，版本公告表示，Bedrock、Vertex 和 Foundry 尚不支持此功能。

配置 Claude Code 以读取一个文件或同时读取两个文件

打开 /config 并更改 项目指令 ，以选择指令加载行为。 带有 v2.1.277 标签的插件 README 记录了四个确切的值。

README 对以下值有一项重要限定说明 managed-only：嵌套的 CLAUDE.md 附件仍可能被引入。不要将此值理解为保证任何嵌套的 Claude 指令内容都不会进入对话。

2.1.277 版本的确切配置

要加载这两类指令，请使用以下配置：

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

对于此版本，请将其放入以下位置的用户设置中 ~/.claude/settings.json、通过以下方式提供的文件中 --settings，或托管设置中。项目的 .claude/settings.json 确实会 并不能 提供这些插件选项。

更改会在下次重建上下文时生效，例如下一轮对话或新对话中。检查某项设置是否改变了已加载的指令时，请留意这一生效时机。

仍可选择导入共享指令

你也可以将 @AGENTS.md 放入相邻的 CLAUDE.md中。这会通过 Claude 指令文件显式导入共享指令。

Claude 指令文件的导入使用 @path/to/file.md ，并于 v0.2.107 中引入。2.1.277 版本会对已经通过以下方式导入的 AGENTS 内容进行去重 CLAUDE.md.

这为组织共享指导提供了两种方式：配置 Claude Code 以加载两个文件，或通过导入将 AGENTS 内容引入 Claude 指令文件。请选择能让仓库贡献者清楚理解两者关系的组织方式。

.claude 目录中应放哪些内容？

该 .claude 目录存放多种项目文件。它们的用途各不相同，因此请根据你编写的是持久指导、配置、可复用提示词、子代理定义还是操作流程来选择位置。

跨项目的个人设置存放在 ~/.claude/settings.json。个人子代理定义使用 ~/.claude/agents/，个人技能则使用 ~/.claude/skills/<name>/SKILL.md.

命令、子代理和技能

诸如以下这样的命令文件 .claude/commands/deploy.md 会创建 /deploy。2.1.3 版本合并了斜杠命令与技能，现有命令文件仍可与技能一起使用。

子代理定义使用带有 YAML 前置元数据的 Markdown。必填字段为 name 和 description；相关的可选字段包括 tools, model，以及 permissionMode。可通过以下方式管理它们 /agents，并参阅 子代理指南 来完成项目设置中的这一部分。

技能将可复用的操作流程打包在一个文件夹中，其中包含 SKILL.md，还可包含可选的脚本和参考资料。Claude 可以选择相关技能，你也可以通过以下方式调用技能 /skill-name；技能正文会在使用时加载。 技能指南 介绍了这一工作流程。

这些结构在引入 AGENTS 回退机制的版本发布之前就已存在。 带版本标签的更新日志 确认，项目设置、命令、代理和技能在 v2.1.277 时就已存在。详细的目录说明参考了持续更新的文档，但未核实这些文档在截止日期当天的确切措辞。

CLAUDE.md 与自动记忆的区别

CLAUDE.md 与自动记忆的区别在于内容由谁编写。你编写指令文件来定义项目指导规则；Claude 则将有用的上下文保存到自动记忆中。

带版本标签的更新日志记载，在以下版本中可以通过 /memory 进行自动保存和管理：2.1.59。因此，自动记忆与由你有意识地维护在以下文件中的指令承担不同的作用 CLAUDE.md 或 AGENTS.md.

决定信息应放在哪里时，应依据上述编写者的区别。将明确的构建命令、约定、架构说明和工作流程规则放入指令文件。使用 /memory 来管理 Claude 自动保存的有用上下文。

要点

• CLAUDE.md 包含 Claude Code 会读入上下文的持久性 Markdown 指令；它并不强制执行配置。
• Claude Code 2.1.277 增加了有条件的 AGENTS.md 回退机制，发布时不支持 Bedrock、Vertex 和 Foundry。
• 祖先目录中的 CLAUDE.md, .claude/CLAUDE.md，或 CLAUDE.local.md 会阻止默认回退。
• 将项目指令设为 claude-md-and-agents-md 即可加载两类指令。
• 在 v2.1.277 中，插件选项应放在用户设置、 --settings 文件或受管理设置中，而不是项目的 .claude/settings.json.
• 该 .claude 目录还存放设置、命令、子代理和技能；自动记忆则包含 Claude 保存的上下文。

常见问题

什么是 CLAUDE.md？

CLAUDE.md 是一个纯文本 Markdown 文件，包含 Claude Code 的持久性指令，例如构建命令、编码约定、架构说明和工作流程规则。Claude 会将它读入会话上下文，而 /init 可以根据项目生成初始文件。

当 CLAUDE.md 和 AGENTS.md 同时存在时，会加载哪个文件？

在 Claude Code 2.1.277 的默认 claude-md-or-agents-md 模式下，符合条件的 Claude 指令文件会阻止 AGENTS 回退。选择 claude-md-and-agents-md 即可同时加载两者，也可以使用以下引用方式导入相邻的 AGENTS 指令 @AGENTS.md ，将其放在 CLAUDE.md.

为什么添加 CLAUDE.local.md 会阻止 AGENTS 回退？

2.1.277 版本将 CLAUDE.local.md 列为会阻止默认回退的文件之一，只要在从文件系统根目录到工作目录的路径上找到它，就会阻止回退。因此，尽管该文件用于提供个人项目指导，它的存在仍可能改变共享的 AGENTS 指令是否会被加载。

我可以在项目的 .claude/settings.json 中启用这两个文件吗？

在 v2.1.277 中，项目的 .claude/settings.json 不提供 agents-md 插件选项。请使用 /config，或将文档中说明的 pluginConfigs 配置放入用户设置、 --settings 文件或受管理设置中。