# Codex 记忆与 AGENTS.md

> 用 AGENTS.md 让 Codex 记住项目规则和个人偏好，告别反复交代上下文。

URL: https://docs.passion8.cc/docs/codex/memory
Language: zh-CN
Publisher: Passion8

不要假设新会话自动继承上次全部信息;可用的 Memories 功能与明确的项目指令是不同机制。解决办法是把需要长期生效的信息写进 `AGENTS.md`——每次启动时 Codex 都会读取它,就像每次上班前先看一遍工作手册。

## README.md、AGENTS.md、.gitignore 有什么区别

三个文件看似都是"项目说明",但读者完全不同:

| 文件 | 读者 | 作用 |
| --- | --- | --- |
| `README.md` | 人 | 项目是什么、怎么安装、怎么使用 |
| `AGENTS.md` | Codex / AI | 在这个项目里应该怎么工作 |
| `.gitignore` | Git | 哪些文件不上传到仓库 |

## AGENTS.md 放在哪里

`AGENTS.md` 支持分层放置,多份文件叠加生效:

| 位置 | 生效范围 |
| --- | --- |
| 项目根目录 `AGENTS.md` | 整个项目的总规则,随仓库共享给团队 |
| 子目录 `src/AGENTS.md` | 只影响该目录及其子目录,适合模块专属规则 |
| `~/.codex/AGENTS.md` | 你本人所有项目的全局偏好 |

全局和项目级同时存在时,两者叠加生效——个人习惯 + 当前项目规则同时起作用。

## 怎么写 AGENTS.md

不必从零开始手写。把项目丢给 AI,让它读一遍代码后替你生成初稿:

```bash
codex "读一下这个项目,帮我生成一份 AGENTS.md,涵盖技术栈、常用命令、目录结构和代码规范"
```

生成后检查一遍,删掉废话、补上你最在意的限制,就可以用了。

## 前端项目 AGENTS.md 模板

以下是一份精简的前端项目示例,可按实际情况裁剪:

```markdown
# 项目说明

前端网页项目。

## 技术栈

- React + Vite + TypeScript
- 样式:Tailwind CSS
- 不引入 Bootstrap 或其他 CSS 框架

## 常用命令

- 安装依赖:`npm install`
- 本地开发:`npm run dev`
- 构建:`npm run build`

## 项目结构

- src/: 主源码
- src/components/: 公共组件
- src/pages/: 页面
- src/assets/: 静态资源
- public/: 不经打包直接输出的资源

## 代码规范

- 优先使用 React 函数组件
- 样式优先用 Tailwind 工具类,不要内联 style
- 中文文案保持自然简洁
- 不做与当前任务无关的大范围重构

## UI 规则

- 保持清晰的信息层级
- 按钮、卡片、标题留白统一
- 移动端基本可用
- 避免过度渐变、阴影和"AI 模板感"——追求真实产品感

## 禁止事项

- 不修改 `.env` / `.env.local`
- 不在输出里暴露 Key、token 或密码
- 不删除已有核心功能
- 不随意引入大型依赖
- 不改动与当前任务无关的文件

## 完成任务后

输出说明:
1. 改了哪些文件
2. 每个文件改了什么、为什么
3. 是否需要重新跑 `npm run build`
4. 提醒检查 git diff 确认无误
```

## 好的 AGENTS.md 有哪些特点

| 特点 | 说明 |
| --- | --- |
| 具体 | 写清技术栈、命令、目录,不说"用主流方式" |
| 简洁 | 去掉废话,Codex 读的是信息密度,不是字数 |
| 可执行 | 每条规则都能直接遵守,不含歧义 |
| 有限制 | 明确哪些文件不能动、哪些依赖不能加 |
| 有验证 | 说明用什么命令检查结果(测试/构建/lint) |
| 有完成标准 | 告诉 Codex 任务结束后要输出什么 |
| 可维护 | 项目升级或换栈后及时更新 |

## 全局级 AGENTS.md

全局 AGENTS.md(`~/.codex/AGENTS.md`)适合放个人通用偏好——和项目无关、但每次都想生效的习惯。

也可以在 Codex 界面里设置:打开 **Codex 设置 → 个性化**,直接输入指令,效果相同。

![全局级 AGENTS.md 设置](https://docs.passion8.cc/images/codex/image-071-c36b13b759.png)




全局设置会影响**所有项目**的所有会话,只放真正通用的规则。项目专属规则请放在项目根的 `AGENTS.md`,不要混入全局。




**安全指令示例:防止 AI 批量删除文件**

```markdown
禁止批量删除文件或目录。
不得使用 rm -rf、Remove-Item -Recurse、rd /s、rmdir /s 等递归删除命令。
需要删除时,每次只能删除一个明确路径的单个文件。
如果任务需要批量删除,应立即停止并提示用户手动操作。
```

把类似规则加进全局 AGENTS.md,可以为所有项目建立一道基础防线。