@AGENTS.md 导入。实践上的最优解是“AGENTS.md 做单一事实源 + 各工具文件只留一行转发”，内容上遵循三条铁律：短（几十行而非几百行）、分层（根目录讲全局，子目录讲局部）、可执行（写成祈使句，能被工具强制的交给 hooks/lint，不靠模型自觉）。规则文件本身也是攻击面，来历不明的仓库里它就是提示注入的载体。问题源于一个朴素需求：AI 编程工具没有记忆，每次会话都要重新学习“这个仓库怎么干活”。于是每家工具发明了自己的记忆文件——Claude Code 的 CLAUDE.md、Cursor 的 .cursorrules、Gemini CLI 的 GEMINI.md。一个同时用三样工具的团队要维护三份内容雷同的文档，Gemin CLI 仓库的著名 issue（#1471）正是在抱怨这种碎片化。
2025 年春，OpenAI 随 Codex 推广 AGENTS.md：一个纯 Markdown、无专属语法、支持目录层级覆盖的开放格式。它没有官方标准组织，却因为“够简单、厂商中立”完成了事实标准化——截至 2026 年，agents.md 官网显示已有超过 6 万个开源项目采用，Cursor（2.0 版起）、Gemini CLI、Google Jules、GitHub Copilot、Aider、Zed、Windsurf、Devin、Amp 等 30 余个 agent 原生读取。Anthropic 的 Claude Code 虽仍以 CLAUDE.md 为主记忆，但支持通过 import 语法直接引用 AGENTS.md，等于变相兼容。
为什么这件事值得认真对待？因为规则文件是当前投入产出比最高的 AI 编程投资：一小时的编写，换来此后每次会话少说十遍废话、少跑十次弯路。它本质上是把“团队隐性知识”变成模型可执行的上下文。
| 文件 | 所属工具 | 加载机制 | 层级能力 | 建议定位 |
|---|---|---|---|---|
AGENTS.md | 开放格式（OpenAI 倡导） | Codex / Cursor / Gemini CLI / Copilot 等原生读取 | 支持嵌套：子目录文件覆盖父目录 | 单一事实源，写全部稳定规范 |
CLAUDE.md | Claude Code | 每次会话自动注入；/memory 编辑；支持 auto memory 自动积累 | 企业策略 / 用户全局 / 项目 / 本地四级 | 留一行 @AGENTS.md 转发 + Claude 专属差异 |
.cursor/rules/*.mdc | Cursor | 按 frontmatter 的 alwaysApply / globs 条件触发 | 多文件按 glob 匹配 | 放“改某类文件才生效”的局部规则 |
GEMINI.md | Gemini CLI | 分层读取；Context Forge 可从仓库自动生成 | 全局 / 项目 / 子目录 | 留一行引用 AGENTS.md |
.github/copilot-instructions.md | GitHub Copilot | 仓库级自动注入 | 单层 | 同步 AGENTS.md 要点 |
取舍建议很简单：AGENTS.md 为骨架，其余文件最多做转发和补充。旧版 .cursorrules 已被官方弃用，迁移到 .cursor/rules 目录即可；Claude Code 的 import 语法（@路径，最多递归约 5 层）足够把所有工具指向同一份内容。不要试图让每个工具的文件各写一套——那是在为未来制造漂移 bug。
规则文件写差的概率远大于写好。常见反模式：写成几百行的 wiki（模型注意力被稀释，等于没写）；写“我们要写高质量代码”这类口号（不可执行）；写了一年后没人删的过时规则（模型比新人更相信它，杀伤力翻倍）。
① 项目一段话：是什么、技术栈、谁在用。② 命令速查：pnpm dev / pnpm test --filter / pnpm lint --fix——让 agent 不再猜命令。③ 硬约束 5—8 条，全部祈使句：“改公共 API 必须跑 pnpm api:check”“禁止提交 .env”“新组件放 src/components/ui，样式用既有 token，不引入新 CSS 框架”。④ 边界：“不确定时先读 docs/architecture.md 再提问”。⑤ 子目录各放一个小 AGENTS.md，只写与父级不同的规则（如 packages/api/AGENTS.md 写迁移规范）。这个结构来自 agents.md 官方建议与各团队公开实践的交集。
判断一条规则该不该写，用两个测试：可执行测试（agent 能否据此改变行为？不能就删）；工具测试（这件事 lint / CI / hooks 能不能强制？能就移出规则文件，交给机器）。Claude Code 的 hooks、Cursor 的 lint-on-edit 就是为此准备的——规则文件管“判断”，工具管“执行”。
| 场景 | 该写进规则文件 | 不该写 / 该交给谁 |
|---|---|---|
| 命名与目录约定 | “测试文件与源文件同目录，命名 *.test.ts” | — |
| 提交卫生 | “提交信息用 conventional commits 格式” | 提交前强制检查 → commitlint / CI |
| 密钥安全 | “需要密钥时向用户索取，不要硬编码” | 兜底扫描 → pre-commit 的 gitleaks 钩子 |
| 代码风格 | — | 全部交给 formatter / linter，规则文件一个字都别写 |
| 业务背景 | “金额单位统一为分（整数）”这类模型猜不出的领域事实 | 长篇架构史 → 放 docs/，让 agent 按需检索 |
对独立开发者和小团队，规则文件之上还有一层可经营的机会：
docs/（领域知识，agent 按需检索）+ Anthropic Agent Skills 式的可复用技能包（2025 年 10 月推出，把“怎么做某类事”打包成带说明的资源目录）。三层各司其职，比塞爆一个文件有效得多。AGENTS.md，从 20 行起步：一段项目说明 + 常用命令 + 5 条硬约束，全部祈使句。@AGENTS.md 转发与各工具差异项；.cursorrules 迁到 .cursor/rules/*.mdc，用 glob 控制触发范围。