AGENTS.md 与跨 Harness 可移植性

它替你干掉什么：干掉四份会打架的仓库说明

第一条立刻能跑的用法

# 正本定为 AGENTS.md。Claude Code v2.1.277+ 且仓库里没有 CLAUDE.md：什么都不用做
# 验收：新开会话会出现一行  no CLAUDE.md found; AGENTS.md loaded: <路径>
# 要两份同时生效：/config → Project instructions → claude-md-and-agents-md

# 旧版本、或要追加只给 Claude 的话时，下面两种旧接法照旧可用（内容只会读一次）——
# ① 符号链接（不需要加 Claude 专属内容时最省事，成功时无输出）
ln -s AGENTS.md CLAUDE.md
# Windows 建符号链接要管理员权限，改用下面的 ② 

# ② 导入（还能在下面追加只给 Claude 的话）
# CLAUDE.md 内容：
@AGENTS.md

## Claude Code
改动 src/billing/ 下的代码时用 plan mode。

# 验收：新开一个会话，跑 /context，确认 Memory files 里出现 CLAUDE.md

# Gemini CLI 侧改一个设置就认 AGENTS.md（.gemini/settings.json）
{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }
# 看拼出来到底是什么：/memory show     重新扫盘：/memory reload

# 已经有 Cursor / Copilot 规则、想一次性收编进 Claude Code
/import                # v2.1.213+，连 MCP、命令、subagent、skill 一起搬

/import 和 /init 的区别值得记住：/init 是读旧规则、重新生成一份 CLAUDE.md（默认读 .cursor/rules/、.cursorrules、.github/copilot-instructions.md；设 CLAUDE_CODE_NEW_INIT=1 后还读 AGENTS.md、.devin/rules/、.windsurf/rules/、.clinerules）；/import 是一次性追加一份拷贝，并把 MCP server、命令、subagent、skill 一并搬过来。前者做归并，后者做搬家。

机制：它凭什么有效——因为它几乎什么都没规定

三种加载语义，别混着想

• 拼接（concatenation）：Claude Code 把工作目录及其所有上级目录里的 CLAUDE.md、CLAUDE.local.md 全部读出来拼进上下文，从文件系统根向下排序——离你启动位置越近的越靠后读。Codex 同理，从 git 根走到当前目录，再叠上全局 ~/.codex/AGENTS.md。
• 就近生效（nearest-wins）：Copilot 的口径是目录树里最近的那份 AGENTS.md 生效，而不是全拼。
• 路径域（path-scoped）：只有当 agent 碰到匹配的文件时才加载。Claude Code 的 .claude/rules/*.md 用 YAML frontmatter 的 paths: 字段，Copilot 的 .instructions.md 用 applyTo，Cursor 的 .mdc 用 globs。AGENTS.md 本身没有这个能力——这是它作为最大公约数的代价。

一条容易被忽略的性质

Claude Code 官方明确说：CLAUDE.md 的内容是作为系统提示之后的一条用户消息送进去的，不是配置，也不强制执行。所以「我明明写了却不照做」不是 bug，是这层机制的本性。真要钉死某个动作——比如提交前必须跑 lint——官方给的答案是写成 hook，钩子在固定生命周期点以 shell 命令执行，不取决于模型怎么想。这条对 AGENTS.md 同样成立，而且更甚：跨 harness 时你连对方有没有 hook 机制都不知道。

真实用法与边界：该写什么、不该写什么

官方瘦身判据（照抄可用）

反过来说，判断一条该不该进 AGENTS.md，问三个问题：① 新来的同事需不需要被告知这件事？需要 → 写。② agent 自己 grep 一下就知道吗？知道 → 删。③ 它只在某个子目录成立吗？是 → 挪到路径域规则里去（.claude/rules/ 加 paths:），别占用每次会话的上下文。

三个边界

嵌套不一定按你想的加载。Codex 的目录遍历是「git 根 → 当前目录」，不是「所有子目录」。openai/codex 的 issue #13288（2026-03-02 提出，现已关闭）报的正是这件事：在仓库根启动、改 go/ 下的代码时，go/AGENTS.md 不会被合并进来。Claude Code 的子目录 CLAUDE.md 则是按需加载——读到那个目录里的文件时才进上下文。同一份嵌套布局，在两个 harness 下行为不同。

monorepo 里会被别人的说明污染。Claude Code 给了 claudeMdExcludes（按 glob 匹配绝对路径），写进 .claude/settings.local.json 就只在你这台机器生效：

{ "claudeMdExcludes": ["**/monorepo/CLAUDE.md"] }

私人偏好不要进正本。CLAUDE.local.md（记得进 .gitignore）是给你自己的沙箱地址、测试数据用的。多 worktree 场景下它只存在于创建它的那个 worktree，官方建议改成从家目录导入：@~/.claude/my-project-instructions.md。新坑：在只靠 AGENTS.md 的仓库里加一份 CLAUDE.local.md，默认就会让 Claude Code 不再读 AGENTS.md（它也算「有 CLAUDE.md」）；要两份都读，把 Project instructions 设成 claude-md-and-agents-md。

代价与替代品：一份文件喂多个 agent，喂的是最小公分母

三条路，成本差一个数量级

• A · 原生读取，或一行符号链接。Claude Code v2.1.277+ 在没有 CLAUDE.md 的仓库里直接读 AGENTS.md，零操作；旧版本补一条 ln -s AGENTS.md CLAUDE.md（官方确认两种情况下内容都只读一次）。零依赖、零维护、正本唯一。什么时候不够：各家需要不同措辞时（比如只想让 Claude 用 plan mode）——改用 @AGENTS.md 导入再追加。注意一旦有了 CLAUDE.md，默认就只读它，所以导入那一行不能省。
• B · ruler（据 GitHub 仓库页 2026-09 约 2.9 千 star，MIT）。替你干掉：手工同步几十个 agent 的配置文件。怎么用：npx @intellectronica/ruler apply，正本放 .ruler/AGENTS.md，分发到 CLAUDE.md、AGENTS.md、.aider.conf.yml 等，README 列了 30 家目标（Copilot、Claude Code、Cursor、Windsurf、Cline、Aider、Codex CLI、Gemini CLI、Goose、Zed、Jules…），还能一并管 MCP 配置。什么时候别装：团队只用一两个 agent 时——它引入的生成产物和 CI 检查比省下的事还多。
• C · rulesync（据 GitHub 仓库页 2026-09 约 1.4 千 star，MIT）。替你干掉：同上，但它的强项在反向。怎么用：npm install -g rulesync；rulesync import 把已有配置吸进 .rulesync/，rulesync convert --from cursor --to copilot,claudecode 可以不采纳它的工作流、只做一次性格式转换；rulesync generate 才是常态分发。除 rules 外还覆盖 ignore、MCP、命令、subagent、skill、hooks。什么时候别装：只想做一次迁移的话，跑完 convert 就卸载，别把生成器留在仓库里。

不装任何东西，你还能怎么办

把正本写成 AGENTS.md，Claude Code（v2.1.277+）、Copilot 和 Codex 天然就读，Gemini CLI 侧改 context.fileName；还在用旧版 Claude Code 就补一条 ln -s。这几步覆盖了绝大多数人的全部需求，成本是零。只有当「每家还要一段自己的话」成为常态时，生成器才开始划算——那时你要维护的不再是一份文件，而是一份模板加 N 份差异。