> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 01-AGENTS.md项目规则

> 掌握 Codex 发现和合并 AGENTS.md 的范围、层级与覆盖规则，并为仓库、子目录和临时场景编写可验证的项目指令。

## 本页解决什么问题

`AGENTS.md` 不是普通的项目介绍，也不是把 README 复制一遍。它是 Codex 在进入工作区后用来理解**当前任务边界、项目约定、常用命令和验收方式**的持久指令文件。

本页只讲项目规则文件本身：发现位置、全局/仓库/子目录层级、`AGENTS.override.md`、内容结构、命令与验收、规则冲突、示例项目、验证加载和反模式。具体 CLI 参数可能随版本变化，先以本机 `codex --help`、相关子命令帮助和官方文档为准。

先记住四个结论：

1. 全局规则影响多个项目，仓库规则随项目共享，子目录规则只约束该目录及后代目录。
2. Codex 通常从全局层开始，再从项目根目录逐级走到当前目录，将找到的非空文件按从远到近的顺序合并。
3. 越靠近当前工作目录的规则越具体；冲突时通常采用更近的规则，但前面的非冲突规则仍然成立。
4. `AGENTS.override.md` 只替换同级候选，不会抹掉其他目录已经合并的规则。

```text theme={null}
全局层（~/.codex 或 CODEX_HOME）
  -> 项目根目录
  -> 根目录到当前目录之间的每一级
  -> 当前目录
  -> 从上到下合并，越近越具体
```

## 01 什么应该写进 AGENTS.md

### 适合写入

写那些**在这个范围内持续成立，而且 Codex 单靠看代码不一定能可靠推断出来**的内容：

| 类别   | 应回答的问题        | 示例                               |
| ---- | ------------- | -------------------------------- |
| 项目范围 | 这个目录负责什么      | `services/billing` 是账单 API，不处理登录 |
| 技术入口 | 如何启动和检查       | 本地开发使用 `pnpm dev`                |
| 常用命令 | 测试、lint、构建怎样跑 | `pnpm test -- --runInBand`       |
| 结构约定 | 新代码放在哪里       | 路由放在 `src/routes`                |
| 兼容要求 | 什么行为不能改变      | 保持已有 REST 响应字段兼容                 |
| 变更边界 | 哪些内容不能直接动     | 不修改已发布迁移文件                       |
| 验收定义 | 什么结果才算完成      | 测试、类型检查和构建均通过                    |
| 安全边界 | 哪些动作必须停下确认    | 不连接生产数据库                         |

### 不适合写入

以下内容通常应放在任务提示、Issue、PR 模板或普通文档中：

* 只对本次任务成立的文件范围，例如“这次只改一个按钮”；
* 很快变化的版本、临时分支名或个人电脑绝对路径；
* 公司历史、产品愿景和与编码无关的长篇背景；
* 格式化配置或代码已经清楚表达的重复信息；
* 密码、API key、SSH 私钥、Cookie、真实客户数据和内部令牌；
* 一次性发布安排或已经结束的事故上下文；
* “代码必须完美”“体验更好”等无法验收的口号。

判断标准是：**下个月仍然应该适用，且不写会让代理重复犯错，才进入规则文件。** 一次性要求留在提示中，持久规则才写入 `AGENTS.md`。

## 02 发现范围：Codex 会查哪些地方

### 全局层

Codex 会在自己的主目录寻找全局项目说明。默认通常是 `~/.codex`；若设置了 `CODEX_HOME`，以该环境变量指向的目录为准。

全局层适合放跨仓库都成立的个人默认行为，例如：

```md theme={null}
# 个人默认规则

- 开始修改前先读取相关规则、README 和测试配置。
- 修改后检查 diff，不要只根据摘要判断完成。
- 未经明确确认，不要提交、推送、删除数据或访问生产系统。
- 输出命令结果时隐藏令牌、Cookie、邮箱和内部链接。
```

全局层不适合放某个团队仓库的专属命令。若个人偏好与仓库事实冲突，应让仓库规则更具体地说明项目要求。

如果全局目录同时存在 `AGENTS.override.md` 和 `AGENTS.md`，通常优先选非空的 `AGENTS.override.md` 作为这一层候选；不要假设两个文件都会同时生效。

### 项目层

项目层从项目根目录开始，逐级检查到 Codex 当前工作的目录。项目根通常由 Git 工作树根目录确定，实际行为应以当前版本验证。

例如：

```text theme={null}
shop/
├── AGENTS.md
├── src/
│   ├── AGENTS.md
│   └── payments/
│       └── AGENTS.override.md
```

在 `shop/src/payments` 中工作时，可能适用：

```text theme={null}
全局层
shop/AGENTS.md
shop/src/AGENTS.md
shop/src/payments/AGENTS.override.md
```

在 `shop/src` 中工作时，`payments` 下的规则不适用。**当前目录不同，生效规则链也可能不同。**

启动前先确认位置：

```bash theme={null}
pwd
git rev-parse --show-toplevel
git status --short
```

PowerShell：

```powershell theme={null}
Get-Location
git rev-parse --show-toplevel
git status --short
```

如果 Git 命令失败，先判断当前目录是否真是项目工作树，不要把上级个人目录随意当成项目根。

### 每个目录如何选文件

常见候选顺序可以理解为：

```text theme={null}
AGENTS.override.md
AGENTS.md
project_doc_fallback_filenames 中的备选名称
```

每个目录最多取一个非空候选。注意：

* 空文件不能证明有有效规则；
* 同级非空 override 通常会让普通 `AGENTS.md` 被跳过；
* `TEAM_GUIDE.md`、`.agents.md` 等自定义名称不会自动生效，必须配置为备选名称。

列出候选文件：

```bash theme={null}
rg --files -g 'AGENTS.md' -g 'AGENTS.override.md' -g 'TEAM_GUIDE.md' -g '.agents.md'
```

PowerShell：

```powershell theme={null}
Get-ChildItem -Path . -Recurse -File -Include AGENTS.md,AGENTS.override.md,TEAM_GUIDE.md,.agents.md
```

搜索结果只是“可能存在的文件”，还要确认它是否位于全局目录、项目根或当前目录的祖先路径，是否为空，以及同级是否有更优先的 override。

## 03 合并顺序和规则优先级

Codex 通常先收集全局层，再按项目根到当前目录收集项目层，最后按从根到近的顺序拼接：

```text theme={null}
全局规则

仓库根规则

src 规则

当前服务规则
```

越靠近当前目录的内容越具体。例如：

全局层：

```md theme={null}
- 默认使用项目提供的包管理器。
```

仓库根：

```md theme={null}
- JavaScript 依赖统一使用 pnpm，不要改用 npm 安装。
```

子目录：

```md theme={null}
- 本目录是 Python 服务，使用 uv 和 pytest；不要执行前端命令。
```

这不是把全局规则整份删除。全局“修改后检查 diff”仍与子目录“使用 pytest”同时成立；只有针对同一动作的冲突才需要采用更具体的规则。

### 把例外写清楚

不要写：

```md theme={null}
- 所有项目都使用 pnpm。
```

如果仓库包含多个运行时，应写成有范围的规则：

```md theme={null}
- 前端目录使用 pnpm。
- Python 服务目录使用 uv；测试使用 pytest。
- 跨运行时任务分别执行各目录的检查。
```

子目录只写差异和例外，不要把根规则全文复制一遍。重复越多，越容易过时和冲突。

### “优先级”不是权限

更近的规则只能表达更具体的工作约定，不能授予工具没有的权限：

* 写“可访问生产数据库”不会改变沙箱或账号权限；
* 写“无需审批即可删除”不会让删除变得安全；
* 写“把日志上传到某网址”不能绕过数据外发政策。

权限、审批、网络和身份控制由工具配置、操作系统、平台策略和人工批准决定。规则文件应写安全边界，不应假装获得更高权限。

## 04 `AGENTS.override.md` 的准确含义

### 替换同级候选

如果仓库根目录有 `AGENTS.md`，临时调试期间可以增加同目录的 `AGENTS.override.md`。当 override 被当前版本识别且非空时，同目录普通 `AGENTS.md` 通常不再作为这一层候选；原文件仍保留，移除 override 后可恢复。

它适合：

* 临时使用测试替身，避免连接外部服务；
* 迁移期间使用不同验证命令；
* 受控实验分支中的更严格只读限制；
* 子目录由不同团队维护且有独立流程。

### 不会覆盖整条链

假设：

```text theme={null}
~/.codex/AGENTS.md
repo/AGENTS.md
repo/backend/AGENTS.override.md
```

在 `repo/backend` 中，最后一个文件只替换 `repo/backend` 这一层。全局和仓库根规则仍在合并链中。若需要局部例外，应明确写出例外，不要假设 override 会清空上层上下文。

示例：

```md theme={null}
# backend/AGENTS.override.md

## 临时集成测试规则

- 本次只调用测试替身，不要连接生产或共享开发数据库。
- 验证使用 `make test-integration-local`。
- 任务结束后移除此文件，不要写入临时凭据。
```

使用前后问三个问题：

1. 这是稳定的局部规则，还是只对本次实验有效？
2. 谁负责移除或更新它？
3. 团队成员和 CI 是否也会看到它？

一次性要求优先写进提示；必须使用 override 时写明目的和移除条件。长期规则应回填到受审查的 `AGENTS.md`，临时文件完成后删除。

## 05 三个层级分别写什么

### 全局：个人默认

放跨项目的工作习惯、安全原则和报告格式，不放项目专属命令、个人路径或团队政策。

### 仓库根：团队约定

根目录 `AGENTS.md` 随代码提交，是团队共享的主要来源。建议写：

* 仓库运行方式和主要入口；
* 主要服务和目录职责；
* 安装、开发、测试、lint、类型检查和构建命令；
* 兼容性、依赖和生成文件约束；
* 提交或 PR 前的检查；
* 不能执行的生产、破坏性或敏感操作。

根规则不必列出每个文件，详细组件规则下沉到对应目录。

### 子目录：组件差异

子目录规则适合写服务专属命令、语言和包管理器、生成代码或迁移策略、组件级验收和边界：

```md theme={null}
# services/payments/AGENTS.md

## 支付服务

- 运行时为 Python 3.12，依赖使用 uv 管理。
- 单元测试运行 `uv run pytest services/payments/tests`。
- 支付流程必须覆盖重复回调、超时和幂等场景。
- 不要修改已经发布的迁移；新增迁移前先说明回滚方案。
- 本地验证只使用测试网配置，不要读取生产密钥。
```

如果规则只适用于这个服务，就不要放在根目录再依赖代理猜范围。

## 06 内容结构：让规则容易执行

推荐结构：

```md theme={null}
# 项目或组件名称

## 项目范围
- 本目录负责什么
- 明确不负责什么

## 工作区入口
- 关键代码、测试和配置路径
- 生成文件或不可手改文件

## 常用命令
- 安装、开发、测试、lint、类型检查、构建

## 修改约定
- 代码放置、命名、API 和兼容性要求
- 测试位置、依赖、生成代码和迁移要求

## 验收标准
- 必须运行的命令
- 必须检查的行为
- 失败时如何报告

## 禁止和需确认的操作
- 只读目录、敏感系统和破坏性命令
- 外部数据和凭据边界
```

### 标题表达决策

`## 常用命令`、`## 不要修改`、`## 验收标准` 比 `## 其他`、`## 注意事项` 更容易检索。一个标题下尽量只放同一类规则，避免把安全限制埋在背景介绍中。

### 每条规则使用可执行动词

不要写：

```md theme={null}
- 测试要做好。
- 代码质量很重要。
```

改成：

```md theme={null}
- 修改业务逻辑后运行 `pnpm test -- --runInBand`。
- 新增公共函数时补充边界测试；失败时报告失败命令和首个相关错误。
```

规则应包含动作、路径、条件和结果。能写具体命令，就不要只写价值判断。

### 说明条件和替代方案

```md theme={null}
- 不要手工修改 `pnpm-lock.yaml`；依赖变更使用 `pnpm add` 生成。
- 不要修改已发布迁移；需要变更时新建迁移并说明回滚方案。
- 修改 CI 配置前先列出影响的工作流和验证方式。
```

只写“不要改配置”会阻塞合理工作；“禁止什么、正确替代是什么”才可执行。

### 控制长度

多层规则会一起进入上下文，常见默认上限是 `project_doc_max_bytes` 的 32 KiB，具体值以当前配置和版本为准。超出时优先：

1. 删除 README 已说明或代码可推断的信息；
2. 删除重复的上层规则；
3. 把组件内容移到对应子目录；
4. 将设计背景移到普通文档；
5. 确实需要时再调整 `project_doc_max_bytes`。

不要把“调大上限”当成整理规则的替代方案。

## 07 命令与验收怎么写

### 命令来自项目事实

写命令前检查 `package.json`、`pyproject.toml`、`Makefile`、锁文件、CI 和贡献指南：

```md theme={null}
## 常用命令

- 安装依赖：`pnpm install --frozen-lockfile`
- 单元测试：`pnpm test`
- 类型检查：`pnpm typecheck`
- 生产构建：`pnpm build`
```

如果需要工作目录、环境变量或测试服务，也写出来：

```md theme={null}
- 在仓库根目录执行 `make test-api`。
- 集成测试前启动测试容器，不要把请求发到生产地址。
- 缺少 `TEST_DATABASE_URL` 时停止并报告，不要读取 `.env.production`。
```

### 区分验证层级

```md theme={null}
## 验证分层

- 小范围逻辑修改：先运行相关测试，再运行 `pnpm lint`。
- 跨模块修改：运行相关测试、`pnpm typecheck` 和 `pnpm build`。
- 提交前：运行 `pnpm verify`；未运行时必须说明原因。
```

### 规定失败后的行为

```md theme={null}
- 命令失败时不要删除测试、跳过检查或修改 CI 伪造绿色结果。
- 报告失败命令、退出码和首个相关错误，区分环境缺失与代码回归。
- 需要网络、凭据或外部服务时，先说明依赖并等待确认。
```

规则中的命令不是自动授权。特别审查批量删除、数据库重置、迁移、发布、安装未知脚本、读取 `.env`、读取生产日志和网络外发。

### 把完成写成可观察结果

验收要回答：行为是什么、怎样检查、什么结果算通过：

```md theme={null}
## 验收标准

- `POST /api/orders` 缺少商品时返回 400，不创建订单。
- 新增行为由 `pnpm test -- order` 覆盖。
- `pnpm lint` 和 `pnpm typecheck` 通过。
- 不改变成功响应中的既有字段和状态码。
- 无法运行集成测试时，报告缺少的服务和未验证风险。
```

“确保功能正常”和“测试一下”无法形成代理可执行的完成条件。

如果规则要求只改一个组件，验收也要防止范围膨胀：

```md theme={null}
- 本目录修改应保持 `src/payments` 外的文件不变，除非任务明确说明。
- 完成后检查 `git diff --stat` 和 `git diff --name-only`。
- 需要扩大范围时先报告原因，不要默默修改其他服务。
```

最终报告至少列出修改文件、执行命令及结果、未运行检查及原因、仍待确认的假设和回滚信息。

## 08 示例项目：观察规则链

下面的示例不使用真实凭据或外部服务。

### 创建项目和根规则

```bash theme={null}
mkdir agents-md-demo
cd agents-md-demo
git init
mkdir -p services/payments
```

PowerShell：

```powershell theme={null}
New-Item -ItemType Directory agents-md-demo | Out-Null
Set-Location agents-md-demo
git init
New-Item -ItemType Directory services/payments -Force | Out-Null
```

确认根目录：

```bash theme={null}
git rev-parse --show-toplevel
```

在根目录 `AGENTS.md` 写：

```md theme={null}
# agents-md-demo

## 项目范围

这是演示规则发现和局部覆盖的最小项目。

## 常用命令

- 根目录检查：`printf 'root-check\\n'`
- 修改后检查 `git diff --check`。

## 约束

- 不新增依赖，不删除文件，不访问外部服务。
- 完成时报告修改文件和实际检查。
```

命令故意简单，只用于观察规则是否被复述；真实项目应替换成已有且可重复执行的脚本。

### 增加子目录规则

在 `services/payments/AGENTS.md` 写：

```md theme={null}
# services/payments

## 局部规则

- 本目录检查使用 `printf 'payments-check\\n'`。
- 修改前先阅读本目录测试。
- 不要修改 `services/payments` 之外的文件。
- 完成时说明根目录和本目录规则如何满足。
```

从 `services/payments` 启动 Codex，根目录“不新增依赖”等未冲突规则仍然适用。

### 增加同级 override

再创建 `services/payments/AGENTS.override.md`：

```md theme={null}
# services/payments 临时规则

## 临时验证

- 本次只运行 `printf 'override-check\\n'`，不要运行普通 payments 检查。
- 这是演示用临时 override，验证结束后删除。
- 不要修改文件，不要访问外部服务。
```

在该目录中要求 Codex：

```text theme={null}
只读检查当前生效的项目规则。列出规则文件路径，区分根目录规则和当前目录规则；说明当前目录的验证命令。不要修改文件，不要执行命令。
```

预期观察：

* 根目录 `AGENTS.md` 仍属于上层来源；
* override 替换同级 `AGENTS.md`；
* 当前目录命令变为 `printf 'override-check\\n'`；
* “不访问外部服务”等未冲突约束仍有效；
* 只读请求不会产生文件变更。

不同版本或入口的来源展示措辞可能不同。重点是它能否复述可观察规则，以及能否按规则行动。

## 09 验证规则是否被加载

### 只读复述

先不给修改权限，要求：

```text theme={null}
请先不要修改任何文件，也不要运行有副作用的命令。
列出当前工作目录、项目根目录，以及从全局层到当前目录可能影响本任务的规则文件。
按“来源、有效规则、冲突或例外、尚未确认的内容”总结。
不要把猜测当成已加载事实。
```

检查回答是否包含正确目录、预期规则文件、override 关系和不同层级的命令。不要因为它说“已读取”就结束验证。

### 使用无歧义标记

在临时项目规则中加入：

```md theme={null}
## 验证标记

- 只读总结中必须明确写出：`agents-md-demo rules loaded`。
```

让 Codex 只读总结，确认后删除标记，避免把测试句子永久提交。

### 观察低风险行动

```text theme={null}
只检查当前规则要求的快速验证命令。执行前列出命令和预期影响；只允许执行不会写文件、不会联网的命令。执行后报告退出码。不要修改文件。
```

随后检查：

```bash theme={null}
git status --short
git diff --check
git diff --stat
```

证据应包括：Codex 选了规则指定的命令、没有越过禁止范围、工作区没有意外变化。

### 配置变化后重启

若修改 `~/.codex/config.toml`：

```toml theme={null}
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536
```

按当前版本要求重新启动 Codex，再验证备选文件名和内容上限。配置声明不能替代实际加载检查。

### 排查顺序

1. 确认启动目录和 Git 根目录；
2. 确认文件名、路径和内容非空；
3. 搜索全局到当前目录的候选；
4. 检查 `CODEX_HOME`；
5. 检查同级 `AGENTS.override.md`；
6. 检查 `project_doc_fallback_filenames` 并重启；
7. 检查是否接近 `project_doc_max_bytes`；
8. 让 Codex 只读复述来源和冲突；
9. 用低风险命令观察验证路径；
10. 再判断是规则含糊、冲突还是代理未遵守。

不要在原因不明时不断复制同一条规则、加粗或增加感叹号。重复只会增加上下文。

## 10 规则冲突：怎样判断谁赢

### 区分冲突和互补

以下是互补规则：

```md theme={null}
# 根目录
- 修改后检查 git diff。

# 子目录
- 修改支付逻辑后运行 pytest。
```

以下才是冲突：

```md theme={null}
# 根目录
- 测试使用 `pnpm test`。

# 子目录
- 测试使用 `uv run pytest`。
```

针对 Python 服务的子目录规则应明确例外：

```md theme={null}
- 本 Python 服务不使用根目录的 JavaScript 测试命令；本目录测试使用 `uv run pytest`。
```

### 处理表

| 情况               | 处理方式              |
| ---------------- | ----------------- |
| 全局偏好与仓库硬性要求冲突    | 采用仓库要求            |
| 根规则与子目录规则冲突      | 采用针对当前目录的规则       |
| 同级普通文件与 override | 该层通常采用非空 override |
| 两条规则都没有明确范围      | 暂停猜测，报告冲突         |
| 规则与平台安全限制冲突      | 遵守更高层限制           |
| 规则与代码现状冲突        | 先报告是规则过时还是代码需改    |

如果根目录禁止修改迁移历史，子目录却允许直接修改，不要自行执行高风险动作。报告冲突文件、适用范围、更具体的规则、风险和需要确认的人。

## 11 常见反模式

### 把规则写成项目百科

公司历史、完整目录树和大段背景会稀释命令和禁区。保留范围、入口、命令、约束和验收，详细内容放普通文档。

### 把一次性要求写成长期规则

“这次只改 `src/foo.ts`”不应永久限制后续任务。一次性范围留在提示中。

### 规则过时

包管理器或测试命令改变后仍保留旧规则，会持续误导代理。把规则当代码维护，在工具链变更的同一提交中更新它。

### 重复上层内容

子目录复制整份根规则会造成多处漂移。根目录写共同部分，子目录只写差异。

### 只有禁止，没有替代

```md theme={null}
- 不要使用 `npm install`；依赖安装使用 `pnpm install --frozen-lockfile`。
```

“禁止 + 正确替代”比单独说“不许”可执行得多。

### 验收写成口号

“确保功能正常”没有路径、命令和通过条件。写预期状态、边界输入、检查命令和失败报告方式。

### 把秘密放入规则

不要为了方便把真实令牌、内部地址或生产连接串写进仓库。使用环境变量和占位符，缺少凭据时停止并报告。

### 把 override 当永久配置

临时 override 长期留在仓库会让团队误解生效规则。写移除条件，稳定规则回填普通文件。

### 把规则当权限控制

规则不能解除沙箱、审批或组织政策。将高风险操作写成需要确认，真正的权限由工具和平台控制。

### 只验证文件存在

看到 `AGENTS.md` 不等于它已生效。必须结合当前目录、同级 override、配置、内容上限和低风险行动验证。

## 12 可直接改造的模板

```md theme={null}
# <项目或组件名称>

## 项目范围

- 本目录负责：<一句话>
- 本目录不负责：<明确边界>

## 工作区入口

- 主要代码：`<path>`
- 测试：`<path>`
- 配置：`<path>`
- 生成或不可手改文件：`<path>`

## 常用命令

- 安装：`<command>`
- 开发：`<command>`
- 测试：`<command>`
- lint / 格式化：`<command>`
- 类型检查：`<command>`
- 构建：`<command>`

## 修改约定

- <代码和命名规则>
- <兼容性、依赖或迁移要求>
- <测试位置和边界场景>

## 验收标准

- <行为结果>
- <必须执行的检查>
- <必须保持不变的接口或文件>
- 失败时报告命令、错误和未验证风险。

## 禁止和需确认的操作

- 不要：<破坏性或越权操作>
- 未经确认不要：<生产、网络、数据或依赖操作>
- 不要输出：<凭据、用户数据和内部链接>
```

占位命令和路径必须替换为仓库事实，不能为了填满章节而编造。

## 13 修改规则文件的工作流

### 修改前

```bash theme={null}
git status --short
rg --files -g 'AGENTS.md' -g 'AGENTS.override.md'
rg -n 'test|lint|typecheck|build|format' package.json pyproject.toml Makefile .github 2>/dev/null
```

阅读当前目录到项目根之间的规则、全局层、README、贡献指南、CI 和测试脚本。先区分要改的是规则内容、发现配置还是实际代码。

### 修改中

```text theme={null}
请先读取当前目录到项目根目录的规则文件、相关脚本和测试配置。
不要修改文件。列出规则来源、适用范围、冲突和需要更新的命令。
然后给出一份只改 AGENTS.md 的最小编辑计划。
```

每写一条规则都检查：适用目录是什么、是永久规则还是一次性要求、代理能否观察到、失败如何报告、是否与上层或 override 冲突。

### 修改后

```bash theme={null}
git diff --check
git diff --stat
git diff -- AGENTS.md
git status --short
```

子目录规则要使用精确路径：

```bash theme={null}
git diff -- services/payments/AGENTS.md services/payments/AGENTS.override.md
```

运行规则中要求的最小验证，不要为验证规则而运行生产命令或包含真实数据的脚本。

## 14 最终检查清单

### 发现范围

* [ ] 已确认当前工作目录和项目根目录。
* [ ] 已检查 `~/.codex` 或 `CODEX_HOME`。
* [ ] 已从项目根逐级检查到当前目录。
* [ ] 已检查同级 `AGENTS.override.md`。
* [ ] 已确认备选文件名配置、空文件和内容上限。

### 内容质量

* [ ] 项目范围和目录边界清楚。
* [ ] 命令来自真实脚本或 CI。
* [ ] 规则使用可执行动词和条件。
* [ ] 验收包含可观察结果。
* [ ] 没有一次性需求、重复 README 或秘密。

### 冲突与验证

* [ ] 已区分全局、仓库和子目录规则。
* [ ] 已确认 override 的替换范围和移除责任。
* [ ] 已让 Codex 只读总结规则来源。
* [ ] 已观察一次低风险验证路径。
* [ ] 已检查 `git diff --check`、变更文件和工作区状态。
* [ ] 已记录未执行的检查和未验证风险。
* [ ] 未经明确要求，没有提交、推送或发布。

## 小结

`AGENTS.md` 的价值不在于写得长，而在于让 Codex 在正确目录、正确层级中获得正确约束：

```text theme={null}
确认当前位置
  -> 找全局到当前目录的候选
  -> 判断 override 和配置
  -> 理解从根到近的合并规则
  -> 写可执行命令和验收标准
  -> 用只读复述和低风险动作验证
  -> 检查 diff、状态和未验证风险
```

全局层保存个人默认行为，仓库根保存团队约定，子目录保存组件差异，`AGENTS.override.md` 只用于明确的同级替换。持久规则进文件，一次性要求留在提示中；冲突先定位来源，高风险动作先确认；命令必须有真实依据，完成必须有验证证据。

参考资料：`参考/codex/11-agents-md.md`、`参考/codex/13-prompting.md`、`参考/codex/36-best-practices.md`。动态行为以本机 Codex 版本的帮助、配置和官方文档为准。