agents-md 是一个即插即用的 AGENTS.md 配置方案，能让 Claude Code、Codex、Cursor 等编码代理像高级工程师一样工作。当项目膨胀到几十个模块时，一份规则文件会让每次会话都背上无关内容。本文讲解 agents-md 的分片思路：用@imports 导入拆分规则、用paths 按路径分片，让代理只在触碰对应目录时才加载相关规则，把每次会话的 token 开销降到最低。

🧩 先判断：你真的需要分片吗？

在动手拆文件之前，先看官方给出的判断标准。agents-md 的 README 里说得很直白：

"Rare. But it happens on large codebases. Read the docs before you shard — most people don't need to."

—— README.md（分片章节）

也就是说：大多数项目用单份AGENTS.md就够了，分片是大型代码库的进阶操作。

为什么文件膨胀是个大问题？核心原因是上下文是稀缺资源。agents-md 在 AGENTS.md 的"会话卫生"一节明确指出：

• 累积了大量失败尝试的长会话，表现不如一份更好的 prompt 加新会话；
• 臃肿的规则文件会被代理整体忽略，而不是逐条执行。

分片的真正目标是：每次会话加载更少的 token，而不是为了多文件而多文件。

⚡️ 方案一：Claude Code 的 @imports 导入与 paths 分片

Claude Code 是唯一内置了完整分片能力的工具，它提供两层机制：

1. 用 @path/to/file.md 导入规则文件

如果你的CLAUDE.md变得过长，可以直接在文件内用@路径语法把规则拆到独立文件：

@src/backend/RULES.md @docs/conventions.md

被@引用的文件会在会话启动时一并加载，相当于把一份大文件拆成多个主题文件。

2. 用 .claude/rules/*.md 加 paths 做按路径分片

这是大代码库最值得用的技巧。把主题范围明确的规则放进.claude/rules/目录，并通过 frontmatter 声明paths:匹配模式——只有当 Claude 触碰匹配文件时，这份规则才会加载：

--- paths: - "src/backend/**" --- 后端目录只允许使用项目内封装的 HTTP 客户端，禁止直接引入新依赖。

效果是：改前端代码的会话完全不会加载后端规则，改 API 的会话才会自动带上——规则按需命中，而不是全程陪跑。

💡 官方提醒：Claude Code 本身会自动写入记忆（memory），分片规则不要重复发明这套机制。

🎯 方案二：Cursor 的 .cursor/rules/*.mdc

如果你主力使用 Cursor，思路完全一致：把规则写进.cursor/rules/*.mdc文件，并用**路径作用域（path scoping）**声明它生效的目录。

两者对比一目了然：

✅ 方案三：其他工具，一份 AGENTS.md 仍是正确答案

README 的结论很干脆："Everyone else: oneAGENTS.mdis still the right answer."

Codex、Cursor（主流程）、Aider、Windsurf、Copilot、Devin、Amp 等工具原生读取AGENTS.md这一个文件；只有 Claude Code 读CLAUDE.md、Gemini CLI 读GEMINI.md。agents-md 的解法是软链接统一入口，详见 README.md：

ln -s AGENTS.md CLAUDE.md ln -s AGENTS.md GEMINI.md

一份规则、一个事实来源（single source of truth），所有代理读同一份内容。

📉 分片之后：如何持续修剪规则

分片不是拆完就完事，规则文件是活的。agents-md 把修剪方法写进了自我改进循环，见 AGENTS.md：

• 每次代理犯错后先问一句：是缺规则，还是无视了规则？缺就加，无视就把规则写得更短、更具体、位置更靠前；
• 每几周做一次修剪，对每一行问："删掉它代理会犯错吗？"不会就删。

文件长度的经验值（出自 AGENTS.md）：

两个配套习惯：

1. Section 10（Project context）：把技术栈、构建/测试命令、目录布局填进 AGENTS.md，一次性填完，分片文件里就不必重复这些内容；
2. Section 11（Project Learnings）：由代理自己维护的经验区，见 AGENTS.md。每次纠正代理后追加一行具体规则（写"对 Y 场景总是用 X"，而不是"对 Y 要小心"），问题消失时及时删除。

📋 小结：三步走路线

1. 默认不分片——单份AGENTS.md+ 软链接，覆盖绝大多数项目；
2. 大代码库再分片——Claude Code 用@imports+.claude/rules/*.md的paths:匹配；Cursor 用.cursor/rules/*.mdc路径作用域；
3. 定期修剪——目标 100 行、上限 300 行，让每条规则都值得被加载。

相关原始文件：

• 主规则文件：AGENTS.md
• 安装与分片说明：README.md
• 许可证（MIT）：LICENSE