AGENTS.md 与 CLAUDE.md 项目规则

AGENTS.md 怎么写，先看一条信息对谁长期成立、会不会改变 Coding Agent 的行动。全仓共享的目录地图、权威命令和跨模块边界放在仓库根；只约束后端、前端或 Worker 的规则放在对应目录；跨仓库的个人偏好留在用户全局；本次任务要改什么仍写在当前 Prompt。CLAUDE.md 采用同一内容边界，只是由 Claude Code 按自己的文件与加载机制读取。

如果根规则同时保存前端命令、后端迁移步骤、发布流程和“这次不要改部署”，四种不同生命周期的信息就会一起进入无关任务。先从代码和构建配置确认事实，再把长期规则留在最小适用作用域；流程、任务变量和强制控制交给各自的执行机制。

AGENTS.md 怎么写，先筛出长期项目事实

判断一条内容能否进入项目规则，不看它听起来是否重要，而看它是否同时满足三个条件：对当前作用域长期成立、会改变文件或命令选择、能被仓库事实或团队决定核对。

“前端 API 类型由契约命令生成，不要手工编辑生成目录”符合这三个条件。它告诉 Agent 应修改契约源文件、运行哪个生成入口，并检查哪个消费者。“保持代码高质量”没有说明对象、动作和可观察结果，放进任何层都不会提供有效选择。

项目规则也不负责保存所有有用信息。一次目标随任务结束而失效，应留在 Prompt；只有相关任务才需要的多步骤流程应进入 Skill；保存文件后必定执行的格式化适合 Hook 或现有工具链；Token、Cookie 和私钥只能由 Secret 管理或环境注入。规则可以解释边界，却不能替代权限、沙箱和 CI 的确定性限制。

规则的权威来源仍是实际工程。测试入口已经定义在 package.json、Makefile 或 CI 时，规则只引用入口及适用目录，不另抄一份容易过期的命令实现。公共字段已经由 OpenAPI、Protobuf 或 schema 文件拥有时，规则记录“修改源文件并验证直接消费者”，不复制字段表。

Codex 怎样找到 AGENTS.md

Codex 在一次运行开始时建立指令链。根据 OpenAI 的 AGENTS.md 官方说明（在新标签页打开），它先检查 Codex home；默认位置是 ~/.codex/，同一层存在非空 AGENTS.override.md 时采用它，否则采用 AGENTS.md。这层适合跨仓库稳定的个人工作方式，不适合保存任何项目路径或业务规则。

项目层从项目根开始，一直检查到当前工作目录。每一级目录依次寻找 AGENTS.override.md、AGENTS.md，再寻找 project_doc_fallback_filenames 配置的备用名称；每个目录最多采用一个文件。被选中的内容按根目录到当前目录的顺序合并，所以更近的规则出现在更后面。

假设当前目录是 repo/frontend/，指令链可能是：

~/.codex/AGENTS.md
repo/AGENTS.md
repo/frontend/AGENTS.md

repo/backend/AGENTS.md 不在这条路径上，不会因为它也属于同一仓库而进入当前指令链。若 repo/frontend/AGENTS.override.md 非空，同目录的普通 AGENTS.md 不会同时加载；override 是替换该层入口，不是给它追加几行。

Codex 还受合并大小限制。官方 Configuration Reference（在新标签页打开） 说明 project_doc_max_bytes 控制项目指令的最大读取量，AGENTS.md 指南给出的当前默认值为 32 KiB；达到上限后，Codex 停止加入后续内容。遇到“文件后半段总被忽略”时，先检查实际字节数和目录拆分，不要立即把上限调大。规则只对更小作用域成立时，下沉到对应目录同时解决了噪声和容量问题。

Claude Code 怎样找到 CLAUDE.md

Claude Code 的项目指令入口是 CLAUDE.md，不是裸 AGENTS.md。Anthropic 的 CLAUDE.md 官方文档（在新标签页打开）把作用域分为组织管理、用户、项目与本机：~/.claude/CLAUDE.md 对当前用户的所有项目生效；仓库里的 ./CLAUDE.md 或 ./.claude/CLAUDE.md 随项目共享；./CLAUDE.local.md 保存不应提交的个人项目信息。

Claude Code 启动时会加载当前工作目录及其所有父目录中的 CLAUDE.md 和 CLAUDE.local.md。内容按文件系统根到当前工作目录排列，同一目录的 local 文件位于共享文件之后。它们会被连接进上下文，并不是更近文件在文件系统层面删除更远文件；两层写出相反规则时，官方文档明确提醒模型可能任意选择其中一条。

当前工作目录之下的 CLAUDE.md 则在 Claude 读取相应子目录文件时按需加载。从仓库根启动会话后，frontend/CLAUDE.md 没有立即出现在上下文中不一定是故障；先让 Claude 读取 frontend/ 中的目标文件，再用 /context 核对来源。

大型项目还可以使用 .claude/rules/*.md。没有 paths Front Matter 的规则在启动时加载；带 paths 的规则只在 Claude 处理匹配文件时生效。例如这条规则只约束演示项目的前端源码：

---
paths:
  - "frontend/src/**/*.{ts,tsx,vue}"
---

# 前端规则

- API 类型只从 `contracts/` 生成，不手工修改 `frontend/src/generated/`。

路径规则适合按文件模式表达的 Claude Code 专属差异。若同一事实还要给 Codex 使用，先把共享内容保存在目录 AGENTS.md，再由同目录 CLAUDE.md 导入；.claude/rules/ 只补充 Claude Code 独有的路径行为，不再复制完整正文。

全局规则、根规则和目录规则各写什么

作用域越宽，内容越应该稳定且与具体技术无关。全局规则只代表个人：语言、沟通方式、跨仓库都成立的操作底线。把“在 frontend/ 运行某个命令”写进全局文件，会让每个无关仓库都接收到不存在的路径。

根规则代表项目团队，只写所有主要目录共同需要的事实。它应让 Agent 知道仓库由哪些责任模块组成、构建与测试的权威入口在哪里、哪些文件是生成物、跨模块变更要检查哪些直接消费者，以及哪些外部动作需要额外授权。

目录规则代表最近的工程责任。backend/ 可以说明事务、迁移和服务测试；frontend/ 可以说明路由、请求层和浏览器验证；worker/ 可以说明幂等、重试和任务入口；deployments/ 可以说明环境差异与授权边界。目录规则不重复根规则，也不替相邻模块决定实现方式。

本机内容只描述当前机器，不能伪装成团队事实。个人沙箱 URL、测试账号别名或工具绝对路径可以进入 Claude 的 CLAUDE.local.md 或 Codex 用户配置，但不能包含真实凭据。团队成员必须共同使用的运行版本应由版本文件或构建配置拥有，而不是散落在每个人的 local 规则里。

用全栈仓库建立规则树

以下演示仓库同时包含服务端、管理端、用户端、异步任务、部署配置和公共契约。目录名称只表示责任，不要求实际项目照着改名：

repo/
├── backend/       # API、数据库、领域服务
├── admin/         # 运营管理界面
├── frontend/      # 用户页面
├── worker/        # 异步任务与调度
├── contracts/     # 多端共同消费的契约源
└── deployments/   # 环境与交付配置

假设仓库现有构建文件已经确认：公共契约由 contracts/openapi.yaml 定义，make contracts-check 能验证生成结果；后端测试在 backend/ 运行 go test ./...；用户端在仓库根使用 pnpm --dir frontend test，并从契约生成 frontend/src/generated/。这些命令只属于这个演示仓库，实际项目应以自己的构建文件为准。

这份仓库原来的根规则把所有信息写在一起。拆分后的去向由适用范围和触发方式决定：

“契约变更必须同时检查生产者与直接消费者”对多个目录成立，归根规则所有。“后端修改 API 后运行 go test ./...”只对 backend/ 成立；“不要手工编辑 frontend/src/generated/”只对 frontend/ 成立。根规则不需要导入所有子目录全文，只需指出目录责任和跨模块边界。

当任务从 frontend/ 开始时，Agent 取得全仓契约边界和前端局部命令，不需要携带数据库迁移细节。当任务从 backend/ 开始时，它取得相同的公共边界和后端测试入口。跨契约任务需要读取两端代码，此时根规则负责要求追踪生产者与消费者，各目录规则分别提供实现和验证细节。

根规则保留哪些内容

根文件不需要预设固定章节数。对前述演示仓库，仓库地图、权威命令入口、跨模块边界和结果验证已经能回答去哪里改、运行什么以及从哪里确认结果。

# 项目规则

## 仓库地图

- `backend/` 负责 API 与数据库变更。
- `frontend/` 负责用户端页面。
- `contracts/` 负责 API schema 源文件和客户端生成输入。
- 修改模块前，读取离该模块最近的目录规则。

## 权威命令

- 修改 `contracts/openapi.yaml` 后运行 `make contracts-check`。
- 各技术栈的测试入口以对应目录规则为准。

## 跨模块边界

- 生成物只能通过源文件和生成命令修改。
- 公共契约变化必须追踪生产者与直接消费者。
- Prompt、规则、命令输出和版本控制都不能承载秘密。

## 结果验证

- 同时检查仓库命令和受影响的 API、Worker 或浏览器结果。
- 必需环境不可用时明确说明，不能推断结果通过。

这不是可复制到所有仓库的通用模板。若项目没有生成契约，相关三行应直接删除；若项目只有一个应用，也不需要虚构模块边界。每条规则都应能回答一个具体选择：去哪里改、运行什么、不能直接改什么、结果从哪里观察。

README 仍负责帮助人理解项目、安装软件和参与贡献。根规则可以指向 README 或架构文档中的稳定正本，只摘出会改变 Agent 行动的边界。整份复制会产生两个要同步的项目说明，也会把大量只供人阅读的背景放进每次会话。

目录规则怎样覆盖最近责任模块

目录文件只补充根层没有的局部差异。沿用演示仓库，backend/AGENTS.md 可以写：

# 后端规则

- 后端命令从当前目录运行。
- API 行为变化后运行 `go test ./...`。
- 数据库迁移与消费该结构的代码一起修改。
- API 响应变化时，同时验证契约源文件和直接客户端。

frontend/AGENTS.md 则拥有另一组选择：

# 前端规则

- 从仓库根运行 `pnpm --dir frontend test`。
- 不手工修改 `frontend/src/generated/`，应修改契约源文件。
- 页面行为变化后，在浏览器中检查用户可见状态。

两个目录都不再重复“密钥不得提交”或“公共契约要检查两端”，因为根规则已经覆盖。后端规则也不规定前端使用哪个状态库，前端规则不描述数据库事务。若一个要求只对某个更深的包成立，还可以继续下沉；拆分依据是责任边界，不是文件行数。

目录重命名、命令迁移或生成路径变化时，应和对应规则在同一个工程变更中更新。只有文档维护者才知道的规则已经失去作用：Agent 会继续执行旧命令，而代码审查也很难发现它为什么选错。

AGENTS.md 与 CLAUDE.md 怎样只维护一份事实

选择正本只取决于仓库实际使用的客户端和已有文件，不取决于哪种命名看起来更标准。

同时使用两者时，共享正文只能有一个权威来源。CLAUDE.md 与 Codex fallback 只负责让各自客户端找到这份正文，不再复制其中的项目事实。

仓库已经使用 AGENTS.md 时，Claude Code 官方支持在根 CLAUDE.md 中导入它：

@AGENTS.md

确有 Claude Code 专属行为时，可以继续写在导入行之后，但不能重复 AGENTS.md 已有内容。同样的做法可以应用到有局部共享规则的目录：该目录的 CLAUDE.md 导入同目录 AGENTS.md。导入路径相对于包含它的 CLAUDE.md 解析；需要显示 @ 路径而不导入时，应把路径放进代码格式中。导入只解决内容共享，不会把 Claude Code 与 Codex 的 settings、权限或 Hook 格式互相转换。

若仓库现有正本是 CLAUDE.md，Codex 可以在 ~/.codex/config.toml 中增加备用文件名：

project_doc_fallback_filenames = ["CLAUDE.md"]

这项配置必须在所有使用 Codex 的团队环境中一致存在。Codex 每个目录仍按 AGENTS.override.md、AGENTS.md、备用名称的顺序最多采用一个文件；同目录一旦存在 AGENTS.md，备用的 CLAUDE.md 就不会再加入。无法统一配置时，应把共享事实迁到 AGENTS.md，再由 Claude Code 导入，而不是让一部分成员静默漏读。

官方文档也允许在不需要 Claude 专属内容时让 CLAUDE.md 软链接到 AGENTS.md。软链接会受到 Windows 权限、容器挂载、打包方式和工具解析路径影响；跨平台团队使用导入更容易审查。无论采用哪种方式，都要在两种客户端中分别验证加载，不能用文件内容相同推断运行行为相同。

规则冲突时先修权威来源

优先级只能决定客户端以什么顺序看到文字，不能告诉团队哪一份才应该维护。根规则写“所有测试都从仓库根运行”，后端目录又写“必须从 backend/ 运行”，如果构建文件只支持后者，应修改根规则的错误范围，而不是依赖更近规则长期反驳它。

冲突通常来自四种来源：同一命令被复制到多层后只更新一处；局部规则被放到根层；两个客户端各维护一份近似正文；一次任务或临时状态留在长期文件。修复时先回到 package.json、Makefile、契约、注册关系或架构决定确认事实，只在最小适用的规则层引用它，并删除其他副本。

AGENTS.override.md 和 CLAUDE.local.md 也不适合永久掩盖错误的共享规则。前者会替换 Codex 同目录的普通文件，后者会在 Claude Code 同目录的共享内容之后加载；个人机器上看似正常，其他成员仍会遇到原冲突。共享事实错误就直接改共享文件，本机文件只保留真正的个人差异。

规则变长时同样先修归属，不先压缩句子。Anthropic 在 CLAUDE.md 官方文档（在新标签页打开）中建议每份文件以 200 行以内为目标，Codex 则用 project_doc_max_bytes 限制合并读取量；两者都不是“写满才完整”的配额，也不能为所有 AGENTS.md 规定一个最佳行数。目录特有内容下沉，相关时才需要的流程迁入 Skill，可由程序完成的检查留给 Hook 或 CI，背景解释回到普通工程文档。

2026 年一项针对 100 个公开仓库的 AGENTS.md 与 CLAUDE.md 配置异味研究（在新标签页打开）列出了上下文膨胀、冲突指令、lint 规则泄漏和 Skill 内容泄漏等问题。这个样本不能给出适合每个项目的长度，却能说明规则数量与质量不是同一个指标。删除或下沉内容后，仍要用代表性任务确认 Agent 能找到正确文件、命令和边界。

怎样验证规则真正生效

验证要依次观察加载来源、Agent 选择和软件结果。文件存在只证明它写入了磁盘；Agent 能复述一条规则也只证明文字进入了上下文。

Codex 可以先从仓库根运行官方给出的只读冒烟命令：

codex --ask-for-approval never "Summarize the current instructions."

再把 frontend 换成实际子目录，比较更近一层的来源：

codex --cd frontend --ask-for-approval never "Show which instruction files are active."

相应文件存在时，第二次结果应包含用户层、仓库根和目标目录，不应包含不在路径上的 backend/AGENTS.md。若同目录存在 override，确认普通文件确实没有同时出现；刚修改过配置时启动新命令或新会话，避免把旧指令链误当成当前状态。

Claude Code 在仓库根与目标子目录分别启动新会话，运行 /context，检查 Memory files 中的 CLAUDE.md、导入文件和 local 来源。对于当前目录之下的规则，先读取一个匹配文件再查看上下文；.claude/rules/ 使用 paths 时，还要用一个匹配文件和一个不匹配文件验证正、负两种情况。

加载正确后，用同一个无写入问题比较选择：“当前目录修改代码后，应该运行哪个最小验证入口，依据来自哪里？”根目录回答应指出共同入口或继续读取模块规则；frontend/ 回答应指向前端命令，不能带出后端迁移步骤。回答仍含不存在的路径时，检查重复规则和过期正本，不要继续往 Prompt 里追加纠正句。

最后执行一个范围很小的代表性任务。演示仓库可以让一个前端生成类型随契约变化：Agent 应先改 contracts/openapi.yaml，运行生成与 make contracts-check，再执行前端测试；diff 不应把 frontend/src/generated/ 当作手工编辑的源文件。只有文件选择、命令结果和直接消费者都符合规则，项目规则才真正参与了交付。

如果加载来源正确而结果仍不稳定，规则可能过于抽象、存在冲突，或把强制要求错误地留给模型。把“不要编辑生成物”改成源文件、生成入口和结果路径；把必须阻断的动作交给权限、Hook 或 CI。AGENTS.md 和 CLAUDE.md 提供长期项目上下文，不承担系统无法容错的最后一道防线。

项目规则稳定后，新的任务 Prompt 只需说明这一次要改变的状态、已知事实、范围与结果，不再复制目录地图和全部命令。具体写法继续看《AI Coding 提示词怎么写：只写当前任务，不重复项目规则》。