企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

API 地址：https://taotoken.net/api

你需要先拿到 API Key。进入控制台创建：

• 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

创建时建议按项目或用途命名，比如codex-frontend、codex-backend，方便后续排查是哪个项目在调用。Key 只在创建时完整显示一次，复制后立刻存到安全位置，不要硬编码进代码或提交到 Git。

注意：AGENTS.md里可以写「禁止硬编码密钥」，但真正的 Key 应该放在环境变量或settings.json引用的配置里，规则文件本身不承载密钥。

如果你后续要做长期编码或 Agent 任务，可以了解 Coding Plan：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

接入文档在这里，配置字段有疑问时对照查：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

3. 可复制配置：AGENTS.md 分层骨架 + settings.json

3.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 - 样式：SCSS，BEM 命名规范 ## 编码规范 - 组件文件使用 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_KEY=xxx，然后配置里写"api_key": "${TAOTOKEN_API_KEY}"，避免明文散落。approval_policy和sandbox_mode按你的安全要求调整，高风险项目建议收紧。

如果你更习惯用 Claude Code 那套接入方式，可以参考：

• ClaudeCodeAnthropic：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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.md，AI 完全不读。Codex 只认AGENTS.md和AGENTS.override.md，不支持自定义后缀。正确做法是在frontend/子目录下创建AGENTS.md，利用分层加载自动差异化。

6. 继续接入与验证

规则配好、验证通过之后，日常使用中如果遇到接入层面的报错，优先查 API Keys 和接入文档：

• API Keys：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

想先在对话里验证模型通道是否通，用模型对话：

• 模型对话：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

长期做编码或 Agent 任务，走 Coding Plan：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

最后留一个我自己的习惯：每次 AI 输出不符合预期，先别急着改 prompt，回头查AGENTS.md是不是缺了规则或者写得太模糊。补完规则后用三步验证法确认生效，每月清理一次过时规则，保持文件精简。规则越精准，AI 越可控。