Codex新手必学（二）：普通人也能照抄的AGENTS.md配置教程

内容分享1周前发布

9 1 0

许多人第一次用 Codex，习惯一上来就提需求：

“帮我改这个功能。””帮我生成这个文件。””帮我跑一下测试。”

但我目前越来越觉得，Codex 新手最该先做的不是提需求，而是给它一份项目说明书。

这个文件就叫：AGENTS.md。

你不写，它就像一个刚进项目的新人：不知道项目结构，不知道哪些文件不能碰，也不知道改完后来怎么验收。

你写了，它才知道这个项目的基本规矩。

为什么 Codex 总像”失忆新人”

每开一个新对话，Codex 都进入新的上下文。

它不会天然知道你的项目结构。不知道哪个目录可以改、哪个文件不能碰。不知道项目常用命令和验证方式。

如果没有规则，你每次都要重新解释一遍。

Codex 不是不机智，它只是没有项目背景。

AGENTS.md 到底是什么

用人话解释：AGENTS.md 是一个 Markdown 文件。

README 是写给人看的。AGENTS.md 是写给 Codex 和其他 coding agent 看的。

它的作用是把项目规则、命令、边界、协作要求提前写清楚。

打个比方：README 像新员工入职手册，AGENTS.md 像给 AI 实习生看的工作 SOP。

Codex新手必学（二）：普通人也能照抄的AGENTS.md配置教程

AGENTS.md 应该放在哪里

三个层级：

项目根目录，最推荐，新手先这样做。

子目录，适合大项目，不同模块有不同规则。

全局目录，适合个人偏好，但要小心不要影响所有项目。

几个提醒：文件名必须是 AGENTS.md，大小写要对；项目级规则和个人偏好不要混在一起。

AGENTS.md 应该写什么

拆成6块。

第一块，项目概览。 项目是做什么的，主要语言和框架，关键目录。

第二块，常用命令。 安装依赖、本地运行、测试、格式化、构建。

第三块，目录边界。 哪些目录可以改，哪些目录不要碰，原始数据、书稿、素材库是否禁止修改。

第四块，代码/内容规范。 遵循现有风格，不做无关重构，不擅自改文件名，不编造数据或案例。

第五块，安全边界。 不读取或提交密钥，不执行危险删除命令，不批量修改用户资料。

第六块，交付要求。 改了哪些文件，怎么验证，哪些没验证，还有什么风险。

Codex新手必学（二）：普通人也能照抄的AGENTS.md配置教程

给一个可以直接照抄的 AGENTS.md 模板

# AGENTS.md

## 项目概览
- 项目类型：
- 主要目标：
- 关键目录：
- 不要修改的目录：

## 常用命令
- 安装依赖：
- 本地运行：
- 测试：
- 构建：

## 工作规则
- 优先读取相关文件，再修改。
- 不做无关重构。
- 不编造数据、案例和测试结果。
- 修改前先确认影响范围。

## 安全边界
- 不读取或提交 `.env`、密钥、账号密码。
- 不批量删除文件。
- 不修改原始资料，除非用户明确要求。

## 交付要求
- 说明修改了哪些文件。
- 说明运行了哪些验证。
- 说明未验证项和剩余风险。