AGENTS.md／.cursor/rules 是给编码代理的“站立规则”。常见翻车：文件过长被截断、把 lint 规则塞进提示、／init 生成后不改、根目录与子目录／多工具规则互相打架。短、可执行、只写代码里猜不到的内容。
要点
- Codex：启动时读取全局与项目链上的
AGENTS.md／AGENTS.override.md；自根向当前目录拼接，更靠近工作目录的文件后出现、覆盖更早指导；默认合计约 32 KiB（project_doc_max_bytes），超限会截断（Custom instructions with AGENTS.md，核验日 2026-10-28）。 - Cursor：可用根／嵌套
AGENTS.md，或.cursor/rules/*.mdc（需 frontmatter；纯.md放 rules 目录会被忽略）。官方建议规则聚焦、可执行，避免整本风格指南与罕见边角；嵌套时更具体者优先（Rules）。 - 该写什么：装依赖／测试／lint 的真实可复制命令、非显而易见的目录约定、危险边界、重复踩过的坑。不该写：整仓目录树、已有 linter 强制的格式、只偶尔用的长流程（可放到 skill／单独文档再按需引用）。
- 公开研究旁证：对 100 个含 AGENTS.md／CLAUDE.md 的热门仓，配置“味道”很常见：Lint Leakage 约 62%、Context Bloat 约 42%、Skill Leakage 约 35% 等（Configuration Smells in AGENTS.md Files；学术样本，非官方产品承诺）。
- 落地习惯：同一条规则只维护一处；改 CI／包管理器时同步改 Commands；用
Summarize the current instructions／让 Agent 复述已加载规则做抽检。 - 证据强度：发现顺序与字节上限来自 OpenAI Learn；Cursor 规则类型与“避免事项”来自 Cursor Docs；六类踩坑名称编译自论文＋官方“what to avoid”＋公开创作者指南。
正文
场景
仓库里已经有 README，你又加了 AGENTS.md，再在 Cursor 里堆一叠 Always Apply 规则。代理开始：装错包管理器、改不该动的目录、或干脆忽略你最在意的那条。问题往往不是“模型不听话”，而是说明文件本身又长又冲又旧。
下文按 Codex CLI 与 Cursor（含在 Cursor 里用 Codex／Agent）常见路径，列出可复现踩坑与改法。菜单与默认值以当前客户端为准。
可跟做步骤／可抄工作流
证据强度：高（OpenAI Learn＋Cursor Docs，核验日 2026-10-28）；字节上限与发现顺序以文档为准，本地可用配置覆盖。
- 先分清两套载体，避免双写互殴
– Codex 主路径：仓库根 AGENTS.md；子目录可用 AGENTS.md 或 AGENTS.override.md（同目录 override 优先于普通文件）。全局默认在 ~/.codex/AGENTS.md（AGENTS.md 文档）。
– Cursor 主路径：简单项目用根 AGENTS.md；需要按 glob／手动引用时用 .cursor/rules/*.mdc。注意：.cursor/rules 里的普通 .md 不会当规则加载（Rules）。
– 同时用两者：共享“命令／禁区／坑”只保留一份真相（通常根 AGENTS.md），Cursor 规则用短条引用“详见 AGENTS.md §Commands”，不要复制两长段后各改各的。
- 用／init 生成后立刻删胖（防 Init Fossilization）
Codex 会话里可用 /init 生成 AGENTS.md（见同系列《第一次开 Agent》与 Learn 文档）。生成稿常见问题：像给人看的入职 wiki、命令是猜的、风格指南整段粘贴。立刻做：
– 每条命令在本机跑一遍；失败的删掉或改成真命令。
– 删掉模型“总结架构”里你自己都不会维护的段落。
– 只留下：猜不到的命令、猜错会出事的边界、两次以上重复犯的错。
- 按五段骨架重写（可抄，删空节）
# AGENTS.md
## Commands
- 安装：【例如 pnpm install｜注明 Node 版本】
- 开发：【真端口／真脚本】
- 测试：【从哪一级目录跑；单包怎么 filter】
- 提交前：【lint && typecheck 的真实顺序】
## Layout
- 【仅非显而易见的路径】；生成物／vendor 目录标明“不要手改”
## Conventions
- 【linter 管不了的选择】例如错误类型、迁移怎么加
## Gotchas
- 【日期】【一句话坑＋正确做法】
## Do not
- 不要改【路径】；不要升级【依赖名】major；不要提交密钥- 嵌套仓库：子文件只写增量
Codex：从根拼到 CWD，近处覆盖远处。Cursor：嵌套 AGENTS.md 与父级合并，更具体优先。因此子包文件应写 delta（“这里用 make test-payments，不用根上的 npm test”），不要整份复制根文件：在 Codex 下等于规则出现两次，又占字节预算。
- Cursor 规则分层（可选）
– 全仓恒真 → alwaysApply: true 的短规则，或根 AGENTS.md。
– 某类文件 → globs:（如 src/components/**/*.tsx）。
– 偶尔流程 → Apply Manually／@规则名，或单独文档，避免 Always 塞满。
– 引用模板文件用 @path：内容不会自动内联；必须常驻上下文的句子请直接写进规则正文（Cursor Docs “Referencing files”）。
- 抽检是否真加载
– Codex（文档示例）：codex --ask-for-approval never "Summarize the current instructions."；子目录用 --cd 再问一次看覆盖是否生效。指令显旧就重启会话（每次 run／TUI 会话重建指令链）。
– Cursor：在 Agent 对话里问“列出当前生效的项目规则要点”；改完规则新开一轮任务再测。
– 若关键指导总不出现：查是否触顶 32 KiB、是否被空的 override 挡住、CODEX_HOME 是否指到别处、Cursor 规则是否用了错误扩展名。
真实用户诀窍／反例
- 踩坑 1：Context Bloat（文件当 wiki）
现象：二三百行架构史、路线图、全量脚本列表。后果：重要禁令被淹没；Codex 还可能在字节上限处截断尾部。
改法：站立规则保持短；长流程挪到按需文档／skill。公开样本里 Context Bloat 约占四成（arXiv 综述）。Cursor 亦建议拆分、避免整本风格指南（Rules｜What to avoid）。
- 踩坑 2：Lint Leakage（把格式规则写进提示）
现象：缩进、import 排序、行宽、camelCase 教条占满文件。
改法：交给 ESLint／Biome／Ruff／CI；AGENTS.md 只留“评审会打回、但工具管不住”的约定。公开样本中此项最常见（约六成）。
- 踩坑 3：Skill Leakage（把偶发长流程常驻加载）
现象：如何发版、如何给平台加新 OS、完整 code review 手册整段进 AGENTS.md。
改法：独立 markdown／Cursor 手动规则／技能目录；AGENTS.md 一行指向“何时去读”。
- 踩坑 4：Blind Reference（只丢路径不说明）
现象：见 docs/foo.md 再无一句。代理可能不打开，或整本灌进上下文。
改法：写清何时读、读哪一节、读完要遵守什么；Cursor 用 @file 时同样说明用途。
- 踩坑 5：Conflicting Instructions（自相矛盾）
现象：根写“组件放 A 目录”，后文或子文件写“放 B 目录”；或 AGENTS.md 与 Always Apply 规则相反。
改法：一处真相；冲突时删旧留新。嵌套覆盖要有意设计，不要靠模型“自行理解精神”。
- 踩坑 6：Init Fossilization（／init 后永不维护）
现象：生成后零提交，仓库继续狂改，规则仍指向旧包管理器。
改法：同一 PR 改 CI 就改 Commands；坑记日期，修好就删；同一错误出现第二次再加规则，不要每次翻车都追加一句恐吓。
- 诀窍：社区共识对齐官方“少写”
创作者指南普遍主张：命令必须可粘贴为真；过时说明比没有更糟；任务列表不要写进 AGENTS.md（autoplans 指南；r/codex 讨论）。
- 反例：Team／User／Project 规则与 AGENTS.md 四套平行小说。 Cursor 文档写明 Team → Project → User 合并且冲突时前者优先；再叠加一份过时 AGENTS.md，排查成本指数上升。
适用边界
- 本稿覆盖：AGENTS.md／Codex 发现链／Cursor rules 与嵌套优先级、六类常见踩坑与抽检命令。不评测哪家代理更强，也不替代你们公司的安全与合规政策。
project_doc_max_bytes默认 32 KiB、菜单文案、／init 产出质量：以你安装的 Codex／Cursor 版本与 2026-10-28 起官方文档为准。- 论文百分比来自特定 100 仓样本与检测方法，用作“很常见”的旁证，不是你仓库的体检报告。
【来源与编译】
- Custom instructions with AGENTS.md｜ChatGPT Learn｜https://learn.chatgpt.com/docs/agent-configuration/agents-md｜核验 2026-10-28（发现顺序、override、32 KiB、抽检与排障）
- Rules｜Cursor Docs｜https://cursor.com/docs/rules｜核验 2026-10-28（规则类型、避免事项、嵌套 AGENTS.md、.md 忽略、Team 优先序）
- Codex CLI｜https://learn.chatgpt.com/docs/codex/cli｜／init、／permissions 等会话命令语境
- Configuration Smells in AGENTS.md Files｜https://arxiv.org/html/2606.15828v5｜六类味道与公开仓发生率（旁证）
- AGENTS.md 结构指南｜https://autoplans.dev/guides/agents-md｜Commands／Gotchas 等实践（创作者指南）
- r/codex：Am I overdoing my AGENTS.md｜https://www.reddit.com/r/codex/comments/1ue0868/am_i_overdoing_my_agentsmd_file/
- 本文说明：编译官方加载规则＋可复现踩坑清单；未编造默认字节以外的隐藏上限；UI／命令以当前版本为准；论文数字保留为样本统计而非产品 SLA。