Codex 配置 AGENTS.md 教程：让 AI 理解项目规则和站点维护流程

Codex 配置 AGENTS.md 不是写个文本就完事，很多人把项目扔给 Codex 之后，AI 乱改代码、忽略维护流程、甚至直接删文件，根源就是没给 AI 项目上下文。AGENTS.md 就是让 Codex 读懂项目规则和站点维护流程的“说明书”。

为什么 Codex 需要 AGENTS.md

Codex 本身是通用模型，不了解你的项目结构、部署规范、安全策略。AGENTS.md 放在项目根目录，Codex 读取后会自动遵循你定义的规则。比如你的站点维护流程要求“更新前先备份数据库”“修改配置后重启 Nginx”，如果不写进 AGENTS.md，Codex 可能直接改配置文件就跑，等着出事故。

创建 AGENTS.md 的核心结构

文件用 Markdown 写，Codex 会解析标题和列表。推荐包含以下几块：

项目规则

明确代码风格、提交规范、禁止操作。例如：

• 使用 2 空格缩进，禁止 Tab

• 所有 API Key 从环境变量读取，不硬编码

• 修改数据库结构前必须创建迁移文件

• 禁止直接在生产服务器上执行 rm -rf

站点维护流程

把日常操作步骤写清楚，Codex 会按顺序执行：

1. 更新代码前：执行 `git pull` 并检查冲突
2. 备份数据库：运行 `mysqldump -u root mydb > backup.sql`
3. 部署更新：`docker-compose up -d –build`
4. 重启服务：`systemctl restart nginx`
5. 检查状态：`curl -I http://localhost:8080`

安全注意事项

• 永远不要将 .env 文件提交到 Git

• 生产环境端口 22 仅允许特定 IP 访问

• 修改 Nginx 配置后先 `nginx -t` 再重载

实战配置过程

假设你有一个 PHP 站点跑在 VPS 上，需要 Codex 协助维护。先创建 AGENTS.md：

touch AGENTS.md

写入内容（用你喜欢的编辑器，比如 vim）：

markdown

项目简介

这是一个 WordPress 站点，使用 Nginx + PHP-FPM + MySQL，Docker 部署。

代码规则

• PHP 代码遵循 PSR-12 规范

• CSS/JS 使用压缩版本，不要提交源文件

• 所有修改必须经过 `phpcs` 检查

站点维护流程

日常更新

1. `git pull origin main`
2. `docker-compose down`
3. `docker-compose up -d –build`
4. `docker-compose exec php wp cache flush`

故障排查

• 先查看日志：`docker logs <container_name> –tail 50`

• 检查端口：`ss -tlnp | grep 80`

• 如果 502，重启 PHP-FPM：`docker-compose restart php`

禁止操作

• 不要直接在容器里修改文件，除非明确指定

• 不要删除 `wp-content/uploads` 目录

• 不要重启整个 Docker 环境，除非有明确说明

保存后，Codex 在项目目录下运行时自动读取。你可以在 Codex 的配置中指定 `–rules-file AGENTS.md` 或直接在项目内使用，Codex 会优先解析根目录的 AGENTS.md。

老鸟叮嘱

•AGENTS.md 不是一次性写的，项目更新了部署流程，记得同步修改文件。建议把 AGENTS.md 纳入版本控制，每次部署前检查差异。

•不要写废话，Codex 解析能力有限，规则要具体、可执行。比如“小心操作”不如“先备份再修改”。

•测试规则是否生效：给 Codex 一个明确指令，比如“更新 WordPress 插件”，看它是否先备份数据库。没按流程走，说明 AGENTS.md 写得太模糊或 Codex 没读到。

•安全第一：AGENTS.md 里不要写明文密码或 API Key，Codex 可能会在对话中暴露。敏感信息放环境变量，规则里只写“从 .env 读取”。

•如果 Codex 不读 AGENTS.md，检查文件名大小写（Linux 区分大小写），确保文件在项目根目录，且当前工作目录正确。

FAQ

Q1: AGENTS.md 只能用于 Codex 吗？

A: 主要针对 Codex，但类似工具如 Claude Code、Cursor 也支持 .cursorrules 或 .claude.md，格式类似，可以互相参考。

Q2: 多个项目共用一套规则怎么办？

A: 复制一份 AGENTS.md 到每个项目根目录，或者用符号链接。不建议全局规则，不同项目差异大。

Q3: AGENTS.md 写太长会不会影响 Codex 性能？

A: 不会，Codex 只读取前几 KB 内容做上下文，建议控制在 100 行以内，只写关键规则和流程。

Q4: Codex 不遵守规则怎么办？

A: 检查 AGENTS.md 语法是否正确，是否被忽略（比如文件名拼错）。也可以在对话中明确引用规则，比如“根据 AGENTS.md 第 3 条，先备份数据库”。

Q5: 生产环境能用 Codex 自动执行维护吗？

A: 建议先让 Codex 生成命令，手动确认后再执行。AGENTS.md 只是约束，不能完全替代人工审核。

Q6: AGENTS.md 需要放在 .gitignore 里吗？

A: 不建议，因为它是项目文档的一部分，应该提交到仓库。但注意不要在里面写敏感信息。

配置好 AGENTS.md 之后，Codex 就不再是瞎猜的助手，而是真正理解你项目规则和站点维护流程的搭档。花半小时写好这份文件，后面能省下无数排查时间。

—

**相关阅读：**

– [VPS 部署 AI 工具需要哪些基础？Linux、Docker、Nginx 和域名配置入门](https://www.zhujixuan.com/jishujiaocheng/9747.html)
– [Claude Code 与 Codex 对比：哪个更适合 VPS 远程开发](https://www.zhujixuan.com/jishujiaocheng/9816.html)
– [VPS部署AI工具100讲：AI Agent、Codex、Claude Code、Hermes Agent、Ollama与自动化工作流实战教程](https://www.zhujixuan.com/jishujiaocheng/9606.html)