同一个仓库同时用 Codex、Cursor、Claude Code，最容易失控的不是模型，而是项目规则分叉。这里给出一套以
AGENTS.md为单一事实源、CLAUDE.md只负责导入、Cursor 按需扩展的项目结构，并附上可以直接改造的配置示例。
我最近越来越不喜欢在 Prompt 里反复告诉 Coding Agent：
这个项目用 pnpm。
不要直接改数据库表结构。
修改接口后记得跑测试。
src/generated 不允许手工修改。
公共 API 不能随便改字段名。
这些话说一次没问题。
麻烦的是，当一个项目同时开始用 Codex、Cursor、Claude Code 后，同一批要求很容易出现三份：
AGENTS.md
CLAUDE.md
.cursor/rules/*.mdc
开始时只是复制粘贴。
几周以后，问题就出来了。
我在 AGENTS.md 里把测试命令从：
npm test
改成：
pnpm test
结果 CLAUDE.md 还是旧的。
后来又给 Cursor 增加了一条：
禁止直接修改 src/generated/
但另外两个 Agent 并不知道。
这时候已经不是“哪个模型更聪明”的问题了。
你的项目实际上出现了三套互相漂移的 AI 开发规范。
我先去核了一下：三个工具现在到底分别认什么？
这一步很重要，因为不能为了所谓“统一配置”，自己发明一套工具根本不会读取的规则。
Codex：AGENTS.md 本来就是一等公民
OpenAI 当前文档里，Codex 会在开始工作前读取 AGENTS.md，而且支持从项目根目录继续向当前工作目录查找更具体的规则。
例如：
repo/
├── AGENTS.md
├── frontend/
│ └── AGENTS.md
└── backend/
└── AGENTS.md
越靠近当前工作目录的规则，可以表达越具体的约束。
所以对于 Codex，根目录直接保留：
AGENTS.md
就够了。
Cursor：现在也可以直接使用 AGENTS.md
Cursor 当前官方 Rules 文档除了 .cursor/rules/*.mdc，还明确提供了 AGENTS.md 这种更简单的项目级规则形式。
官方文档目前也支持在子目录放置嵌套的 AGENTS.md。
这件事对同时使用多个 Coding Agent 的项目很有价值。
因为以前很多人的目录是：
.cursor/
└── rules/
├── frontend.mdc
├── backend.mdc
├── database.mdc
└── testing.mdc
如果这些内容只是普通的项目规范，其实未必需要为了 Cursor 再完整维护一套。
.cursor/rules 更适合保留 Cursor 特有的：
- 文件路径匹配规则；
- 특정类型文件才加载的上下文；
- Cursor 专属工作流；
- 需要手动触发的规则。
普通项目约定，则可以尽量回收到 AGENTS.md。
Claude Code：它不直接读 AGENTS.md，但官方已经给了兼容办法
这里最容易写错。
Claude Code 当前真正读取的仍然是：
CLAUDE.md
而不是直接把 AGENTS.md 当成自己的项目记忆文件。
不过 Anthropic 官方文档现在专门给出了一个多工具仓库的处理方式：
在 CLAUDE.md 中导入：
@AGENTS.md
这样 Claude Code 仍然从 CLAUDE.md 进入，但真正的公共项目规范来自同一份 AGENTS.md。
这一下结构就简单多了。
我现在更推荐这种目录结构
假设是一个普通的 TypeScript Web 项目：
my-project/
├── AGENTS.md
├── CLAUDE.md
├── package.json
├── src/
│ ├── api/
│ ├── services/
│ ├── components/
│ └── generated/
├── tests/
└── docs/
核心只有两个入口文件。
AGENTS.md
它是公共规则的单一事实源：
# Project Instructions
## Tech Stack
- Node.js 22
- TypeScript
- pnpm
- Vitest
## Project Structure
- API handlers are under `src/api/`
- Business logic belongs in `src/services/`
- UI components are under `src/components/`
- `src/generated/` contains generated code and must not be edited manually
## Change Rules
- Read the related implementation before editing
- Keep changes limited to the requested task
- Do not add production dependencies unless necessary
- Do not change public API contracts without explicitly explaining the impact
## Validation
After changing TypeScript code, run:
```bash
pnpm lint
pnpm test
For build-related changes, also run:
pnpm build
If a command cannot be executed, explain which validation was not completed.
这里写的不是“你是一个专业程序员”这种空 Prompt。
而是**会直接影响代码修改结果的项目事实**。
例如：
```text
业务逻辑放在哪里？
哪个目录不能改？
用 npm 还是 pnpm？
改完至少跑什么？
什么属于高风险变更？
这些才值得每次 Agent 启动时读取。
CLAUDE.md 不再复制一遍，只负责接入
然后给 Claude Code 留一个非常薄的入口：
@AGENTS.md
## Claude Code Specific
For larger changes, inspect the relevant modules before editing.
Keep task-specific exploration out of AGENTS.md.
这样公共规则发生变化时，只改：
AGENTS.md
而不是：
AGENTS.md
CLAUDE.md
.cursor/rules/project.mdc
三个地方分别检查一遍。
Anthropic 当前文档甚至直接把“已有 AGENTS.md 的仓库，通过 CLAUDE.md 导入”作为官方推荐场景之一。
那 .cursor/rules 是不是可以删掉？
也不是。
我更倾向于把它从“项目总说明书”，降级成Cursor 专用增量规则。
例如你的前端目录有特殊约束：
src/components/**/*.tsx
只有 Cursor 在处理这些文件时，希望自动加载一组 UI 规范。
这时候 .cursor/rules/react.mdc 就很合适。
例如：
---
description: React component rules
globs: src/components/**/*.tsx
alwaysApply: false
---
- Prefer named exports.
- Keep API requests outside presentation components.
- Reuse existing components before creating new ones.
Cursor 官方规则目前支持按照 globs、description、alwaysApply 等条件决定什么时候加载规则。
也就是说：
公共规范放 AGENTS.md，工具特性留给工具自己的规则系统。
这个边界比“所有东西全部塞进一个文件”更重要。
为什么我不建议把 AGENTS.md 写成 1000 行？
统一规则以后，还有一个很容易出现的新问题：
既然三个工具都可能依赖它，那就把所有知识都塞进去。
结果：
项目背景
代码规范
数据库设计
部署步骤
接口文档
Git规范
测试规范
Bug记录
历史架构决策
线上事故
Prompt模板
需求流程
……
最后 AGENTS.md 变成另一份 README 百科全书。
这同样不合理。
OpenAI 当前关于 Codex 自定义的建议也强调：AGENTS.md 应该保持精简，放真正需要持续生效的项目指导，而不是把所有资料全部堆进去。
我判断一条规则要不要进入 AGENTS.md，通常只问一句：
下一次换一个全新的 AI Agent 会话，如果它不知道这件事，很容易把代码改错吗？
如果答案是“会”，可以考虑放进去。
如果只是某一次任务的背景：
不要放。
一个简单判断：规则、文档、Skill 到底怎么分？
我现在会这样分。
每次都必须知道的
放：
AGENTS.md
比如：
构建命令
测试命令
关键目录
禁止修改区域
代码风格
兼容性要求
某个模块才需要知道的
可以放到更靠近代码的规则中，例如：
backend/AGENTS.md
frontend/AGENTS.md
Codex 和 Cursor 目前都支持这种更细粒度的 AGENTS.md 使用方式。
只是某项任务才需要
例如：
发布流程
数据库迁移流程
生成 API 文档
PR Review Checklist
更适合独立文档、Skill 或任务指令。
不要让每一次“帮我改一个按钮颜色”的会话，都先背一遍公司的生产发布流程。
最值得写进规则的，其实是“AI 已经犯过两次的错”
这是我认为最实用的一条。
假设 Agent 已经第二次把：
src/generated/
里的文件直接改掉。
不要第三次继续在聊天里说：
不要改 generated。
直接把它变成项目规则：
## Generated Code
Never manually edit files under `src/generated/`.
If generated output needs to change, locate and modify its source definition instead.
或者某个旧接口不能改：
## Compatibility
`GET /api/v1/orders` is consumed by legacy clients.
Do not rename or remove existing response fields unless backward compatibility is preserved.
这样你做的事情就从：
纠正一次 AI
变成了：
给整个仓库增加一条以后都能复用的工程知识。
OpenAI 最近关于 Codex Code Review 的官方说明里，也在强调类似思路：把团队反复出现的 Review 要求固化为仓库规则，让 Agent 在后续编码和 Review 时直接拿到这些上下文。
我觉得这才是现在 Coding Agent 真正值得投入时间的地方。
不是再研究一个更花哨的 Prompt。
而是让仓库本身越来越“适合被 Agent 理解”。
我最后保留的结构
对于同时使用多个 AI 编程工具的普通项目，我会先从最简单的结构开始：
repo/
├── AGENTS.md # 公共项目规则
├── CLAUDE.md # @AGENTS.md + Claude 专属补充
├── README.md # 给人看的项目入口
├── docs/ # 较长的项目知识
├── src/
└── tests/
Cursor 直接使用 AGENTS.md。
Codex 直接使用 AGENTS.md。
Claude Code 通过：
@AGENTS.md
复用同一份内容。
只有真的出现工具专属需求时，再增加：
.cursor/rules/
.claude/rules/
别一开始就搭一座“AI 配置大厦”。
这套做法真正解决的不是 Prompt，而是配置漂移
Coding Agent 越来越强以后，我反而越来越少关注：
这句话怎么问，模型才能更聪明？
更值得处理的是：
它每次进入项目时，能不能拿到正确的规则？
这些规则有没有过期？
不同工具看到的是不是同一套事实？
AI 犯过的错误，有没有沉淀回项目？
如果一个团队同时在用 Codex、Cursor、Claude Code，却分别维护三份几百行的项目说明，那么以后真正难维护的可能不是代码，而是这些 AI 配置本身。
所以我的建议很简单：
先把公共规则收敛成一个 AGENTS.md，再给不同工具增加最薄的一层适配。
今天就可以从一个动作开始：
打开你现在的：
AGENTS.md
CLAUDE.md
.cursor/rules/
找出重复出现两次以上的规则。
把它们收敛掉。
这比再收藏二十条“万能 AI 编程提示词”，更容易产生长期收益。
你现在项目里是只维护一份 AI 规则，还是 Cursor、Claude Code、Codex 各有一套？如果已经开始出现配置漂移，也可以说说你现在怎么处理。
