第5章让 Codex 懂你的项目

约 2365 字大约 8 分钟

2026-06-09

这一章来聊聊怎么给 Codex 写一份"项目说明书"，让它一上来就了解你的项目，不用你每次都从头解释。

5.1 为啥需要 AGENTS.md？

想象一下这个场景：

你招了个新员工，第一天上班。每次给他安排活儿，都得从头介绍一遍： "咱们公司用的是 Java、数据库是 MySQL、代码要遵循阿里巴巴规范、打包用 Maven、部署到阿里云……"
说一次还行，每次都说？太累了。

AGENTS.md 就是解决这个问题的。

它就是一个放在项目目录里的文件，Codex 每次启动时会自动读取它。在里面写好项目信息，Codex 就不用你每次都重复了。

没有 AGENTS.md：
你："项目用的是 Vue 3 + TypeScript..."
Codex："好的"
你（下次）："项目用的是 Vue 3 + TypeScript..."
Codex："好的"
你（下下次）："项目用的是……" 😫

有 AGENTS.md：
你（写好一次）："项目信息都在 AGENTS.md 里"
Codex（每次自动读取）："我已了解项目背景" 😊

一句话搞懂 AGENTS.md

AGENTS.md 就是给 Codex 写的"入职手册"，写好一次，长期省心。

5.2 AGENTS.md 的层级结构

AGENTS.md 可以放在不同位置，不同位置管的事情不一样：

文件放哪里？

放在哪里	管多大范围	适合写啥
`~/.codex/AGENTS.md`	所有项目	个人偏好（比如喜欢用什么风格、通用规范）
项目根目录 `AGENTS.md`	当前项目	项目信息（技术栈、结构、编码规范）
子目录 `AGENTS.md`	只管这个目录	特定模块的细节（比如 API 文档）

叠加关系

Codex 会读取所有层级的 AGENTS.md，不是只读一个。信息会叠加在一起生效。

比如说，你在全局写了"用中文回复"，在项目级写了"用 React"，在 src/components/ 里写了"组件用 PascalCase 命名"。Codex 会把这三层信息全读进去，一起遵守。

5.3 AGENTS.md 里写点啥？

建议写的内容

一定要写的：

项目简介 —— 一句话说清楚这个项目是干嘛的
技术栈 —— 什么语言、什么框架、什么数据库
项目结构 —— 主要目录都是干嘛的
编码规范 —— 希望 Codex 遵循的规则

建议也写上的：

常用命令 —— 怎么启动、怎么测试、怎么构建
注意事项 —— 特殊约定、容易踩坑的地方
部署信息 —— 怎么部署、部署到哪

来看个实际的好例子

假设你有一个 Vue 3 + TypeScript 的前端项目：

# 项目简介
一个在线笔记应用，支持 Markdown 编辑、分类管理和全文搜索。

# 技术栈
- 前端：Vue 3 + TypeScript + Pinia
- 样式：Tailwind CSS
- 构建：Vite
- 测试：Vitest + Vue Test Utils
- 部署：Nginx + Docker

# 项目结构
- src/views/ — 页面组件
- src/components/ — 通用组件
- src/stores/ — Pinia 状态管理
- src/api/ — 后端接口调用
- src/utils/ — 工具函数

# 编码规范
- 组件文件名用 PascalCase（如 NoteEditor.vue）
- 工具函数用 camelCase（如 formatDate.ts）
- CSS 用 Tailwind 类名，不写自定义样式
- 统一用 composition API，不用 options API

# 常用命令
- 启动开发：pnpm dev
- 运行测试：pnpm test
- 构建生产：pnpm build
- 代码检查：pnpm lint

# 注意事项
- 不要修改 src/api/config.ts 里的接口地址，那是自动生成的
- 数据库迁移脚本放在 migrations/ 目录，文件名要带时间戳

再看看反面教材

# ❌ 不好的 AGENTS.md

这个项目是一个使用 Vue.js 框架开发的现代化 Web 应用程序，
我们团队在经过多次技术选型讨论后，决定采用 TypeScript 作为
主要开发语言，因为它提供了更好的类型安全和开发体验，
同时我们还引入了 Pinia 作为状态管理方案……

（后面还有 200 行流水账）

问题在哪？ 写太长了！Codex 读 AGENTS.md 也是占"注意力空间"的。写得越长，Codex 能用的空间就越少。而且大段描述根本不如关键词来得清楚。

关键原则

好的 AGENTS.md：简明扼要，一眼看清，控制在 60 行以内。不好的 AGENTS.md：几百行的流水账，把所有代码都贴进去。

5.4 好和不好，对比一下

编码规范怎么写

# ❌ 模糊写法
代码要写得好一点，风格要统一

# ✅ 具体写法
- 组件文件名用 PascalCase
- 变量名用 camelCase
- 常量用 UPPER_SNAKE_CASE
- 所有函数都要有返回类型注解

项目结构怎么写

# ❌ 啥也没说
项目结构见代码

# ✅ 一目了然
- src/views/ — 页面组件
- src/components/ — 通用组件
- src/api/ — 后端接口
- src/utils/ — 工具函数

常用命令怎么写

# ❌ 太随意
跑一下就能启动

# ✅ 清清楚楚
- 启动：pnpm dev
- 测试：pnpm test
- 构建：pnpm build

结果是不言而喻的——你写得越清楚，Codex 干活就越靠谱。

5.5 动手试试：给项目创建 AGENTS.md

来，实际操作一遍。

第一步：打开项目目录

cd 你的项目路径

第二步：启动 Codex

codex

第三步：让 Codex 帮你生成

在聊天里输入：

帮我分析当前项目，生成一份 AGENTS.md 文件。
要求：
1. 包含项目简介、技术栈、项目结构、编码规范、常用命令
2. 控制在 60 行以内
3. 简洁明了，只写关键信息

Codex 会自动分析你的项目，帮你生成一份合适的 AGENTS.md。

第四步：检查和调整

Codex 生成后，你可以：

让它读取生成的文件给你看看
告诉它哪里需要补充或修改
确认没问题后保存

第五步：验证效果

退出 Codex，重新启动：

codex

然后问它：

这个项目用的什么技术栈？编码规范是什么？

如果 Codex 能正确回答，说明 AGENTS.md 已经生效了！

省力小技巧

不想自己手写的话，直接让 Codex 分析项目帮你生成就行。生成后再看看需不需要调整，比自己从零写快多了。

5.6 几个常见的坑

坑1：写得越多越好？并不是

注意

AGENTS.md 太长会占掉大量"注意力空间"，反而让 Codex 表现变差。

建议： 控制在 30-60 行，只写最关键的。细节可以放到子目录的 AGENTS.md 里分担。

坑2：把它当文档来写

注意

AGENTS.md 是给 Codex 看的"速查卡"，不是给人看的详细文档。

建议： 用关键词和短句，别写长篇大论。

# ❌ 不好的写法
这个项目是一个使用 Vue 框架开发的现代化 Web 应用程序，
我们团队决定采用 TypeScript 作为主要开发语言……

# ✅ 推荐的写法
技术栈：Vue 3 + TypeScript + Pinia + Vite

坑3：写好就不改了

注意

项目会变化，AGENTS.md 也得跟着更新。

建议： 当技术栈或项目结构有变化的时候，顺手把 AGENTS.md 也更新一下。你想想，Codex 还以为你在用 Vue 2，结果项目早换成 Vue 3 了，它能干对才怪。

坑4：只放在根目录

注意

如果项目比较大，一个 AGENTS.md 装不下所有信息。

建议： 大项目用多级 AGENTS.md。根目录写全局信息，子目录写模块细节。这样每层的信息都不会太长。

5.7 再聊几个进阶玩法

给 Codex 设定"角色"

# 角色设定
你是一个资深的前端性能优化专家。审查代码时要特别关注：
- 不必要的重渲染
- 大列表有没有用虚拟滚动
- 图片有没有做懒加载
- 首屏加载时间

给 Codex 一个"人设"，它就会用这个角色的视角来干活，出来的结果更有针对性。

设定回复格式

# 回复格式
- 用中文解释
- 给出代码时标注文件路径
- 修改代码时说明改了什么、为什么改
- 修改前后的代码都要展示

告诉 Codex 你希望它怎么回复，省得每次都说"请用中文解释"、"请标注文件路径"。

全局 AGENTS.md 示例

放在 ~/.codex/AGENTS.md，对所有项目都生效：

# 个人偏好
- 用中文回复
- 代码注释用英文
- 变量命名用 camelCase
- 优先推荐最简单的方案，不要过度设计

提示

全局 AGENTS.md 适合放个人偏好（比如语言、命名风格），项目级 AGENTS.md 适合放项目相关的信息。两者叠加在一起生效，互不冲突。

5.8 小结

要点	一句话总结
AGENTS.md 是啥	给 Codex 写的"入职手册"，让它了解你的项目
写啥内容	项目简介、技术栈、结构、规范、常用命令
放在哪里	项目根目录（必须）、子目录（可选）、全局（可选）
多长合适	30-60 行，简洁为上
啥时候更新	技术栈变了、项目结构调整了就更新
叠加关系	多层 AGENTS.md 信息会叠加在一起生效

一句话： AGENTS.md 就是给 Codex 写的"项目小抄"，写好一次，长期省心。

下一章来聊聊 Codex 要干活的时候，怎么保证安全不乱来：第6章 Codex 要干活，安全吗？

第5章 让 Codex 懂你的项目

第5章让 Codex 懂你的项目