跳到正文
claudemods

agents-md:Claude Code AGENTS.md 支持,把它加载为项目指令

像加载 CLAUDE.md 一样把 AGENTS.md 文件加载为项目指令,在 /config 中提供四种模式。

权限

  • 拦截工具调用能看到 Claude 发起的每一次工具调用(tool.call / tool.check),并可以阻止或修改它。
  • 修改界面在 Claude Code 界面中绘制内容:横条、面板、状态文字、弹出通知(ui.render / $.ui.*)。
实测版本
v2.1.310
最近实测
需要
Claude Code ≥ 2.1.287
显示位置
无

在 Claude Code 中安装:

git clone https://github.com/anthropics/claude-code
claude --plugin-dir ./claude-code/mods/agents-md
全部安装方式 ↓

这个插件能做什么?

agents-md 是 Anthropic 提供的一款 Claude Code AGENTS.md 支持插件(anthropics/claude-code)。很多仓库把智能体指令写在 AGENTS.md 里,而 Claude Code 读取的是 CLAUDE.md。这个插件把 AGENTS.md 文件作为项目指令文件交给 Claude Code,因此模型看到它们的位置和包装方式与 CLAUDE.md 相同。

一个选项 instructionFiles 决定加载什么:

  • claude-md:只加载 CLAUDE.md,与现在的 Claude Code 一致,插件什么都不加。
  • claude-md-or-agents-md(默认):没有自己 CLAUDE.md 的项目改为加载它的 AGENTS.md 文件。
  • claude-md-and-agents-md:每个 AGENTS.md 都与 CLAUDE.md 一起加载。
  • managed-only:丢弃项目的和你自己的指令文件,保留组织的受管 CLAUDE.md 和记忆。

文件从文件系统根目录一直找到工作目录,AGENTS.md 和 .claude/AGENTS.md 都算。当 Claude 读取子目录中的文件时,该目录的 AGENTS.md 会附加在读取结果后面,就像 Claude Code 对嵌套的 CLAUDE.md 所做的那样。插件不在屏幕上绘制任何东西,它的效果体现在模型知道什么。

演示

录屏中,我们在小型演示项目里启动加载了该插件的 Claude Code。录制开始前,一行隐藏的准备命令在项目里写入一个简短的 AGENTS.md(两条规则:提交信息以工单号开头,如 DEMO-123;每次提交前运行 npm test)。项目里没有 CLAUDE.md。片段中我们问:“Without reading any file: what does my AGENTS.md say about commit messages? One sentence.” Claude 大约两秒内回答提交信息以工单号开头,如 DEMO-123,没有调用任何工具,因为该文件已经在它的上下文中。

安装

使用安装区块中的任意一种方式;它们都从 anthropics/claude-code 仓库安装。该仓库没有列出此插件的 marketplace.json,所以安装区块以仓库本身作为来源。默认模式无需配置:在有 AGENTS.md 且没有 CLAUDE.md 的项目里开始会话即可。

$ install agents-md

需要 Claude Code ≥ 2.1.287

从作者自己的 marketplace 安装: anthropics/claude-code

  1. 1.免安装试用

    git clone https://github.com/anthropics/claude-code
    claude --plugin-dir ./claude-code/mods/agents-md

    仅在当前会话中加载该插件,不会写入你的设置。

工作原理

hooks/register.ts 是 hooks/hooks.json 中唯一的模块,hooks/ 下的其他文件都是它导入的小型辅助模块。在两种加载模式下,prompt.context 钩子接收 Claude Code 已加载的指令文件,用 $.fs.ancestors 向上查找 AGENTS.md,并把新文件作为 project 文件加进列表后返回。下面是查找部分,来自 hooks/register.ts:

const found = isClaudeProject
  ? NONE
  : await $.fs.ancestors({ names: Names.AGENTS_NAMES }).catch(() => {
      isWalkFailed = true

      return NONE
    })
const added = Files.unseenFiles(Files.filesOf(found), handed)

unseenFiles 会丢弃 Claude Code 已持有路径的文件,或文本与已交给的项目文件相同的文件(例如指向 AGENTS.md 的 CLAUDE.md 符号链接)。Read 上的 tool.call 钩子先让读取完成,然后对项目根目录下的文件,把根目录与该文件之间各目录的 AGENTS.md 以 Contents of <path>: 的形式附加,每个智能体循环只附加一次。针对 fork 的 agent.spawn 钩子会复制父级已送达的集合,避免 fork 重复收到同样的文件。

自定义

选项是 /config 中的“Project instructions”一行,可在四个值中选择。手动设置时,写在用户设置、--settings 或受管设置里(项目的 .claude/settings.json 不会被读取为插件选项):

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

用 claude --plugin-dir mods/agents-md 运行时,同样的条目键名为 "agents-md"。旧键 projectInstructions 在 instructionFiles 被设为非默认值之前仍然有效。作者的 README 列出了 AGENTS.md 与 CLAUDE.md 仍有差异的八处,例如 --add-dir 目录不提供 AGENTS.md,/memory 也不认识这些文件。

权限与安全

我们读过插件可以执行的每一个文件:plugin.json、hooks/hooks.json、hooks/register.ts,以及它导入的 hooks/ 下所有辅助模块和测试。没有 package.json、安装脚本、二进制文件或打包代码,源码中也没有非 ASCII 字符。

  • 读取文件。 $.fs.ancestors 沿目录树向上读取 AGENTS.md 和 .claude/AGENTS.md(并查找 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md)。它们的文本会作为项目指令交给模型,所以你不信任的 AGENTS.md 也能像 CLAUDE.md 一样左右 Claude。
  • 读取环境变量。 HOME、USERPROFILE、CLAUDE_CODE_SIMPLE 和 CLAUDE_CODE_DISABLE_ATTACHMENTS,只用于解析 ~ 路径,以及在 Claude Code 不附加任何内容时跳过附加。它不写入环境变量。
  • 拦截工具调用。 Read 上的 tool.call 钩子和针对 fork 的 agent.spawn 钩子会等调用结束后返回其结果,只在读取成功后追加上下文,从不拒绝调用。claude plugin validate 提示这两个钩子都没有 .catch。
  • 遥测。 它用计数和固定选项(模式、文件数和导入数、总长度、几个标志)调用 $.telemetry.log 和 $.telemetry.mark。README 说明其中没有路径和文本,并且在没有安装 Anthropic 的 telemetry 插件时这些记录会被丢弃。我们没有检查那个插件。
  • 无网络、无进程、无写入、无守护进程。 插件不使用 fetch、shell、$.fs 写入或后台定时器。它只会通过 $.ui.log 写一行调试日志:no CLAUDE.md found; AGENTS.md loaded: <paths>。
  • 许可证。 仓库的 LICENSE.md 写着“© Anthropic PBC. All rights reserved”,使用受 Anthropic 商业条款约束,因此本页标记为 redistributable: false。我们只链接代码,不做镜像。

claude plugin validate 没有报告错误。它只给出了插件目录“没有图标”的非阻塞警告、上面提到的两条缺少 .catch 的提示,以及 README 没有安装行的建议。作者的 5 个测试在 Claude Code 2.1.310 上全部通过。

拦截工具调用
能看到 Claude 发起的每一次工具调用(tool.call / tool.check),并可以阻止或修改它。
修改界面
在 Claude Code 界面中绘制内容:横条、面板、状态文字、弹出通知(ui.render / $.ui.*)。

兼容性与故障排除

已在 macOS 上使用 Claude Code 2.1.310 检查(validate、测试和演示录制)。README 把它描述为内置插件(agents-md@builtin),所以自带它的 Claude Code 版本可能已经在加载;/plugin 会列出内置插件,可在那里关闭。如果你的 AGENTS.md 没有被读到:

  • 检查从根目录到工作目录之间是否有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。在默认模式下,其中任何一个都会让插件退让。
  • 检查 /config 中的选项不是 claude-md 或 managed-only。
  • 在 --bare 或 --safe-mode 运行中,或设置了 CLAUDE_CODE_DISABLE_CLAUDE_MDS 时,Claude Code 不加载任何指令文件;设置 CLAUDE_CODE_DISABLE_ATTACHMENTS 时会跳过嵌套附加。
  • 在瘦客户端上插件什么也找不到,因为它的工作区文件在远端。
  • 修改选项后,新文件会随 Claude Code 下一次构建的上下文到达:下一轮对话、/clear 或一次压缩。

常见问题

不装这个插件,Claude Code 会读取 AGENTS.md 吗?
插件的 README 说明,引擎只加载 CLAUDE.md,插件在此基础上补充 AGENTS.md。把选项设为 claude-md 时,插件什么都不加,CLAUDE.md 照旧加载。
项目里同时有 CLAUDE.md 和 AGENTS.md 会怎样?
在默认模式 claude-md-or-agents-md 下,只要从根目录到工作目录之间任何位置存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md,插件就不介入。在 claude-md-and-agents-md 下两者都会加载,但会跳过 CLAUDE.md 已经导入或链接的 AGENTS.md。
它会把我的 AGENTS.md 内容发到别处吗?
代码不发网络请求,也不运行命令。它会把计数(文件数、导入数、总长度、模式)交给一个 telemetry 对象;README 说明这些记录只在安装了 Anthropic 的 telemetry 插件时才存在,其中没有路径,也没有文件内容。
怎样切换模式?
打开 /config,在“Project instructions”一行选择一个值,或在用户设置的 pluginConfigs 下设置 instructionFiles。修改会重新加载模块,引擎下次构建上下文时使用新模式。
我能把代码复用到自己的插件里吗?
不能直接复制。仓库的 LICENSE.md 写明保留所有权利,并受 Anthropic 商业服务条款约束,所以本页只链接到代码,不做镜像。
Context Inspector 在 Claude Code 中运行精选

Context Inspector

显示 Claude Code 上下文窗口被什么占满、其中有多少是重复读取和重复输出,以及压缩保留了什么。

  • 状态栏
  • 面板
  • 弹出通知
  • 写入文件
  • 拦截工具调用
  • 读取你的提示词
  • 修改界面
  • 添加命令/工具

已在 v2.1.303 实测

更多 计时、待办与站会。