AGENTS.md 中文指南：把稳定规则放到正确层级

同一句规则复制十次，还是有人会漏掉

你在每个任务开头都写「保留现有 UI」。新同事也照抄。可一进入子目录，某个任务仍然把视觉系统重做了一遍。

问题不在提醒次数，而在规则没有稳定的地址。

AGENTS.md 的作用，是让规则跟着目录被发现，而不是让提示词继续变长。 这节课会跟着一个前后端仓库，判断哪些规则放根目录，哪些只在子目录生效，冲突时怎样追到来源。

AGENTS.md 不是项目百科

官方文档把 AGENTS.md 定义为 Codex 每次运行都会发现的持久指导。它适合放会反复影响协作方式的规则：仓库结构、测试命令、代码约定、验证要求和目录特有边界。一次任务的目标、临时文件和今天的决定仍放在 prompt 或任务记录中。

判断一句话是否应该进入 AGENTS.md：

• 是否会在多个未来任务中重复出现？
• 是否能直接改变 Codex 的检查、修改或验证动作？
• 是否比代码、package scripts 或自动化检查更适合用文字表达？
• 规则过期时，维护者能否知道去哪里改？

“保持高代码质量”不合格；“修改 app/ 后运行 npm test，并在交接中列出未运行项”可执行。

指令链与就近覆盖

Codex 会从全局范围开始，再沿项目路径寻找项目指令；越接近当前工作目录的规则通常越具体并优先。AGENTS.override.md 可用于覆盖。这个模型让：

• 全局层保存个人稳定偏好；
• 仓库根保存全项目规则；
• 子目录保存特定技术或数据边界；
• override 处理明确的临时或强覆盖需求。

不要深层嵌套许多近似规则。规则来源过多会让冲突难以诊断，也可能超过加载限制。内容应就近、短小、去重。

一份合格文件的结构

# Repository instructions

## Scope
- 这些规则适用于整个仓库；子目录 AGENTS.md 可提供更具体规则。

## Before editing
- 阅读 README、package.json 和当前 Git 状态。
- 保留用户已有改动，不覆盖无关文件。

## Implementation
- 复用现有组件与命名。
- 未经请求不新增依赖，不改变公开接口。

## Validation
- 运行 npm test 与 npm run typecheck。
- 布局变化验证 1280×720 与 390×844。
- 无法运行的检查必须列为未验证。

## Delivery
- 汇报修改文件、验证、风险与未执行动作。
- 未经明确请求不 push 或 deploy。

项目实际命令必须来自真实脚本，不要复制通用模板。

把规则放在代码还是指令里

优先级建议：

1. 能由类型、测试、lint 或 CI 自动执行的，写成机器约束；
2. 需要解释工程意图和工作流程的，写 AGENTS.md；
3. 只影响本次结果的，写 prompt；
4. 需要脚本、模板和多步操作的重复流程，沉淀 Skill。

AGENTS.md 不是用来替代测试，也不应包含会自动执行的秘密或凭据。

验证生效，而不是假设生效

在目标目录启动新会话，让 Codex只读汇报：

请列出对当前目录生效的指令文件，说明读取顺序、每个文件的范围和发生覆盖的规则。
不要修改文件。

然后给一个故意触碰规则的任务，例如要求新增依赖或跳过移动端验证，观察它是否指出冲突并停下。验证后删除测试性要求，不要让反例污染项目。

常见失败

文件写得像愿景

“专业、简洁、用户友好”不能直接执行。改为具体文件、命令、视口、数据或审批规则。

全局规则过于具体

把某仓库 npm 命令写入全局文件，会污染其他技术栈。移到仓库根。

子目录互相矛盾

明确更具体规则覆盖什么，不要让同一术语在多个层级表达不同意思却没有说明。

修改后不重启或不重新加载

官方说明和具体客户端行为会更新；编辑指令后新建或重启会话，再让 Codex报告实际生效链。

完整案例：同一仓库里的三层规则

一个 monorepo 同时包含前端、Worker 和移动端。所有目录都需要保护用户改动，但验证方式不同：

repo/
├── AGENTS.md
├── apps/web/AGENTS.md
├── apps/mobile/AGENTS.md
└── services/worker/

仓库根 AGENTS.md 适合写：

• 不覆盖已有未提交改动；
• 使用项目包管理器；
• 提交前运行 diff check；
• 外部发送、迁移和部署需要明确授权。

apps/web/AGENTS.md 再写：

• 使用 Kumo 组件；
• 桌面和 390px 移动端都要验证；
• 浏览器截图保存在 ref/；
• 前端验收命令和路由。

不要把“这次只改订单页标题”写入 AGENTS.md。它只属于当前 prompt。

规则冲突怎样判断

更靠近工作目录的 AGENTS.md 对其子树提供更具体指导，但它不应被写成绕过根安全约束的后门。例如根文件要求“禁止未经授权部署”，子目录不能写“前端改动完成后自动部署”。

遇到冲突时：

1. 报告发现的文件路径；
2. 引用冲突的具体规则；
3. 区分“更具体”与“直接矛盾”；
4. 对安全或外部状态冲突暂停询问；
5. 不在当前任务里静默改规则来让自己继续。

从一次错误反推规则

只有可重复的摩擦才值得沉淀。复盘模板：

重复错误：两次视觉修改都只验证桌面
根因：README 只写 npm test，没有浏览器验收要求
新规则：涉及布局时使用 Ego Lite 验证 1280×720 和 390×844，
截图存入 ref/，结果写入 design-qa.md
验证：在下一次布局任务中确认规则被发现并执行

“Codex 要认真一点”不是规则；可触发、可执行、可验证的行为才是。

给规则加适用条件和证据

当修改影响页面布局时：
- 使用 Ego Lite 验证 1280×720 与 390×844；
- 检查横向溢出、主要操作和侧栏行为；
- 截图保存到 ref/；
- 把实际视口、动作和结果记录到 design-qa.md。

这比“所有改动都截图”更准确：它说明何时触发、检查什么、产物放哪里，也不会给纯后端改动制造无意义步骤。

AGENTS.md 不应变成百科全书

当文件越来越长时，把稳定但低频的工作流移到引用文档或 Skill：

• AGENTS.md：何时必须做浏览器验收；
• docs/browser-qa.md：项目具体验收矩阵；
• Skill：跨仓库可复用的浏览器操作流程。

入口文件保留导航、强约束和最常用命令，避免真正重要的规则被埋在背景说明中。

故障诊所

规则存在但没有生效

检查当前工作目录、文件命名、路径层级和是否真的读取。要求 Codex 在任务开始时报告生效指导，而不是猜。

每次都要重新解释同一验证步骤

说明它已经是仓库级惯例。把实际命令、适用条件和输出位置写入最接近的 AGENTS.md。

AGENTS.md 经常过期

规则复制了版本号、临时路径或 UI 文案。保留稳定目的，把高漂移细节链接到单独文档，并定期校准。

知识检查

“所有 React 组件不得超过 100 行”应该直接写进根 AGENTS.md 吗？只有团队确实采用并能解释例外时才写。否则它会制造机械拆分，不能代表真正的可维护性标准。

判断是否值得沉淀的简单标准是：下一位不了解本次对话的人，能否仅凭这条规则做出同样的安全选择，并用明确证据证明自己遵守了它。

规则还要能被删除：当工具、目录或团队流程改变后，过期指导应更新或移除，不能因为“曾经有用”就永久增加上下文负担。

从你重复最多的那句话开始

翻看最近几次任务，找出被重复三次以上、而且长期稳定的要求。为它选择最小生效范围，再用一个子目录任务验证是否真的被发现。

不要把会议记录、临时决定和项目百科一起塞进 AGENTS.md。规则越可执行、范围越准确，未来的 prompt 才越短。

完成检查

• 每条规则会改变真实动作
• 长期规则、单次任务和可执行自动化没有混写
• 全局、仓库、子目录规则各自就位
• 实际命令来自当前仓库
• 已验证生效指令链与覆盖关系
• 规则不能替代测试、安全或人工授权