摘要： Claude Code 与 Codex 可以共用项目级 Agent 指令，但两者的原生入口不同：Claude Code 使用 CLAUDE.md，Codex 使用 AGENTS.md。最实用的方案是把编码规范、测试命令、目录约束和交付清单写入仓库根目录的 AGENTS.md，再由 CLAUDE.md 使用 @AGENTS.md 导入，同时将权限、工具偏好和产品专属功能留在各自文件中。本文提供完整目录设计、可复制模板、Monorepo 作用域、跨平台同步、CI 校验、安全边界与迁移步骤。
核心结论
Claude Code 并不会因为仓库中存在 AGENTS.md 就自动把它当作原生项目记忆；Codex 会自动读取 AGENTS.md。要让两者共用项目规则，推荐采用“AGENTS.md 公共核心 + CLAUDE.md 导入 + 两侧专属附录”的结构。
- 公共规则只维护一次： 架构、测试、格式化、禁止事项和完成标准写入
AGENTS.md。 - Claude Code 通过导入复用： 根目录
CLAUDE.md写入@AGENTS.md，再补充 Claude 专属工作方式。 - 不要把权限当文字建议： Shell、网络、MCP、Secrets 和生产操作仍需由 settings、Sandbox、CI 与审批机制强制执行。
- Monorepo 按目录细化： 根规则保持短小，子目录分别放置更具体的
AGENTS.md与CLAUDE.md，避免把全仓库文档一次塞进上下文。 - 用 CI 防止漂移： 验证导入路径、必需章节、禁止密钥、命令可执行性及子目录规则覆盖关系。
先纠正概念：AGENTS.md 不是 Claude Code 的原生文件名
OpenAI 官方文档说明，Codex 会在开始工作前读取 AGENTS.md，并根据仓库和当前目录加载适用指令。Anthropic 官方文档则把 CLAUDE.md 定义为 Claude Code 的项目记忆文件，并支持在其中使用 @path/to/file 导入其他文件。
因此，“Claude Code AGENTS.md”更准确的含义不是 Claude Code 新增了与 Codex 相同的自动发现机制，而是借助 CLAUDE.md 的导入能力，让 Claude Code 复用 AGENTS.md 中的公共内容。这个区别关系到排错：如果只有 AGENTS.md、没有 CLAUDE.md 导入，不能假设 Claude Code 一定读取了它。
| 对比项 | Claude Code | Codex | 共用策略 |
|---|---|---|---|
| 原生项目指令 | CLAUDE.md | AGENTS.md | 保留两个入口 |
| 公共规则来源 | 可通过 @AGENTS.md 导入 | 自动读取 | 以 AGENTS.md 为公共核心 |
| 目录级规则 | 分层 CLAUDE.md | 分层 AGENTS.md | 子目录成对配置 |
| 用户级偏好 | 用户目录中的 Claude 配置/记忆 | Codex 用户配置与指令 | 不提交个人偏好和凭据 |
| 权限控制 | settings、权限模式、Sandbox、Hooks | Sandbox、审批、配置与执行环境 | 不在 Markdown 中伪造强制权限 |
| 工具扩展 | MCP、Skills、Hooks、Subagents | MCP、Skills、Subagents | 专属配置与公共规范分离 |
本文聚焦文件协作；更完整的 Agent 项目实践可继续参考 AI Stack Nav 的 Codex 项目上下文教程 和 Claude Code 教程。
推荐目录结构：公共核心与工具适配层
中小型仓库可以从三个文件开始：根目录 AGENTS.md、根目录 CLAUDE.md、详细文档目录 docs/agent/。不要把所有架构文档复制进指令文件；入口只说明“什么时候读取哪份文档”。
your-repo/
├── AGENTS.md # 公共规则，Codex 原生读取
├── CLAUDE.md # 导入公共规则 + Claude 专属说明
├── docs/
│ └── agent/
│ ├── architecture.md
│ ├── testing.md
│ └── security.md
├── services/
│ └── api/
│ ├── AGENTS.md # API 子目录规则
│ └── CLAUDE.md # 导入同目录 AGENTS.md
└── scripts/
└── check-agent-instructions.sh公共核心应覆盖：项目目标与边界、仓库地图、安装命令、格式化与测试命令、代码风格、生成文件处理、数据库迁移规则、安全禁区、完成定义和提交/PR 要求。只写 Agent 无法从代码可靠推断的内容。
工具专属层则处理差异。例如 Claude Code 的 Hooks、权限模式和专属 Skills；Codex 的 Sandbox、审批策略、Worktree 或专属 Skill 路由。这些内容若写入公共核心，会让另一工具收到无法执行的命令。
可复制的 AGENTS.md 公共模板
下面模板刻意保持短小。把 YOUR_* 替换为真实项目值，并删除不适用条目。
## 项目目标
这是 YOUR_PROJECT_NAME。优先做最小、可验证、可回滚的修改。
## 仓库地图
- `src/`：业务代码
- `tests/`：自动化测试
- `docs/`：架构和运行文档
- `generated/`：自动生成，禁止手工编辑
## 开发命令
- 安装：`YOUR_INSTALL_COMMAND`
- 格式化：`YOUR_FORMAT_COMMAND`
- 单元测试：`YOUR_TEST_COMMAND`
- 类型检查：`YOUR_TYPECHECK_COMMAND`
## 工作规则
1. 修改前先阅读相关代码、测试和目录级指令。
2. 不修改无关文件，不覆盖用户已有改动。
3. 新行为必须新增或更新测试。
4. 数据库、权限、公开 API 变更先给方案并等待确认。
5. 禁止读取、输出或提交真实密钥与个人数据。
## 完成定义
- 相关测试、格式化和类型检查通过。
- 说明变更文件、验证结果、限制与回滚方式。
- 不声称未实际运行的检查已经通过。指令要使用可验证动词：“运行”“检查”“不得修改”“等待确认”，而不是“尽量写好代码”。不要塞入大段教程、团队历史和已可由 linter 强制的规则。指令越长，模型越难区分真正重要的约束，Token 成本也越高。
CLAUDE.md 如何导入 AGENTS.md
根目录 CLAUDE.md 可以把公共文件作为第一项导入，再补充 Claude Code 专属内容：
@AGENTS.md
## Claude Code 专属说明
- 先使用计划模式处理跨模块变更。
- 遇到权限、部署、数据库写入或外部消息操作时暂停并请求确认。
- 不自动启用未在项目设置中批准的 MCP Server。
- 需要详细架构时读取 `docs/agent/architecture.md`，不要一次加载整个 docs 目录。官方文档说明 CLAUDE.md 支持导入其他文件。实施时仍需在目标 Claude Code 版本中验证相对路径解析，尤其是嵌套目录、符号链接和从不同工作目录启动的情况。不要用导入链形成循环，例如 CLAUDE.md → AGENTS.md → CLAUDE.md。
对于子目录，推荐在 services/api/CLAUDE.md 导入同目录的 AGENTS.md。如果还需要根规则，先确认 Claude Code 已按层级加载根 CLAUDE.md，避免重复导入导致上下文浪费或规则重复。子目录文件只写差异，不要复制根文件全文。
三种共用方案如何选
方案一：CLAUDE.md 导入 AGENTS.md，最推荐
优点是符合两边官方机制，Git 中仍能看到两个清晰入口；Windows、macOS 和 Linux 都不依赖符号链接。缺点是需要维护一行导入和少量专属内容。大多数团队选择它即可。
方案二：符号链接，适合纯同内容项目
可让 CLAUDE.md 指向 AGENTS.md，实现物理单文件。但 Windows 权限、Git 配置、压缩包、某些 IDE 与容器挂载可能改变链接行为；而且两种工具最终往往需要少量专属说明。除非团队环境统一，否则不作为默认方案。
ln -s AGENTS.md CLAUDE.md方案三：从公共源生成两个入口，适合大型企业
把 docs/agent/shared-rules.md 设为源文件，通过脚本生成 AGENTS.md 和 CLAUDE.md，分别拼接适配内容。CI 检查生成结果是否最新。优点是模板化和规模化；缺点是开发者不能随意直接编辑生成文件，流程更复杂。
Monorepo 的作用域与优先级
Monorepo 不应只有一个上万字根文件。根文件定义全局安全、提交和通用命令；frontend/、backend/、infra/ 分别定义框架、测试和部署差异。Agent 修改某个文件时，只应应用从仓库根到目标目录路径上的相关规则。
Codex 官方文档描述了 AGENTS.md 的目录作用域和覆盖关系；Claude Code 官方资料也说明会读取目录层级中的 CLAUDE.md，子目录规则适用于其范围。两者的精确发现顺序与最大加载边界可能随版本变化，团队应通过可观察任务验证，而不是根据记忆猜测。
一个稳健约定是：下层只能细化上层，不能降低安全要求。例如根文件规定“生产部署必须人工批准”，infra/AGENTS.md 不得写“自动部署生产”。出现矛盾时，系统/管理员策略和运行时权限优先，Markdown 文件不能覆盖更高层安全控制。
十步落地与验证流程
- 盘点现有指令。 搜索
CLAUDE.md、AGENTS.md、README、贡献指南和 CI 脚本，删除互相矛盾或已经过期的规则。 - 抽取公共核心。 把两边都需要的仓库地图、命令、编码规范、安全边界和完成定义写入根
AGENTS.md。 - 创建 Claude 入口。 新建
CLAUDE.md，第一行导入@AGENTS.md，其余仅放 Claude 专属内容。 - 拆分详细文档。 将架构、测试、安全和发布长文移动到
docs/agent/，入口文件只提供按需阅读路由。 - 建立子目录规则。 只在确有差异的模块添加成对入口，并确保下层不削弱根级安全约束。
- 用相同任务双测。 分别让 Claude Code 与 Codex复述适用命令、禁止事项和完成定义，不要求模型泄露隐藏推理。
- 执行无害验证。 让两者修改临时示例、运行最小测试，确认目录规则和命令均正确生效。
- 加入 CI 检查。 校验导入目标存在、无循环、必需章节齐全、没有疑似密钥、生成文件没有漂移。
- 实施代码审查。 修改 Agent 指令必须通过 CODEOWNERS 或安全负责人审核，PR 中解释行为变化。
- 版本升级回归。 Claude Code 或 Codex 更新后，重新执行固定指令测试，记录差异并保留回滚版本。
CI 校验：防止导入失效和规则漂移
最小 CI 可以检查根文件存在、CLAUDE.md 包含 @AGENTS.md、公共文件没有密钥样式，并验证文档声明的测试命令。复杂项目还可解析目录树，确保每个子目录的 Claude 入口导入正确公共文件。
set -eu
test -f AGENTS.md
test -f CLAUDE.md
grep -Fq '@AGENTS.md' CLAUDE.md
if grep -En '(sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16})' AGENTS.md CLAUDE.md; then
echo '发现疑似凭据，拒绝提交'
exit 1
fi
grep -Fq '## 完成定义' AGENTS.md脚本本身不能证明模型一定遵守指令。真正验收要包含行为测试：Agent 是否先读目标目录规则；是否拒绝编辑生成文件；是否运行指定测试；生产、权限和外部消息动作是否停在审批门前。记录 Agent 版本、启动目录和测试结果，方便升级后对比。
常见故障与排查方法
第一种问题是 Claude Code 没有表现出 AGENTS.md 中的规则。先确认实际启动目录位于仓库内，CLAUDE.md 的导入行拼写和大小写正确，目标文件已提交且当前用户可读。Linux 文件系统区分大小写，@agents.md 不等于 @AGENTS.md。再用一条无害、可观察的规则测试，例如要求在交付总结中列出实际运行的测试，而不要用危险命令验证。
第二种问题是 Codex 使用了错误目录的规则。检查当前工作目录、目标文件路径以及从仓库根到目标目录之间是否存在多个 AGENTS.md。将每个子目录文件的第一段写清适用模块，减少含糊覆盖。若从 Monorepo 根部同时修改多个服务，应分别读取各路径规则，不能把一个服务的框架命令套到另一个服务。
第三种问题是两边给出不同结果。这不一定表示规则未加载，因为模型、工具、Sandbox 和上下文不同。先比较确定性证据：读取了哪些文件、运行了哪些命令、修改了哪些路径、测试输出是什么。若差异来自模糊表述，就把规则改为明确的条件—动作形式，例如“修改 src/api/** 后必须运行 YOUR_API_TEST_COMMAND”。
第四种问题是导入内容过长或重复。检查根 CLAUDE.md 是否既自动继承了上层规则，又手工重复导入；检查 AGENTS.md 是否复制了完整架构文档。保留一份权威规则，其他内容通过具体链接按需读取。对大仓库，可以为每个模块维护短索引，而不是把整棵文档树放入上下文。
第五种问题是 Windows 符号链接在某些开发机或 CI 中变成普通文件。若团队无法统一 Developer Mode、Git 和容器设置，应迁移到显式导入方案。迁移时先创建真实 CLAUDE.md，写入 @AGENTS.md，在三种主要环境执行验证后，再删除旧链接；保留一个 Git Commit 作为回滚点。
团队治理：谁可以修改 Agent 的工作规则
Agent 指令会改变自动化行为，应像代码与 CI 配置一样治理。根 AGENTS.md、CLAUDE.md 和安全文档可由平台团队或架构负责人作为 CODEOWNERS；模块级文件由模块负责人审核；涉及权限、部署和数据处理的修改增加安全审批。PR 模板要求作者说明新增规则、受影响 Agent、验证任务和回滚方式。
团队还应定义冲突处理顺序：运行环境的系统策略与管理员策略最高，其次是仓库根安全约束，再是子目录业务规则，最后是当前用户的任务要求。用户不能通过一句 Prompt 要求 Agent 忽略安全审批；子目录也不能解除根目录的生产保护。将这一顺序写入公共核心，并在 CI 中对关键语句做最小检查。
对规则变更建立轻量版本记录，例如在 PR 标签中标记 agent-instructions，发布说明中记录行为变化。无需为每次文字修订单独发软件版本，但重要变更应通知使用 Claude Code 与 Codex 的开发者。若新规则导致失败率或 Token 成本明显上升，可以按 Git Commit 回滚，并用固定验收任务定位问题。
从单工具项目迁移到双 Agent 的策略
原先只有 CLAUDE.md 的项目，不要直接重命名文件。先把其中真正跨工具的部分复制到 AGENTS.md，再让 CLAUDE.md 导入公共核心，并保留 Hooks、Claude Skills、权限模式等专属段落。运行 Claude 回归确认行为未丢失后，再让 Codex执行同一批无害任务。
原先只有 AGENTS.md 的项目更简单：新增短 CLAUDE.md 导入它，然后补充 Claude Code 专属边界。若公共文件包含 Codex 专属命令，先移出到单独文档或改写为平台无关规则。迁移期间不要同时大改项目架构和 Agent 指令，否则出现差异时难以定位原因。
回退方案是恢复两个独立入口文件，但仍可把稳定规范放入 docs/agent/shared-rules.md。回退不是失败；如果某个版本对导入、链接或目录发现的行为发生变化，短期独立文件加 CI 一致性检查，往往比继续依赖不确定行为更安全。
安全、权限与 Prompt Injection
仓库指令属于会进入 Agent 上下文的文本，因此拥有写权限的人可能通过 PR 修改它，诱导 Agent 读取 Secret、上传代码或跳过测试。AGENTS.md 和 CLAUDE.md 应由明确 CODEOWNERS 审核，来自 Fork 的变更不能在带生产凭据的 Runner 中直接执行。
不要在文件中保存 API Key、密码、内部主机凭据和个人信息。示例统一使用 YOUR_API_KEY、YOUR_DOMAIN 等占位符。Markdown 中写“禁止联网”不是网络隔离；写“部署前询问”也不是审批系统。Shell、文件、网络、MCP 和云身份要在 Sandbox、settings、代理、CI/CD 与 IAM 中真正限制。
Hooks 或自动脚本要设置超时、有限重试和幂等键，防止 Agent 循环触发。付款、删除数据、发布内容、发邮件、修改账户、修改权限和生产数据库操作必须由独立权限与人工审批控制。审计日志至少记录所加载指令文件的 Commit SHA、工具版本、任务、命令、文件变更、审批和测试结果。
成本、性能与维护策略
每次加载冗长指令都会增加上下文 Token 和注意力负担。根入口控制在能快速扫描的长度，把稳定细节链接到文档；不要每次会话加载全部 ADR、API 文档和历史事故。文档按需读取通常比把所有内容复制进两个入口更省成本。
共用不会消除工具差异。Claude Code 与 Codex 可能采用不同模型、工具、Sandbox、上下文管理和执行策略，同一规则也可能产生不同实现。团队应把格式、类型、测试和安全要求尽量交给确定性工具，Agent 指令主要负责导航与决策边界。
每个规则应有所有者和复查周期。删除已经由 CI 强制的重复文字，更新过期命令，并通过 Git 历史回滚。不要让 Agent 自动修改自身核心约束后立即在同一高权限任务中执行；这类变更应进入新的会话，并经过人工审查。
事实依据与来源
截至 2026 年 9 月 22 日，Anthropic 官方文档明确把 CLAUDE.md 用于指导 Claude Code 行为，并说明可导入其他文件、使用目录层级规则；OpenAI 官方 Codex 文档明确说明 Codex 在工作前读取 AGENTS.md，并使用目录作用域的项目指令。OpenAI 还建议保持 AGENTS.md 简洁，让它提供持久的仓库导航和实践说明。
“以 AGENTS.md 为公共核心、由 CLAUDE.md 导入”的结构是基于两边官方机制形成的实施建议，不是双方宣布的联合标准。符号链接、生成同步、CI 脚本和模板也属于编辑方案，需在团队所用操作系统、IDE、容器和具体版本中实测。本文没有使用未经证实的性能提升或成本百分比。
FAQ
Claude Code 会自动读取 AGENTS.md 吗？
不能把它当作官方保证。Claude Code 的原生项目记忆入口是 CLAUDE.md。若要复用 AGENTS.md，应在 CLAUDE.md 中显式使用 @AGENTS.md 导入并实测。
Codex 会读取 CLAUDE.md 吗？
Codex 的官方项目指令机制是 AGENTS.md，不应假设它自动解释 CLAUDE.md。把公共规则放进 AGENTS.md，Claude 再导入，是更清晰的兼容方向。
能否只创建一个符号链接？
可以，但跨 Windows、容器、压缩包和不同 Git 配置时可能失效，而且难以添加工具专属规则。环境统一的小团队可用，通用教程更推荐导入方案。
AGENTS.md 应该提交到 Git 吗？
项目级规则通常应该提交，以便团队、CI 和 Agent 使用同一版本。个人偏好、账号信息、密钥和机器路径不应提交，应放在用户级配置中。
文件越详细，Agent 效果越好吗？
不是。入口文件应短、明确、可执行。长背景放进按需文档，格式与测试要求交给确定性工具。冗长和矛盾指令会提高 Token 成本并降低遵循度。
子目录规则与根规则冲突怎么办？
设计上应禁止下层削弱根安全规则。业务细节可由更具体目录规则覆盖；系统、管理员、Sandbox、IAM 和审批策略始终高于仓库 Markdown。
如何确认两个 Agent 真的加载了规则？
使用固定的无害验收任务，检查它们能否指出正确命令、禁止目录和完成定义，并观察实际行为与审计日志。不要只问“你读了吗”就认定成功。
AGENTS.md 能代替 Sandbox 和权限配置吗？
不能。它是文本指令，不是安全边界。网络、文件、Shell、MCP、Secrets 和生产权限必须由运行环境强制执行，高风险动作还要人工审批。
参考来源
- Anthropic, How Claude remembers your project
- Anthropic, Claude Code settings
- Anthropic, Claude Code security
- OpenAI, Custom instructions with AGENTS.md
- OpenAI, Codex customization overview
- OpenAI, Codex best practices
- OpenAI, Introducing Codex
工具选型与提示词资料
适合阅读工具评测、工具推荐、对比测评类文章后继续转化。
