一、为什么要做项目记忆#

在日常开发中，很多信息不是代码本身能完整表达的，例如：

• 这个项目常用哪些命令？
• 哪些文件不能随便改？
• 发布文章前要先检查什么状态？
• 哪些目录只是草稿收件箱，不能直接提交？
• 哪些 manifest 文件决定了后续是否会重复发布？
• 最近做过哪些改动，下次继续时应该先看哪里？

这些信息如果每次都重新解释，会浪费时间；如果不解释，又容易让 Agent 做出错误操作。

项目记忆的目标就是：让 Codex 每次进入项目时，先读到稳定、明确、可版本管理的上下文。

二、不要只依赖 Codex Memories#

Codex 的 Memories 可以辅助记住偏好、工作流、技术栈和已知坑点，但它更像一个后台回忆层。

真正需要长期、稳定、可控、可提交的规则，应该写进项目文件里。

我的分工是：

1
全局 AGENTS.md        个人通用规则
2
项目 AGENTS.md        当前项目的协作规则
3
CONTEXT.md            项目长期事实和架构上下文
4
PROJECT_MEMORY.md     面向后续任务的快速记忆
5
Codex Memories        辅助回忆，不作为唯一依据

这样做的好处是：即使换线程、换环境，只要项目文件还在，规则就不会丢。

三、全局 AGENTS.md：记录个人通用偏好#

全局文件一般放在：

1
C:\Users\你的用户名\.codex\AGENTS.md

它适合记录所有项目都通用的规则，例如：

• 默认使用中文回答。
• Git 默认只读，不自动 git add、commit、push。
• PowerShell 命令使用 pwsh，脚本里设置 $ErrorActionPreference = 'Stop'。
• 敏感信息、token、cookie、OAuth 凭据不能直接输出。
• 修改文件后要做最小验证，不能把“未验证”说成“已通过”。

这类规则和某个具体项目无关，应该放在全局层。

四、项目 AGENTS.md：记录项目专属协作规则#

每个项目根目录可以放一个：

1
AGENTS.md

这个文件适合告诉 Codex：进入这个项目后应该怎么工作。

例如：

1
# 项目协作指令
2

3
## 项目概况
4

5
- 本项目是 Astro 静态博客。
6
- 文章位于 `src/content/posts`。
7
- 项目长期上下文记录在 `docs/CONTEXT.md`，任务入口记忆记录在 `docs/PROJECT_MEMORY.md`。
8

9
## 常用命令
10

11
- 安装依赖：`pnpm install`
12
- 本地开发：`pnpm dev`
13
- 类型检查：`pnpm run type-check`
14
- 构建：`pnpm run build`
15

16
## 修改规则
17

18
- 开始任务前先读取 `docs/CONTEXT.md` 和 `docs/PROJECT_MEMORY.md`。
19
- 不做无关重构。
20
- 不进行全项目格式化。
21
- 修改发布流程、构建命令、目录结构后，同步检查项目记忆是否需要更新。

项目 AGENTS.md 不应该塞太多临时记录，它更像“项目协作规范”。

五、CONTEXT.md：记录稳定的项目事实#

docs/CONTEXT.md 适合放长期稳定的信息。

例如：

• 项目定位
• 技术栈
• 运行方式
• 重要目录
• 内容模型
• 发布流程
• 部署方式
• manifest 路径
• 已知长期坑点
• 推荐验证方式

它回答的是：这个项目到底是什么，以及长期应该怎么维护。

一个简单结构可以这样写：

1
# 项目长期上下文
2

3
## 项目定位
4

5
- 本项目是个人博客发布目标。
6
- 项目不仅包含主题代码，还包含内容发布脚本。
7

8
## 技术栈与运行方式
9

10
- 包管理器：pnpm。
11
- 框架：Astro、Svelte、TypeScript。
12
- 构建命令：`pnpm run build`。
13

14
## 重要目录
15

16
- `src/content/posts`：正式文章。
17
- `src/config`：站点配置。
18
- `scripts`：发布脚本和工具脚本。
19

20
## 何时更新本文档
21

22
- 改了架构、部署方式、发布流程、目录结构或关键命令时更新。

CONTEXT.md 不是日志，不需要记录每一次小改动。

六、PROJECT_MEMORY.md：记录后续任务入口#

docs/PROJECT_MEMORY.md 更适合放“下次接着做时最应该先想起来的东西”。

它可以记录：

• 最近的重要改动
• 后续任务入口
• 容易忘的维护提醒
• 当前项目的高频坑点
• 哪些测试命令最常用
• 哪些文件改动时要格外谨慎

比如：

1
# 项目记忆
2

3
## 当前任务入口
4

5
- 常见任务主要是发布文章、维护发布脚本、调整主题配置。
6
- 发布文章前必须先看状态，不能凭文件名直接复制。
7

8
## 近期重要记忆
9

10
- 最近新增了项目 `AGENTS.md`、`docs/CONTEXT.md`、`docs/PROJECT_MEMORY.md`。
11
- 最近发布脚本依赖 manifest 判断文章是否已经发布。
12

13
## 维护本文件的规则
14

15
- 只记录未来任务会反复用到的信息。
16
- 不记录一次性命令输出、临时调试步骤或未验证猜测。

如果说 CONTEXT.md 是项目档案，那么 PROJECT_MEMORY.md 就是后续任务的便签。

七、什么时候更新记忆#

我现在采用的规则是：

1
改了项目长期事实 → 更新 CONTEXT.md
2
新增近期维护提醒 → 更新 PROJECT_MEMORY.md
3
两者都影响 → 两个都更新

具体来说，下面这些情况应该更新：

• 改了架构或目录职责。
• 改了启动、构建、测试、部署方式。
• 改了内容发布流程。
• 改了 manifest 路径或发布状态机制。
• 新增一个以后会反复踩的坑。
• 做了长期有效的设计决策。
• 修改了项目级 AGENTS.md 规则。

下面这些情况通常不需要更新：

• 只修了一个很小的 bug。
• 临时调试命令。
• 一次性的错误输出。
• 还没确认的猜测。
• token、cookie、账号凭据等敏感信息。

八、我的推荐工作流#

以后每次进入项目，可以按这个流程：

1
1. 读取全局 AGENTS.md
2
2. 读取项目 AGENTS.md
3
3. 按项目 AGENTS.md 要求读取 docs/CONTEXT.md
4
4. 读取 docs/PROJECT_MEMORY.md
5
5. 开始处理任务
6
6. 任务结束前判断是否需要更新项目记忆
7
7. 运行必要验证
8
8. 给出本轮修改摘要和建议 commit message

当我明确知道这次改动会影响长期记忆时，可以直接对 Codex 说：

1
这次改动会影响项目记忆，帮我更新 docs/CONTEXT.md 和 docs/PROJECT_MEMORY.md

如果只是新增一个提醒，可以说：

1
把这个注意事项记录到 PROJECT_MEMORY.md

如果是稳定项目规则，可以说：

1
把这个发布流程变化同步到 CONTEXT.md

九、以 Firefly 项目为例#

在 Firefly 博客项目里，我最终整理了三类文件：

1
AGENTS.md
2
项目协作规则，告诉 Codex 如何处理这个仓库。
3

4
docs/CONTEXT.md
5
项目长期事实，包括技术栈、目录结构、发布流程、manifest 位置和验证方式。
6

7
docs/PROJECT_MEMORY.md
8
后续任务入口，包括近期改动、发布提醒、UI 行为记忆和常用测试命令。

这个项目里有文章发布流程，所以尤其要记录：

• Firefly-docs 是本地草稿收件箱，不是 Astro content collection。
• 发布前必须运行 node scripts\publish-firefly-doc.js --list。
• Firefly-docs/data/firefly-docs-publish-manifest.json 必须保留。
• 外部 LeetCode 题解目录默认只读。
• 发布图片时要复制到 public/assets/... 并重写成站点根路径。

这些规则如果只靠记忆，很容易在后续任务中漏掉；写进项目文档后，Codex 每次进入项目都能先读到。

十、总结#

让 Codex 对每个项目保持记忆，不是让它“凭空记住所有事”，而是把上下文放到正确的位置。

我的最终做法是：

1
个人习惯 → 全局 AGENTS.md
2
项目规则 → 项目 AGENTS.md
3
长期事实 → docs/CONTEXT.md
4
近期提醒 → docs/PROJECT_MEMORY.md
5
辅助回忆 → Codex Memories

这样既能保持自动化协作的连续性，也能让项目规则变得可检查、可提交、可迁移。