用 AGENTS.md 让 Codex 遵守项目规范

用 AGENTS.md 保存项目约定，理解目录作用范围、覆盖关系与验证方式。

适用范围：涉及账户、Key、模型、计费或接口的内容，请以 GPT88 当前控制台和对应 API 文档为准。

返回教程库

GPT88 使用说明 模型名、版本、默认值和平台入口可能随客户端版本变化，请按 GPT88 当前模型目录和客户端显示核对。

快速开始 · 模型导航 · GPT88 API Key 管理

同一个项目里，有的页面使用现成组件，有的模块需要特别的验证命令。如果每次开始任务都重新解释这些约定，很容易遗漏。把长期有效、适用于整个项目的规则写进 AGENTS.md，Codex 开始工作时就能读到。

这篇教程会带你建立一份简短的项目约定，验证它是否被读取，再为特殊模块添加覆盖规则。还未运行过 Codex，可以先看学习路线和读懂现有项目。

哪些内容适合写进去

优先记录 Codex 无法单靠代码轻易判断、却会反复影响工作的约定，例如使用哪套工具链、修改接口时要同步哪些文件、提交前运行什么检查，以及最终需要怎样汇报。

当前任务的需求和复现步骤，直接放在对话中。
项目长期适用的规范，放进 AGENTS.md。
只在某类任务中使用的多步骤流程，整理成 Skill。不要把整份 README 复制进来，也不要填写项目实际上不存在的测试命令。先查看 README、依赖文件和现有 CI，再写准确的规则。

第一步：在项目根目录创建文件

在仓库根目录创建 AGENTS.md，从下面这份最小模板开始。命令部分刻意要求读取当前项目配置，适合还没整理完工具链的项目。

# 项目工作约定

## 开始任务

- 先阅读 README 和依赖配置，确认启动、构建和检查命令。
- 优先沿用现有组件、目录结构和代码风格。
- 修改前检查当前工作区，保留已有的无关改动。

## 实现与验证

- 修复问题时先确认复现步骤和预期行为。
- 新增界面功能时处理加载、错误和空数据状态。
- 运行与改动相关的现有检查，并记录实际结果。
- 无法运行的检查说明原因，不把未验证结果描述成通过。

## 交付说明

- 用中文说明改动内容、验证结果和待确认事项。
- 引用关键文件，便于查看和审阅。

项目稳定后，可以把第一条换成确切命令，例如项目确认使用 npm 且定义了对应脚本时，记录 npm run lint 与 npm run build。规则需要随工具链一起维护。

第二步：理解范围和覆盖关系

官方当前文档说明，Codex 启动时建立指令链。全局约定位于 Codex home，默认是 ~/.codex；如果设置了 CODEX_HOME，则使用该目录。项目约定从仓库根目录一路读取到启动时的当前工作目录。

位置	适合放置的内容
~/.codex/AGENTS.md	个人跨项目偏好，例如回复语言
项目根目录/AGENTS.md	整个仓库共同遵守的规则
项目子目录/AGENTS.md	该模块的工具链和验证要求

同一目录优先读取非空的 AGENTS.override.md，其次是 AGENTS.md，再考虑配置的备用文件名；每个目录最多采用一个文件。不同目录的文件按从根到当前目录的顺序组合，更靠近当前目录的规则可以覆盖较早的规则。

例如，一个仓库的根目录约定运行通用检查，而 services/payments/AGENTS.md 约定运行支付模块检查。从这个子目录启动 Codex，可以让模块规则进入指令链。不要假定任意深层目录的文件都会在根目录会话启动时全部加载。

第三步：验证 Codex 实际读到了什么

保存文件后，在项目根目录启动一个新的 Codex CLI 会话：

codex

然后发送：

请列出本次会话读取的项目指令文件，并总结当前生效的工作约定。
先不要修改项目。重点说明工具链、验证要求和最终交付格式。

需要验证子目录规则时，在该目录重新启动会话：

codex --cd services/payments

请将示例路径换成真实模块。核对输出是否同时反映全局、根目录与模块约定。修改指令后若会话仍表现为旧规则，重新启动，让 Codex 重新构建指令链。

一次练习与验收

选择一个小任务，例如为现有表单完善空值提示。按照功能开发实战描述目标，观察 Codex 是否沿用现有组件、执行相关检查并如实汇报。规则本身不是完成质量的保证，仍需查看实际改动和检查输出。

Codex 能准确总结你写入的关键约定。
真实检查命令与项目配置一致。
特殊模块规则在对应目录启动的会话中生效。
最终报告区分已验证结果与未验证事项。如果规则未生效，依次检查当前目录、CODEX_HOME、上层是否存在覆盖文件、文件是否为空。官方默认合并上限为 32 KiB；内容过长时先精简或按模块拆分。不要将密钥、登录文件或其他凭证写进项目指令。

官方参考

核对日期：2026-10-19。路径发现和覆盖规则依据官方当前文档；不同客户端版本的入口可能调整。