Source: https://aiprimetech.io/zh/blog/claude-code-agents-md-support/ 2026 年九月 19 日 · 8 分钟 · 开发者指南 # Claude Code 现在可读取 AGENTS.md：CLAUDE.md 与 AGENTS.md 的区别及 .claude 目录 A 作者 [AI Prime Tech](https://aiprimetech.io/zh/) · AI 辅助撰写 如果你在问“什么是 claude.md”，它是一个 Markdown 文件，用于向 Claude Code 提供有关项目和工作流的持久指令。Claude Code 2.1.277 于 2026 年九月 18 日发布，新增了对读取以下文件的支持 AGENTS.md ，前提是不存在符合条件的 Claude 指令文件。本指南介绍这种回退机制、如何加载这两个文件，以及设置、命令、子智能体和技能应放在以下目录中的哪个位置 .claude 目录。 ## 什么是 claude.md，你应该在其中写些什么？ CLAUDE.md 是一个纯文本 Markdown 文件，其中包含 Claude Code 会读取到会话上下文中的指令。你可以在这里记录原本需要反复说明的信息：构建和测试命令、编码约定、项目架构以及工作流规则。 文档没有规定的格式。你可以使用普通的 Markdown 标题和列表来组织内容，选择便于理解项目指令的结构。Claude Code 的 /init 命令会根据项目生成一个初始文件，具体说明见 [官方最佳实践文档](https://code.claude.com/docs/en/best-practices). 可以先从以下四个方面入手： - 构建和测试命令： 贡献者构建项目和检查更改时应使用的命令。 - 编码规范： 与仓库相关的命名、格式及其他规范。 - 项目架构： 主要组件及其相互关系。 - 工作流规则： 你希望 Claude 在进行和检查更改时遵循的步骤。 将这些内容视为持久指导。指令会进入 Claude 的上下文，但并不是强制执行的配置。如果你需要配置 Claude Code 本身，请使用相应的设置文件，而不要指望 CLAUDE.md 中的文字能充当设置值。 组织仓库时，这一区别很重要：项目知识应放在指令文件中，应用配置则应放在设置中。 [Claude Code 指南中心](/claude-code/zh/) 可作为了解相关工作流的起点。 ## CLAUDE.md 应放在哪里 Claude Code 支持在多个位置存放共享项目指令和个人指令。 [指令文件文档](https://code.claude.com/docs/en/memory) 介绍了这些既定位置，以及指令发现机制的工作方式。 | 位置 | 用途 | ./CLAUDE.md | 项目的共享指令 | ./.claude/CLAUDE.md | 存放在以下位置的共享项目指令 .claude | ~/.claude/CLAUDE.md | 跨项目的个人指令 | ./CLAUDE.local.md | 当前项目的个人指令 祖先目录中的指令文件会在启动时加载。子目录中的文件则按需加载，让 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 版本说明](https://github.com/anthropics/claude-code/releases/tag/v2.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](https://raw.githubusercontent.com/anthropics/claude-code/v2.1.277/mods/agents-md/README.md) 记录了四个确切的值。 | 值 | 行为 | claude-md-or-agents-md | 默认：使用 Claude 指令文件；不存在符合条件的 Claude 文件时，回退到 AGENTS | claude-md-and-agents-md | 同时加载 Claude 和 AGENTS 指令文件 | claude-md | 仅加载 Claude 指令文件 | managed-only | 保留托管指令和引擎记忆；从初始上下文中移除项目、本地和用户指令 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/CLAUDE.md | 共享项目指令 | .claude/settings.json | 可提交到仓库供团队使用的共享项目配置 | .claude/settings.local.json | 个人项目设置覆盖项 | .claude/commands/.md | 可复用的自定义斜杠命令提示词 | .claude/agents/.md | 项目子代理定义 | .claude/skills//SKILL.md | 可复用的操作流程，可选择附带脚本和参考文件 跨项目的个人设置存放在 ~/.claude/settings.json。个人子代理定义使用 ~/.claude/agents/，个人技能则使用 ~/.claude/skills//SKILL.md. ### 命令、子代理和技能 诸如以下这样的命令文件 .claude/commands/deploy.md 会创建 /deploy。2.1.3 版本合并了斜杠命令与技能，现有命令文件仍可与技能一起使用。 子代理定义使用带有 YAML 前置元数据的 Markdown。必填字段为 name 和 description；相关的可选字段包括 tools, model，以及 permissionMode。可通过以下方式管理它们 /agents，并参阅 [子代理指南](/zh/claude-code/subagents/) 来完成项目设置中的这一部分。 技能将可复用的操作流程打包在一个文件夹中，其中包含 SKILL.md，还可包含可选的脚本和参考资料。Claude 可以选择相关技能，你也可以通过以下方式调用技能 /skill-name；技能正文会在使用时加载。 [技能指南](/zh/claude-code/skills/) 介绍了这一工作流程。 这些结构在引入 AGENTS 回退机制的版本发布之前就已存在。 [带版本标签的更新日志](https://raw.githubusercontent.com/anthropics/claude-code/v2.1.277/CHANGELOG.md) 确认，项目设置、命令、代理和技能在 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 文件或受管理设置中。 [Claude](/zh/blog/tag/claude/)[编程](/zh/blog/tag/coding/)[智能体](/zh/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/zh/) 本博客由 AI Prime Tech 发布。文章借助 AI 辅助起草；在据此采取行动前，请对照官方文档核实模型 ID、价格和限额等特定版本的细节。 以更低价格接入 Claude API 一个 API 密钥即可使用 Claude Opus 5.5、Sonnet 5、Haiku 4.5 和 Fable 5.1，以及 GPT-6 个模型。按量付费，无需订阅。 [获取 API 密钥 →](/register) AI Prime Tech 是独立的第三方 API 网关。Claude™ 和 Anthropic® 是 Anthropic, PBC 的商标。此处不暗示任何关联或背书。