Claude Code 与 Codex 的配置要先分清两件事：谁应该看到这条信息，以及它要在什么时候、以什么方式生效。跨仓库都成立的个人习惯放在用户层；团队共同遵守的项目事实放在仓库里；只约束前端或后端的规则靠近对应目录；本次要改什么留在 Prompt；可重复的判断流程交给 Skill；必须发生的机械动作由 Hook、权限或项目原有的 CI 执行。
这套分工不要求你先建一个独立配置仓库，也不要求项目改成某种目录模板。它从正在开发的仓库出发，把散落在聊天记录、全局文件和项目规则里的信息迁回唯一的权威来源。Claude Code 和 Codex 可以共享项目事实，但两端的配置格式、发现顺序和可用事件仍由各自客户端负责。
这里的“配置”指会改变 Agent 上下文、工作流或工具边界的指令与设置；API Key、模型选择和代理地址属于运行时接入，不属于这条项目协作链。开始整理前至少要有一个正在使用的代码仓库、一种 Coding Agent，以及读取项目配置的权限。组织托管策略和生产权限不在项目成员的可修改范围内时，只记录它们怎样限制当前任务，不要尝试从本机或仓库配置覆盖。
Claude Code 配置由作用域与执行机制共同决定
只按 CLAUDE.md、AGENTS.md、Skill、Hook 逐个学习，很容易得到多个都能写规则的入口，却不知道冲突时该保留哪一个。作用域与执行机制共同决定信息归属。
作用域回答“谁需要它”：所有项目、一个仓库、仓库中的一个目录、一台机器，还是当前这次任务。执行机制回答“它怎样生效”：每轮作为上下文参与模型判断、相关任务才按需加载、某个事件发生时执行程序，还是连接外部能力。两条轴交叉以后，才轮到选择具体文件。
| 判断轴 | 要确认的事实 | 决定的配置位置 |
|---|---|---|
| 作用域 | 对所有项目、一个仓库、一个目录，还是只对当前任务成立 | 用户层、仓库根、目录或 Prompt |
| 生命周期 | 长期稳定、会跨任务复用，还是一次性输入 | Rules、Skill 或 Prompt |
| 触发方式 | 始终出现、相关时加载，还是在固定事件上执行 | Rules、Skill 或 Hook |
| 执行要求 | 只帮助模型判断，还是必须在模型之外阻止或验证 | 指令、权限、Hook 或 CI |
| 权威来源 | 事实由代码、构建配置、工程文档、运行环境还是个人偏好拥有 | 是否应该写入 Agent 配置，以及应引用哪个正本 |
明确权威来源可以避免同一事实出现多个正本。测试命令已经由 package.json、Makefile 或 CI 拥有时，项目规则只需要指出应使用哪一个入口，不应再复制一份可能过期的脚本正文。API 字段由契约文件拥有时，规则应该说明修改边界和验证责任，而不是把字段表抄进 Markdown。
作用域决定谁能看到一条规则
一条规则覆盖得越广，它越应该稳定、简短，并且与具体项目无关。“回答使用中文”可以是个人偏好；“数据库迁移必须与模型变更一起提交”只属于采用这套迁移机制的项目或后端目录。把后者放进全局文件，会让无关仓库接收到错误约束。
| 作用域 | 适合保存的内容 | 典型错误 |
|---|---|---|
| 组织管理 | 合规策略、受管权限、统一禁止项 | 让普通项目文件覆盖组织安全策略 |
| 用户全局 | 跨仓库稳定的语言、沟通方式、个人操作底线 | 写入某个项目的目录、命令和业务名词 |
| 仓库根 | 团队共享的结构、权威命令、架构边界和交付约定 | 塞入所有子项目的框架细节 |
| 目录 | 该模块独有的命令、命名、测试和维护责任 | 重复父级规则，或规定相邻模块怎样实现 |
| 本机覆盖 | 个人机器路径、尚未共享的临时偏好 | 提交密钥，或让团队依赖一个人的环境 |
| 当前任务 | 这次变化、已知现象、范围、输入和结果 | 重复长期规则，或猜测未经读取的文件路径 |
Claude Code 全局配置和项目配置会组成一条加载链，不是项目文件存在后全局文件就失效。Codex 同样会合并用户与项目指令，但两种客户端查找和合并文件的顺序并不相同。Codex 先在 ~/.codex/ 中读取 AGENTS.override.md，不存在时再读取 AGENTS.md；随后从项目根沿路径走到当前工作目录，每个目录最多采用一个匹配文件，靠近当前目录的内容排在后面。项目目录还可以通过配置增加备用文件名。OpenAI 的 AGENTS.md 官方说明（在新标签页打开）还定义了合并大小上限；指令链达到上限后，Codex 会停止加入后续文件。
Claude Code 则区分组织托管、用户、项目、本机与目录层级的记忆文件。~/.claude/CLAUDE.md 对所有项目生效，仓库中的 ./CLAUDE.md 或 ./.claude/CLAUDE.md 随项目共享，./CLAUDE.local.md 适合不提交的本机内容；子目录中的文件会在 Claude 读取该目录里的文件时按需进入上下文，并非全部在会话启动时加载。具体位置与加载行为应以 Claude Code 的 CLAUDE.md 官方文档（在新标签页打开）为准。
因此，工作目录本身也是配置输入。从仓库根启动与从 frontend/ 启动，看到的目录规则可能不同。排查“同一条 Prompt 为什么在两个终端表现不同”时，先比较启动目录和实际加载来源，不要先改写 Prompt。
执行机制决定一条要求怎样生效
作用域相同也不代表应该使用相同机制。项目可能要求“修改公共契约后同时验证生产者与消费者”：这条长期边界属于项目规则；某次修改的是哪个字段属于 Prompt；反复执行的契约升级流程可以成为 Skill；保存契约后运行一个快速语法校验可以交给 Hook；能否访问测试环境则由权限和凭据系统决定。
| 机制 | 何时进入任务 | 适合拥有的责任 | 不能替代什么 |
|---|---|---|---|
| Rules / Instructions | 会话启动、路径发现或读取相关目录时 | 稳定事实、架构边界、项目命令入口 | 强制安全策略、单次目标 |
| 当前 Prompt | 每次任务开始或追问时 | 当前变化、已知事实、允许范围、可观察结果 | 项目长期知识库 |
| Skill | 被明确调用或任务内容与描述匹配时 | 可复用、需要判断的多步流程及配套脚本 | 每轮都适用的短规则、纯事件动作 |
| Hook | 匹配生命周期事件时 | 格式化、阻断、采集状态或运行确定性检查 | 需要理解业务规则的完整工作流 |
| 权限与沙箱 | 工具或外部动作发生前后 | 允许、询问或禁止某类能力 | 项目目标和完成标准 |
| MCP | 连接或调用外部服务时 | 暴露工具、数据与资源 | 使用这些能力的业务授权与项目规则 |
| Memory | 会话恢复或本地回忆被取用时 | 可丢失的历史线索、个人观察和阶段状态 | 团队权威事实、架构决定和安全边界 |
| Subagent | 主 Agent 委派独立任务时 | 隔离上下文、工具和局部探索 | 没有明确边界的大任务拆分 |
Anthropic 的功能总览（在新标签页打开）把 CLAUDE.md、Skills、Hooks、Subagents 和 MCP 分成不同功能：持久上下文、按需知识、事件自动化、隔离任务与外部连接分别解决不同问题。OpenAI 的 Skill 文档（在新标签页打开）也采用渐进加载，启动时只暴露名称与描述，选中后才读取完整 SKILL.md 及其参考、脚本或资源。复杂流程放进 Skill 后只在相关任务中读取，无关对话不必加载完整流程。
Rules、Prompt 和 Skill 都由模型解释。它们会影响模型的选择，却不能把自然语言变成不可绕过的系统边界。“禁止访问生产环境”若只写在项目规则里，仍然弱于不提供生产凭据、限制网络、收紧权限，或在确定事件上拒绝命令。Claude Code 的配置诊断文档（在新标签页打开）也明确区分了项目指导与 permissions、hooks 的强制责任。
Hook 同样不是完整安全沙箱。它只能处理客户端实际提供的事件、匹配器和输入；配置未加载、事件未覆盖或脚本自身有缺陷时，保护就不存在。更强的边界应下沉到最靠近资源的一层，例如操作系统权限、云端 IAM、分支保护和 CI。两端的 Hook 事件、payload 与退出码含义必须分别接入和验证，不能复制一份配置后假定行为相同。
全栈仓库怎样拆项目规则
一个已有项目可能同时包含 API、管理端、用户端、异步任务、部署配置和公共契约。目录名称不重要，每条局部规则只需靠近负责它的模块。以下名称只标记常见责任，不要求仓库照着改名：
repo/
├── backend/ # API、数据库和服务端测试
├── admin/ # 运营界面与管理端权限
├── frontend/ # 用户页面与浏览器验证
├── worker/ # 异步任务、重试和调度
├── deployments/ # 环境与交付配置
└── contracts/ # 前后端共同消费的契约
仓库根规则只保留所有这些目录共同需要的事实，例如权威构建入口、模块责任边界、公共契约在哪里、哪些变更必须验证直接消费者。它不需要展开某个前端组件怎样命名，也不需要复制后端迁移命令的全部参数。
目录规则补足局部信息。backend/ 可以说明迁移与服务测试的项目入口；frontend/ 可以说明路由、组件边界和浏览器验证；worker/ 可以说明任务幂等与重试约束；deployments/ 可以明确哪些环境动作需要额外授权。若 contracts/ 的产物同时被后端和前端消费，“修改契约必须检查生产者与消费者”属于根层共享边界，而生成命令和文件格式属于 contracts/ 的局部规则。
当仓库已经观察到 API 返回与用户页面使用不同的状态名称时，Prompt 不必再次解释整个仓库，也不应凭猜测指定一组文件。当前任务只需写明已经确认的现象、排除范围和结果：
请修复订单状态在 API 响应与用户页面之间的名称不一致。
先读取当前目录适用的项目规则，再沿公共契约找到实际生产者和直接消费者。
只修改这组状态名称及必要适配，不改变管理端流程和部署配置。完成后运行仓库已有的契约检查，并在本地页面确认 API 返回值与可见状态一致。若现有代码同时表达两种互相冲突的状态含义，停止修改并列出需要业务负责人决定的冲突证据。
这段请求只有在“API 与页面状态名称不一致”已经可以复核时才成立。项目规则指向适用边界，构建文件提供项目命令，源码与注册关系证明实际责任边界。路径未知就让 Agent 搜索，命令未知就让它读取构建文件，业务规则没有确认则不能靠更长的 Prompt 猜出来。
当契约升级在多个任务里反复出现，并且始终包含兼容性判断、生成、生产者测试、消费者测试和变更说明，它才适合提炼成 Skill。保存文件后运行一次便宜且无歧义的语法检查，可以进入 Hook。二者都不该反过来吞掉根规则或当前任务：Skill 不拥有项目事实的权威来源，Hook 也不知道这次为什么改状态。
哪些配置进入仓库，哪些只留本机
是否提交不取决于“配置能不能工作”，而取决于它是不是团队共同需要的可审查事实。仓库中的规则、项目级 Skill 和 Hook 会影响其他贡献者与自动化，应该像代码一样评审；个人模型选择、机器绝对路径和临时实验不应让整个团队被迫采用。
| 信息 | 合适位置 | 原因 |
|---|---|---|
| 仓库结构、权威命令、架构边界 | 版本控制中的根规则或工程文档 | 所有贡献者需要同一事实 |
| 前端、后端、Worker 的局部约定 | 对应目录的规则 | 只在该模块内生效 |
| 团队重复使用的发布或迁移流程 | 项目级 Skill 及其脚本、参考 | 需要共同审查和版本化 |
| 团队一致执行、便宜且无歧义的动作 | 项目级 Hook 或现有工具链 | 行为要随仓库一起演进 |
| 语言偏好、个人交互方式 | 用户全局配置 | 跨仓库稳定但不代表团队意见 |
| 本机路径、临时模型与个人实验 | 本地覆盖或用户设置 | 机器相关，不应污染共享配置 |
| Token、私钥、生产凭据 | Secret 管理、环境注入或受管身份 | 规则文件和 Prompt 都不是秘密存储 |
| 组织禁止项与托管权限 | 组织管理层 | 项目成员不应自行放宽 |
本机差异也不要伪装成项目事实。例如“浏览器在 /Applications/...”只对某台机器成立；共享规则应描述需要浏览器验证的结果，具体可执行路径交给本机配置或工具发现。相反，如果整个团队都必须使用仓库锁定的 Hugo、Node 或 Go 版本，版本文件与构建脚本才是正本，Agent 规则只引用它们。
Claude Code 与 Codex 共享项目事实，各自保留配置格式
为 Claude Code 和 Codex 复制两份完整规则会产生漂移，强行把两端所有配置做成同一种结构又会抹平能力差异。项目事实只保存一份，客户端入口各自适配。
| 两端共同使用的内容 | 需要分别适配的部分 | 通常只留本机的部分 |
|---|---|---|
| 仓库结构与模块责任 | 指令文件的发现与优先级 | 个人回答语言与交互偏好 |
| 构建、测试和预览的权威入口 | Skill 的安装位置与触发元数据 | 默认模型与推理参数 |
| 公共契约、权限和数据边界 | Hook 事件、payload、退出码含义 | 本机工具路径与临时授权 |
| 完成标准与直接消费者 | MCP 配置格式和项目审批 | 个人 Memory 与历史线索 |
如果仓库已经以 AGENTS.md 保存跨工具规则，Claude Code 的项目入口可以使用官方支持的导入语法引用它，再在同一文件中追加只属于 Claude Code 的短说明：
@AGENTS.md
Claude Code 专属说明可以继续写在导入行之后，但不应重复 AGENTS.md 已有内容。团队成员克隆仓库后，Codex 能直接发现 AGENTS.md，Claude Code 则通过导入读取同一内容，无需为 Codex 增加额外发现设置。
如果仓库现有的唯一项目规则就是 CLAUDE.md，又暂时不准备增加 AGENTS.md，可以在 Codex 的 ~/.codex/config.toml 中登记备用文件名：
project_doc_fallback_filenames = ["CLAUDE.md"]
新会话中，Codex 会在每个目录依次检查 AGENTS.override.md、AGENTS.md，最后才检查备用名称。同一目录仍然最多读取一个项目指令文件，所以只要 AGENTS.md 已经存在，该目录中的 CLAUDE.md 就不会再作为备用文件合并。如果无法保证每位成员的 Codex 环境都配置了这个字段，应改用 AGENTS.md 作为共享正本，再让 Claude Code 导入。
备用名只改变发现入口，不会自动把 Claude Code 的 Hook、settings 或 Skill 元数据转换成 Codex 格式。选择哪一份文件作为正本，应服从仓库当前已有的权威来源；没有必要为了“统一”再造第三份相同文档。
客户端专属的短入口可以直接随项目版本化。只有当多个仓库、多个客户端和多台机器之间的人工同步已经产生漂移时，才需要考虑独立配置仓库、软链接或生成器。它们解决的是配置资产分发，不是全局配置与项目配置协作的前置条件。
客户端改变指令发现顺序、Skill 元数据、Hook 事件或权限配置结构时，只更新对应的短入口；仓库目录、权威命令或模块责任改变时，先修改项目事实的权威来源，再更新引用它的根规则与目录规则。两类变化不能混在一次“同步配置”里，否则客户端升级会意外改写项目事实。
Claude Code 配置不生效时，先查实际加载来源
迁移前先确认当前客户端、工作目录和实际加载的文件。否则你可能修改了一份从未加载的配置，或者漏掉更高优先级的 override。
Claude Code 中，/context 会按类别显示当前上下文来源，可先确认 CLAUDE.md、Rules 与 Skill 描述是否出现；/memory、/skills、/hooks、/mcp 和 /permissions 分别显示对应来源与状态。子目录 CLAUDE.md 没在启动时出现不一定是故障：官方说明它会在 Claude 读取该目录文件时按需加载。/doctor 可继续检查安装状态与无效配置。
Codex 官方文档给出了两条直接的冒烟命令。先在仓库根运行：
codex --ask-for-approval never "Summarize the current instructions."
再从实际子目录比较加载来源：
codex --cd frontend --ask-for-approval never "Show which instruction files are active."
第二条命令中的 frontend 对应前述示意结构。实际仓库没有这个目录时，应替换成当前工作目录。若根目录与子目录显示完全相同，而子目录明明存在非空的规则文件，继续检查项目根识别、文件名、override 优先级和合并大小，不要用重复 Prompt 掩盖发现失败。
搜索规则内容还能发现重复正本。选一条有辨识度的句子，例如“公共契约变更必须验证直接消费者”，同时检查用户全局、仓库根、目录规则、Skill 与 Hook。它若在多处表达不同范围，先确定谁拥有事实，再删除其他副本。不要用“以更近文件为准”长期容忍互相矛盾的定义；优先级只解决加载冲突，不解决团队不知道哪份才应修改的问题。
把零散配置迁回权威来源
每移动一层配置就检查一次加载和行为；一次性重写所有文件后，很难判断是哪项变化改变了 Agent 的行为。
- 画出现有加载链。 记录实际用户层、仓库根、当前目录、本地覆盖、Skill、Hook、权限与 MCP 来源，不从理想目录结构反推。
- 为重复信息确定权威来源。 命令回到构建文件，字段回到契约，架构决定回到工程文档；Agent 规则只保存使用这些事实时必须知道的边界。
- 移动静态规则。 跨仓库的个人习惯上移到用户层，共享项目事实保留在根层，局部命令和约束下沉到最近目录，一次目标从规则中移回 Prompt。
- 拆分执行机制。 相关时才需要的多步判断进入 Skill，固定事件上的机械动作进入 Hook 或现有工具链，秘密与授权进入权限系统。
- 适配双客户端。 先确认共享正文正确，再分别补足 Claude Code 与 Codex 的发现、元数据和事件差异；每移动一层就重新验证。
把前述目录代入这组顺序：根规则如果同时包含前端格式化命令、后端迁移步骤、发布流程全文和“本次不要改部署”，迁移后只保留跨模块边界。前后端命令回到各自目录并引用项目脚本，发布流程进入按需 Skill，“不要改部署”作为当前任务范围，能阻止部署的权限仍由环境控制。迁移后的任务只加载当前作用域需要的常驻规则，其他流程在相关时再进入上下文。
| 原来散落的信息 | 迁移后的唯一权威来源 | 其他层怎样使用 |
|---|---|---|
| 跨仓库都使用中文回答 | 用户全局指令 | 项目文件不再重复 |
| 公共契约变更必须检查生产者与消费者 | 仓库根规则 | Prompt 写本次契约变化，目录规则提供各自验证入口 |
| 用户端修改后要运行浏览器检查 | 用户端目录规则 | Skill 可编排完整流程，Hook 只执行无歧义的快速检查 |
| 本次不得修改部署配置 | 当前 Prompt | 任务结束即失效，不沉淀为长期项目限制 |
| 契约升级的生成、测试与变更说明 | 项目级 Skill | 根规则只说明何时需要使用这套流程 |
| 保存 JSON 后执行语法校验 | Hook 或项目现有工具链 | 校验失败时返回非零退出码 |
| 生产 Token 与部署权限 | Secret 管理和权限系统 | Prompt 只说明授权边界，不承载凭据 |
增加配置长度不等于提高可靠性。Configuration Smells in AGENTS.md Files（在新标签页打开） 对 100 个公开仓库的研究报告了 lint 规则泄漏、上下文膨胀、Skill 内容泄漏和冲突指令等常见问题；Do Context Files Help Coding Agents?（在新标签页打开） 在其受控任务设置中没有观察到上下文文件带来可测的正确率提升。后者不能推出“项目规则无用”，但足以说明不能用规则行数、文件数量或单次成功证明效果。规则是否有效，要看代表性任务有没有少选错文件和命令，以及软件结果是否正确。
怎样验证 Claude Code 配置与 Codex 配置生效
“文件保存了”和“Agent 说它看到了”都不是完整证据。一次配置变更需要分别验证加载来源、行为选择和软件结果。
| 证据层 | 要回答的问题 | 可观察状态 |
|---|---|---|
| 加载来源 | 客户端实际读取了哪些文件、Skill、Hook 和权限 | 官方诊断中出现正确路径、作用域和优先级 |
| 行为选择 | 根目录与子目录的相近任务是否采用不同局部约束 | Agent 指向正确命令和责任模块，没有引用被移除的副本 |
| 软件结果 | 选择的命令和流程是否覆盖生产者与消费者 | 构建、测试、契约或页面结果与当前代码一致 |
用客户端诊断入口确认加载来源后，在仓库根和目标子目录分别提出一个不会修改文件的问题，例如“当前目录修改代码后应运行哪个最小验证入口，依据来自哪里”。答案应该引用不同层的项目命令；若只复述一段宽泛原则，说明目录规则还没有提供足够具体的信息，或客户端没有加载它。
随后执行一项代表性任务。公共契约变更不能止于 Agent 说“已同时更新前后端”：运行仓库已有的契约检查，读取 API 生产者，并让实际前端消费者解析或展示结果。Hook 要核对事件、matcher、退出码、标准输出和副作用；Skill 要同时测试相关请求会触发、无关请求不会触发、缺少输入时会停止。MCP 则要检查连接状态、工具 schema、权限拒绝和失败返回，而不只是“服务器已配置”。
如果文件已经加载但行为仍不稳定，先检查同一事实是否有冲突版本、规则是否使用“注意质量”“遵循最佳实践”这类无法执行的抽象句，以及常驻上下文是否塞入了本应按需加载的流程。若 Hook 已列出却没有执行，再查事件是否覆盖当前动作、matcher 是否命中、脚本是否接收到预期 payload；不要把同一命令重复写进 Prompt 当作修复。
配置加载正确后，仍要运行测试、打开页面或调用 API。Rules、Skill 和 Hook 只能影响 Agent 选择什么，不能让未检查的消费者自动正确。没有观察直接消费者，最多只能确认配置被读取，不能确认代码改对了。
从一条长期项目事实开始
现在从自己的仓库选一条经常重复说明的长期事实，先找到它在代码或工程文档中的权威来源，再判断它对整个仓库还是某个目录成立。把它放进根规则或最近的目录规则后，分别从仓库根与目标目录检查加载来源，并运行这条规则指向的项目命令。如果 Claude Code 与 Codex 都读取同一事实，并在目标目录选择正确命令，再迁移下一条。
根规则与目录规则需要怎样写、AGENTS.md 和 CLAUDE.md 怎样共享事实而不互相覆盖，继续看《AGENTS.md 与 CLAUDE.md 怎么写：根规则、目录规则与跨工具复用》。长期规则稳定后，当前任务只补 Prompt；重复流程再进入 Skill，确定性动作再进入 Hook。