Claude Code 2.1.277 新增 AGENTS.md 回退功能并受特性标志限制

Claude Code 2.1.277 版于 2026 年 9 月 18 日正式发布，此次更新的核心亮点是原生支持 AGENTS.md 约定。AGENTS.md 是一种基于 Markdown 的元数据文件，旨在统一收集代码库的开发上下文、测试指令以及贡献规则，使得项目的指令信息能够集中管理，避免在多个工具之间重复编写相同的说明。

在新版本中，如果项目根目录缺失传统的 CLAUDE.md 文件，Claude Code 会自动回退读取 AGENTS.md，从而保证即使没有专门的 CLAUDE.md，团队仍然可以通过单一的 AGENTS.md 文件提供完整的指令集合。这一机制极大降低了新成员上手的门槛，也提升了跨工具协作的一致性。

配置与控制

系统管理员可以在 /config 菜单中自由切换 CLAUDE.md 与 AGENTS.md 的使用顺序。所做的选择会保存在本地配置文件中，但实际的功能开启依赖于内置插件的激活，而插件本身是由远程特性标志（feature flag）动态触发的，这一点在 Korben 的报道中已有详细说明。

特性标志的设计意味着如果组织出于安全或合规原因关闭了非必要的网络流量或遥测数据上报，特性标志可能无法成功加载。在这种情况下，Claude Code 会悄无声息地恢复到仅使用 CLAUDE.md 的旧行为，完全忽略 AGENTS.md，并且不会在 UI 中弹出任何错误提示，避免干扰用户的正常操作。

官方文档提供了一种兼容性变通方案：保留一个最小化的 CLAUDE.md 文件，仅在其中使用 @AGENTS.md 语法将 AGENTS.md 内容导入。这样即使特性标志获取失败，回退机制仍然能够生效，因为 CLAUDE.md 本身已经充当了 AGENTS.md 的桥梁。

兼容性概览

当前版本的 Claude Code 并未在首次推送时内置对 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 等主要云平台的直接集成。使用这些平台的开发者仍需依赖传统的 CLAUDE.md 或外部工具来提供指令元数据，直至后续的功能扩展正式加入对这些平台的原生支持。

值得注意的是，业界已有多款开发助理工具已经实现了对 AGENTS.md 约定的兼容，包括 Codex、Gemini CLI、Devin、Cursor 以及 GitHub Copilot。这些工具的提前支持为 Claude Code 的新特性提供了生态基础，使得在同一项目中切换不同 AI 助手时，指令文件的重复工作大幅度降低。

团队实用检查清单

• 确认 /config 中已将 AGENTS.md 设为指令来源
• 如果特性标志可能被阻断，确保 CLAUDE.md 仅用于导入 @AGENTS.md
• 在 UI 中验证 Claude Code 显示 “Loading project instructions from AGENTS.md”
• 确保遥测或隐私设置未阻止远程标志的获取

团队在实际使用时必须注意，仅凭软件版本号并不能直接证明回退功能已被激活。只有当 UI 明确显示已从 AGENTS.md 加载项目指令时，才能确认回退机制真正生效，否则可能出现看似正常但实际仍使用旧文件的隐蔽错误。

由于回退依赖远程特性标志，网络策略极其严格的组织需要将特性标志的服务端点列入白名单，或者在隐私设置中显式允许相关流量通过。否则，标志加载失败将导致回退失效，项目指令仍然只能通过 CLAUDE.md 提供，可能影响开发流程的连贯性。

在真实的开发场景中，AGENTS.md 回退的加入显著简化了新贡献者的入门流程。以前，新成员必须同时了解 CLAUDE.md 与项目特定的指令文件，而现在只需关注单一的 AGENTS.md，即可获得完整的上下文信息，这与其他 AI 助手保持了一致的使用体验，也大幅降低了维护多个指令文件的运营成本。

对于以中文为主要工作语言的组织而言，这一改进带来的好处尤为突出。开发者可以将所有项目指导集中写入 AGENTS.md，Claude Code 在检测到缺失 CLAUDE.md 时会自动读取该文件，并通过 UI 的提示与前述检查清单相结合，确保指令加载的透明度和可追溯性，从而提升团队协作效率。