1. 为什么 AGENTS.md 分层规则总是不生效如果你正在用 Codex 做项目级编码大概率遇到过这种场景明明在AGENTS.md里写了「禁止修改dist/目录」AI 还是把构建产物改了或者全局规则说「注释用中文」项目规则说「注释用英文」AI 一会儿中文一会儿英文行为完全不可预测。问题往往不在模型能力而在规则文件的分层结构和加载顺序没搞对。AGENTS.md是 Codex 识别项目指令的核心文件它支持从个人全局目录、项目根目录、子目录到 override 文件的多层叠加。层级一多踩坑点就集中爆发文件名少写一个字母、override 忘了删、文件超过 32KB 被截断、规则写得太模糊 AI 直接忽略。这些坑我在实际项目里基本都踩过一遍所以这篇不聊概念直接给可复制的规则模板骨架再把settings.json里 TaoToken 统一 Key 和 API 通道的配置写法讲清楚最后用一次真实请求验证规则到底有没有生效。适合谁看已经在用 Codex 做项目开发、想让 AI 稳定遵守团队规范、又不想每次手动重复交代上下文的开发者。读完你能拿到一套分层规则模板、一份settings.json骨架以及一套三步验证工作流。2. TaoToken 前置统一 Key 与 API 通道在配置settings.json之前先把 TaoToken 的接入信息准备好。TaoToken 在这里扮演的是统一 API 通道的角色Codex 通过它来调用模型你只需要维护一份 Key不用在多个项目里散落不同的凭证。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api你需要先拿到 API Key。进入控制台创建控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建时建议按项目或用途命名比如codex-frontend、codex-backend方便后续排查是哪个项目在调用。Key 只在创建时完整显示一次复制后立刻存到安全位置不要硬编码进代码或提交到 Git。注意AGENTS.md里可以写「禁止硬编码密钥」但真正的 Key 应该放在环境变量或settings.json引用的配置里规则文件本身不承载密钥。如果你后续要做长期编码或 Agent 任务可以了解 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里配置字段有疑问时对照查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content3. 可复制配置AGENTS.md 分层骨架 settings.json3.1 四层 AGENTS.md 的职责划分先把分层逻辑理清楚后面配置才不会乱。Codex 的加载顺序是个人全局 → 项目根目录 → 子目录 → override。子目录规则优先级更高会覆盖上层override 文件存在时同目录的AGENTS.md会被完全忽略。第一层个人全局偏好路径~/.codex/AGENTS.md只写跨项目通用的内容# 个人全局编码偏好 ## 语言与风格 - 所有注释和文档使用中文 - 代码变量命名使用英文 camelCase - 优先使用 ES6 语法避免 var ## 安全底线 - 禁止在代码中硬编码密码、密钥、Token - 禁止执行 rm -rf、DROP TABLE 等破坏性命令 - 无明确指令禁止主动 git push ## 完成规范 - 每次修改代码后简要说明改了什么、为什么改 - 遇到不确定的问题先询问再操作第二层项目根目录路径repo/AGENTS.md写整仓统一规范。禁止类规则必须放最前面因为文件有 32KB 上限一旦被截断后面的规则就丢了# 项目全局规则 ## 禁止操作最高优先级 - 禁止手动修改 dist/、.next/、coverage/ 目录下的任何文件 - 禁止修改 .env.production 文件 - 禁止删除 migrations/ 目录下的历史迁移文件 - 禁止修改 package-lock.json除非明确要求 ## 通用命令 - 安装依赖pnpm install - 代码检查pnpm lint - 运行测试pnpm test - 构建项目pnpm build - 修改代码后必须执行 pnpm lint 校验 ## Git 规范 - Commit 信息遵循 Conventional Commits 规范 - 无明确指令禁止 git commit 和 git push - 分支命名feature/xxx、fix/xxx、refactor/xxx ## 安全规则 - 支付相关逻辑修改前必须阅读 docs/payment-rules.md - 用户权限相关修改前必须阅读 docs/auth-rules.md - 数据库 schema 变更必须生成 migration 文件 ## 完成汇报 - 修改文件后列出所有变更文件路径 - 如有破坏性变更明确标注影响范围第三层子目录差异化规则比如repo/frontend/AGENTS.md只写前端特有内容通用规则交给根目录# 前端专属规则 ## 技术栈 - 框架Vue 3 Composition API - 状态管理Pinia - UI 组件库Element Plus - 样式SCSSBEM 命名规范 ## 编码规范 - 组件文件使用 PascalCase 命名UserProfile.vue - 组合式函数使用 use 前缀useAuth.ts - 禁止直接操作 DOM必须通过 Vue 响应式系统 - 禁止在组件内使用 any 类型 ## 目录约束 - 页面组件放在 views/ 目录 - 可复用组件放在 components/ 目录 - 禁止在 views/ 中编写可复用逻辑提取到 composables/ - 静态资源放在 assets/禁止使用外部 CDN 链接 ## 测试要求 - 新增组件必须编写单元测试 - 测试文件与组件同目录UserProfile.spec.ts - 运行前端测试pnpm --filter frontend test第四层高风险模块 override比如repo/backend/modules/payment/AGENTS.override.md。这里要特别注意override 存在时同目录AGENTS.md被完全忽略所以必须写全该目录需要的所有规则不能只写差异# 支付模块强制规则override ## 绝对禁止任何情况不可违反 - 禁止修改订单金额计算逻辑 - 禁止修改退款流程和退款金额校验 - 禁止删除支付回调验签逻辑 - 禁止跳过支付状态校验 ## 修改前必须执行 - 修改任何文件前必须先阅读 docs/payment-rules.md - 涉及金额的字段修改必须输出变更前后对比 - 涉及状态流转的修改必须画出状态机变更图 ## 测试要求 - 任何修改必须通过支付模块全量测试 - 运行测试pnpm --filter backend test -- --grep payment - 测试未通过禁止提交代码 ## 完成汇报 - 必须列出所有修改文件和修改原因 - 必须说明是否影响订单金额、退款流程、回调验签 - 如有影响标注影响范围和回滚方案3.2 settings.json 骨架TaoToken 统一通道settings.json负责把 Codex 的模型调用指向 TaoToken 的统一 API 通道。下面是一份可直接改的骨架把YOUR_TAOTOKEN_API_KEY替换成你在控制台创建的 Key{ model_provider: taotoken, model: claude-sonnet-4-20250514, providers: { taotoken: { base_url: https://taotoken.net/api, api_key: YOUR_TAOTOKEN_API_KEY, wire_api: chat } }, approval_policy: on-request, sandbox_mode: workspace-write }几个字段说明一下。base_url固定指向https://taotoken.net/api不要加多余路径。api_key建议通过环境变量注入比如在 shell 里export TAOTOKEN_API_KEYxxx然后配置里写api_key: ${TAOTOKEN_API_KEY}避免明文散落。approval_policy和sandbox_mode按你的安全要求调整高风险项目建议收紧。如果你更习惯用 Claude Code 那套接入方式可以参考ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注意settings.json里的 Key 和AGENTS.md里的规则是两回事。前者管「怎么调用模型」后者管「模型该遵守什么」。别把 Key 写进AGENTS.md也别指望规则文件能替代鉴权配置。4. 验证请求规则到底有没有生效配置写完不算完必须验证。我常用的三步工作流每步都有明确命令。第一步查哪些指令文件被加载了codex --ask-for-approval never Show which instruction files are active.这条命令会列出当前生效的AGENTS.md和 override 文件路径。如果某个子目录的规则没出现在列表里说明路径或文件名有问题。第二步查规则是否被理解codex --ask-for-approval never Summarize the current instructions.它会用自然语言复述当前生效的规则。如果复述里漏掉了「禁止操作」部分很可能是文件太长被截断或者禁止类规则没放在最前面。第三步用小任务实测。在支付目录下让 AI 改一行代码观察它是否先读取了docs/payment-rules.md。如果它直接动手改说明安全规则没生效回到第一步排查加载列表。一次成功的验证输出大概长这样指令文件列表包含~/.codex/AGENTS.md、repo/AGENTS.md、repo/backend/AGENTS.md、repo/backend/modules/payment/AGENTS.override.md规则复述里明确提到「支付模块修改前必须阅读 payment-rules.md」实测时 AI 先输出了「正在阅读 docs/payment-rules.md」再动手。三步都通过才算配置落地。5. 本篇常见错排查坑一文件名写错。现象是规则写好了 AI 完全不遵守原因多半是写成了AGENT.md少了个 S。Codex 只认AGENTS.md一个字母都不能差。坑二override 遗忘。之前为了临时修复加了AGENTS.override.md后来忘了删导致同目录AGENTS.md被完全替代。用第一步的加载列表命令就能发现看到 override 还在生效就手动删掉。坑三文件太长被截断。前面的规则有效后面的规则 AI 当没看见。AGENTS.md默认 32KB 上限把架构文档塞进去后关键规则就被截断了。详细文档移到docs/AGENTS.md只保留核心执行规则禁止类放最前面。坑四规则冲突。全局写「注释用英文」项目写「注释用中文」AI 行为不一致。记住子目录优先级更高会覆盖上层加载顺序是全局 → 项目 → 子目录 → override。冲突时以更具体的层级为准。坑五规则太模糊。写「注意代码质量」AI 完全无视。改成具体动作比如「修改代码后执行 pnpm lint 校验格式」AI 才能执行。坑六自定义文件名不生效。建了AGENTS.frontend.mdAI 完全不读。Codex 只认AGENTS.md和AGENTS.override.md不支持自定义后缀。正确做法是在frontend/子目录下创建AGENTS.md利用分层加载自动差异化。6. 继续接入与验证规则配好、验证通过之后日常使用中如果遇到接入层面的报错优先查 API Keys 和接入文档API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先在对话里验证模型通道是否通用模型对话模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content长期做编码或 Agent 任务走 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留一个我自己的习惯每次 AI 输出不符合预期先别急着改 prompt回头查AGENTS.md是不是缺了规则或者写得太模糊。补完规则后用三步验证法确认生效每月清理一次过时规则保持文件精简。规则越精准AI 越可控。