我给 5 个 AI 工具写同一份说明书,两个月后 Claude Code 追上来了

行途导读

Claude Code 9 月 18 日那条更新，把我两个月前的一个土办法变成了官方支持。这篇讲清楚三件事：我的三个入口文件各管什么、为什么不能合成一份、以及同一周那次让所有网关用户集体报错的事故。

先说结论：一份共享规则加一份工具专属差异层，比给每个工具各写一份更省事；但升级前一定要先测网关，9 月 18 日那次事故就是教训。

1. 一条更新，把我两个月的做法合法化了

先说发生了什么。

9 月 18 日，Claude Code 发布 2.1.277，里面有一条不起眼的改动：项目里没有 CLAUDE.md 的时候，它会去读 AGENTS.md。

这条改动之所以值得说，是因为 AGENTS.md 本来就是个跨工具的民间约定。

不是 Anthropic 定的，是社区用出来的。Codex CLI 认它，OpenCode 认它，国内几个桌面端也认。Claude Code 这次等于官方承认了这个约定。

我看到这条的第一反应不是"好功能"，是"终于"。

因为我工作区里那份 AGENTS.md，两个月前就写着这么一段：

本文件是 Codex / 豆包 / OpenCode / ZCode / 千问办公 的入口；Claude Code 读 .claude/CLAUDE.md，WorkBuddy 读 .workbuddy/memory/MEMORY.md。各工具共享同一套规则 SSoT rules/RULES.md，不要各自维护一份规则副本。

五个工具读同一份，两个工具读自己的。这不是我设计出来的优雅架构，是被逼出来的——工具越来越多，每个都要求你给它写一份说明书，写第五份的时候我发现，前面四份里 80% 的内容是重复的。

2. 我的三个入口，各管什么

三个文件，职责不重叠。这是当前工作区的真实状态：

底下还有一层真正的事实源：rules/RULES.md，99 行，配 8 个分册文件（rules/RULES.d/ 下面按发布、安全、品牌、方法论、变现、防弹工作法、AI 使用约定分类）。三个入口都不抄它，只指向它。

再加一句量级：工作区里现在有 35 个 skill，触发条件、适用范围、彼此分工都写在触发规则表里。

这套东西的价值不在"看起来整齐"，在于换工具的时候不用重来。上个月我把三个定时任务从一个客户端迁到另一个，改的是调用方式，规则一行没动——因为规则不在那个客户端里，在 rules/RULES.md 里。

3. 为什么不干脆合成一份

有人会问：既然都指向同一套规则，为什么不干脆只留一个 AGENTS.md？

两个原因。

第一，工具能力不一样，一刀切会互相拖累。

Claude Code 有 hooks，能在命令执行前后插钩子；别的工具没有。我要是只在通用文件里写"必须在写文件前跑备份脚本"，对没有 hooks 的工具就是一句废话，它们只会靠"自觉"。

而自觉是不可靠的。专属文件存在的意义，就是把"这个工具能强制的"和"只能靠提示词的"分开写。

第二，记忆和规则是两种东西。

规则是规范的、稳定的，改一次要留痕。记忆是碎的、会过期的，今天踩的坑下个月可能就不成立了。

混在一个文件里，时间长了就会出现"这条到底还算不算数"的问题。我干脆把它们物理分开：规则进 rules/，记忆进 MEMORY.md，后者的每条都带日期，过期就删。

一句话：共享的是规则，不是文件；分开的是职责，不是内容。

4. 同一周的另一面：一次让网关用户集体报错的事故

这条更新不是那一周唯一的事。

2.1.277 发布前一天，2.1.275 出过一个回归：所有把 ANTHROPIC_BASE_URL 指向自建网关或代理的请求，全部返回 400 错误。Anthropic 当天发了 2.1.276 修掉。

如果你是普通用户，这条跟你没关系。但如果你在公司里跑自建网关——尤其是把 Claude Code 接到统一 LLM 网关后面的团队——那天下午是集体断线的。

第二天 9 月 19 日又发了 2.1.278，把 auto mode 的模型路由分类器挪到服务端执行，这一层的 token 开销不再计费。

/status 里新增一行 "Auto mode server"，可以确认当前会话的分类器到底跑在哪；如果静默回退到本地，它会警告你。

把这三件事放一起看，能看出一个节奏：这个工具平均每 0.9 天发一个版本，光这个月就发了 32 次，2.1.278 是今年第 223 次发布。

高频更新意味着一件事：不要把升级当成无风险动作。 我自己现在的做法是，凡是走网关的团队，升级前先在测试仓库里跑一遍，确认 ANTHROPIC_BASE_URL 那条链路没断，再全员推。

5. 如果你也要这么配，三个坑

坑一：别把差异层写成通用层的复制品。

我第一版 CLAUDE.md 就是复制 AGENTS.md 再改，结果两边都改的时候永远改不齐。后来我强制自己：差异层里只写"只有这个工具才有"的东西，写不出来就说明它该进通用层。

坑二：指向规则，不要抄规则。 一旦某个入口文件里出现了一份规则的副本，那份副本立刻开始腐烂——通用规则改了，副本不会跟着改。我在 AGENTS.md 里写了"不要各自维护一份规则副本"，就是给自己立的规矩。

坑三：记忆文件一定要带日期。 没有日期的坑会变成永久真理。我的 MEMORY.md 每条都标日期，超过一定时间的直接归档，不留在新文件里骗人。

6. 核心结论

三句话。

第一，跨工具的民间约定，正在被官方一个个收编。AGENTS.md 是这样，SKILL.md 也是这样。你按民间约定搭的东西，被收编的概率比你以为的高——所以按约定搭，比按某个工具的私有语法搭更安全。

第二，共享规则加专属差异层，是多人多工具场景下的最小结构。再复杂就过度设计，再简单就会开始复制粘贴。

第三，工具更新越快，你的升级流程越要保守。9 月 18 日那次事故不是 Anthropic 不靠谱，是高频发布天然会有回归。把"升级前先测网关"写进你的流程，比事后救火便宜得多。

最后说一句可能被误解的：我写这套结构不是为了"架构优雅"。是因为工具会换、会新增、会消失，而我要让规则活过工具。两个月前那个判断，现在被一条更新验证了。

信源

• Claude Code 官方变更日志：code.claude.com/docs/en/changelog

• Claude Code 2.1.278 发布页（含发布节奏统计）：havoptic.com/r/claude-code-2.1.278

• AI Coding Roundup · 2026-09-18：oday-bakkour.com/blog/ai-coding-roundup-september-18-2026

• AI Coding Roundup · 2026-09-19：oday-bakkour.com/blog/ai-coding-roundup-september-19-2026

如果对你有启发，欢迎点赞、在看、转发；星标「行途技术手记」，第一时间收到下一篇。

谢谢你看我的文章，下篇见。

© 行途 XingTu · AI 时代的工程师成长与效率提升

欢迎转载，注明出处 · 未经授权禁止用于 AI 训练

关键词：AI 工程化 / AGENTS.md / 行途技术手记