AGENTS.md vs CLAUDE.md：一个仓库同时用多个 Agent，规则文件怎么配
## 3. AGENTS.md vs CLAUDE.md：一个仓库同时用多个 Agent，规则文件怎么配 **Slug:** `agents-md-vs-claude-md-multi-agent-repository-rules` 当一个仓库同时交给 Codex、Claude Code、Curso
Jacky Wang
2 分钟阅读
当一个仓库同时交给 Codex、Claude Code、Cursor 和其他 Agent 时，最容易出现的不是代码冲突，而是规则冲突。每个工具都可能读取不同的说明文件，导致同一个任务在不同 Agent 手里有不同的“正确答案”。
最稳妥的做法是把规则分成两层。第一层是工具无关的仓库契约，放在 `AGENTS.md` 或团队统一认可的文件中：构建命令、测试要求、目录边界、禁止操作和发布流程。第二层是工具专属补充，例如 `CLAUDE.md` 中的 Claude Code 工作流、快捷命令或模型特定限制。
不能假设所有工具会自动合并这些文件。社区已经记录过某些情况下存在 `CLAUDE.md` 时，Claude Code 会优先使用它而跳过 `AGENTS.md`。这类行为必须以当前版本文档和本地实验为准。因此，仓库里最好提供一个“规则入口”，明确哪些文件是规范、哪些只是适配层，并在 CI 中检查关键规则是否重复或矛盾。
可直接复制的最小模板如下：
# Repository Agent Contract
Required checks
- Run: `npm run typecheck`
- Run: `npm test`
Boundaries
- Do not edit production secrets.
- Do not change database schema without a migration.
- Ask before destructive or paid actions.
Completion
- Report changed files, tests, and any unverified runtime behavior.
然后在 `CLAUDE.md` 或其他工具文件里只写适配信息，不再复制整份规范。规则文件也应该像代码一样接受 review：有版本、有负责人、有测试。VelaNote 可以用来记录跨工具的设计决策，再通过 MCP 让不同 Agent 读取同一份上下文，减少“规则散落在聊天记录里”的问题。