Codex CLI 上下文持久化设计
Codex CLI 是 OpenAI 推出的轻量级终端 AI 编程助手，通过 AGENTS.md 文件实现跨会话的上下文持久化能力。
一、设计原理
1.1 核心问题：AI 代理的”失忆”
传统 AI 编程助手存在一个根本性缺陷：每次会话都是全新的开始。这导致：
- ❌ 重复解释项目架构和业务逻辑
- ❌ 编码偏好和规范无法跨会话保持
- ❌ 重要架构决策需要反复说明
- ❌ 长期项目缺乏连贯的开发上下文
1.2 解决思路：AGENTS.md 持久化文件
Codex CLI 通过 项目级 AGENTS.md 文件 实现上下文持久化：
┌─────────────────────────────────────────────────────────────┐
│ Codex 持久化架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 会话启动 │ ──▶ │ AGENTS.md │ ──▶ │ 上下文注入 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 工作执行 │ ──▶ │ 手动更新 │ ──▶ │ 持久化存储 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AGENTS.md │ │
│ │ ├─ 项目描述 │ │
│ │ ├─ 架构决策 │ │
│ │ ├─ 编码规范 │ │
│ │ ├─ 技术栈信息 │ │
│ │ └─ 团队约定 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
核心设计原则：
| 原则 | 说明 |
|---|---|
| 文件持久化 | 通过 AGENTS.md 文件在项目根目录存储 |
| Markdown 格式 | 使用标准 Markdown，易于版本控制 |
| 手动维护 | 开发者主动更新，确保信息准确性 |
| 会话独立性 | 文件在会话之间持久存在 |
| 轻量高效 | 会话开始时自动加载，避免重复说明 |
1.3 AGENTS.md 文件结构
Codex CLI 的 /init 命令会生成一个 AGENTS.md 模板，其核心结构包括：
AGENTS.md
├─ 项目上下文
│ ├─ 项目描述
│ ├─ 技术栈
│ └─ 核心目标
├─ 开发规范
│ ├─ 编码风格
│ ├─ 架构原则
│ └─ 团队约定
└─ 重要决策
├─ 技术选型理由
├─ 设计模式
└─ 已知限制
关键特点：
- 📝 单一文件：所有上下文信息集中在一个文件中
- 🔄 版本控制：可作为项目的一部分进行 Git 管理
- 👥 团队共享：团队成员可以协作维护这个文件
- ⚡ 自动加载：每次会话开始时 Codex 自动读取该文件
二、AGENTS.md 文件详解
2.1 文件结构
AGENTS.md 是 Codex CLI 的核心持久化文件，通过 /init 命令生成。其结构分为几个关键部分：
| 部分 | 用途 | 维护建议 |
|---|---|---|
| 项目上下文 | 项目描述、目标、技术栈 | 初始化后较少变化 |
| 开发规范 | 编码风格、架构原则 | 相对稳定，团队共识 |
| 重要决策 | 技术选型、设计决策 | 随项目发展累积更新 |
2.2 AGENTS.md 内容示例
# 项目上下文
## 项目描述
这是一个实时协作的在线白板工具，支持多人同时编辑和图形绘制。
## 核心功能
- WebSocket 实时同步
- Canvas 2D 绘图引擎
- 多用户光标跟踪
- 导出 PNG/PDF
## 技术栈
- 前端: React + TypeScript
- 后端: Node.js + Socket.io
- 存储: PostgreSQL
# 开发规范
## 编码风格
- 使用 2 空格缩进
- 单引号优先
- 箭头函数用于回调，class 方法用于对象方法
## 工具配置
- ESLint: @typescript-eslint/recommended
- Prettier: 单行最大 80 字符
- 测试框架: Vitest
## Git 工作流
- 功能分支命名: `feature/描述`
- 提交信息: Conventional Commits
# 重要决策
## 架构决策
- 使用 CRDT 算法处理冲突解决（2024-01-15）
- Canvas 渲染层与逻辑层分离（性能优化）
- 状态管理采用 Zustand（避免 Redux 冗余）
## 重要约定
- API 路由前缀统一为 `/api/v1/`
- 组件使用 PascalCase 命名
- 工具函数使用 camelCase 命名
## 已知限制
- WebSocket 连接在高并发下不稳定
- 导出 PDF 时中文乱码三、使用场景
3.1 场景一：长期项目维护
问题场景： 一个持续 6 个月的项目，每周多次开发，但每次重新打开项目都需要重新解释架构。
AGENTS.md 解决方案：
第1周：初始化 AGENTS.md
├─ 运行 /init 命令生成模板
├─ 填写项目描述和技术栈
└─ 定义编码规范和架构原则
第4周：架构调整
└─ 更新 AGENTS.md：添加"从 Redux 迁移到 Zustand"的决策记录
第12周：新人加入
└─ 新成员通过 AGENTS.md 快速了解项目背景和规范
第24周：功能迭代
└─ 继续在 AGENTS.md 中累积新的设计决策
效果：
- ✅ 新成员 30 分钟理解项目（vs 传统 2 小时）
- ✅ 编码风格自动保持一致
- ✅ 架构决策有完整历史记录
3.2 场景二：多开发者协作
问题场景： 团队多人使用 Codex CLI，每个人有不同的编码偏好，容易产生风格冲突。
AGENTS.md 解决方案：
| 协作方式 | 说明 |
|---|---|
| 团队共识 | 在 AGENTS.md 中定义统一的编码规范 |
| 版本控制 | 将 AGENTS.md 加入 Git，所有人共享 |
| 代码审查 | PR 时检查是否符合 AGENTS.md 中的规范 |
效果：
- ✅ Codex 自动遵循团队编码规范
- ✅ 减少代码审查中的风格争议
- ✅ 新人自动继承团队最佳实践
3.3 场景三：上下文切换
问题场景： 同时维护多个项目，频繁切换导致上下文混乱。
AGENTS.md 解决方案：
~/projects/
├─ project-a/AGENTS.md (Project A 的技术栈和规范)
├─ project-b/AGENTS.md (Project B 的技术栈和规范)
└─ project-c/AGENTS.md (Project C 的技术栈和规范)
效果：
- ✅ 项目切换时自动加载对应上下文
- ✅ 避免跨项目的技术栈混淆
- ✅ 每个项目保持独立的开发上下文
3.4 场景四：复杂功能开发
问题场景： 开发一个跨多个模块的复杂功能，需要保持整体设计的一致性。
AGENTS.md 解决方案：
# 在 AGENTS.md 中临时添加功能开发上下文
## 当前开发重点：用户认证系统
### 涉及模块
- `auth/` - 认证逻辑
- `api/middleware/` - JWT 验证中间件
- `frontend/components/` - 登录 UI
### 设计决策
- 使用 JWT 而非 Session（无状态需求）
- Token 有效期 24 小时
- Refresh Token 存储在 HttpOnly Cookie
### 待完成
- [ ] 密码重置流程
- [ ] 双因素认证（2FA）
功能完成后，可以将这些内容移到"重要决策"部分作为历史记录效果：
- ✅ 跨模块的一致性自动维护
- ✅ 设计决策可追溯
- ✅ 中断后可快速恢复进度
四、Codex CLI 斜杠命令
Codex CLI 提供了多个斜杠命令来辅助开发：
| 命令 | 功能 | 使用场景 |
|---|---|---|
/init | 生成 AGENTS.md 模板 | 项目初始化 |
/status | 显示会话配置和 token 使用 | 检查会话状态 |
/model | 选择活跃模型 | 切换 AI 模型 |
/compact | 总结对话以释放 token | 上下文过大时 |
/diff | 显示 Git diff | 查看代码变更 |
/mention | 将文件附加到对话 | 引入文件上下文 |
/new | 开始新对话 | 重置会话 |
/review | 审查工作树 | 代码审查 |
注意： Codex CLI 没有专门的记忆管理命令（如 /m_update、/m_drop、/m_view）。AGENTS.md 文件需要手动维护和更新。
五、设计哲学
5.1 简洁性原则
“AGENTS.md 会在每次会话开始时加载，因此必须保持简洁有效。”
- ❌ 错误做法：记录每日详细变更日志或临时任务清单
- ✅ 正确做法：只记录稳定的项目上下文、规范和重要决策
5.2 维护原则
“AGENTS.md 应该是项目文档的一部分，而不是独立的记忆系统。“
AGENTS.md 的定位：
├─ 不是：任务管理工具
├─ 不是：变更日志
├─ 不是：临时笔记
└─ 而是：项目上下文和规范的持久化存储
5.3 可演进原则
“AGENTS.md 应该随着项目发展而演进。”
- 初期：基本的项目描述和技术栈
- 中期：添加架构决策和编码规范
- 成熟期：累积设计决策和已知限制
六、与其他工具的对比
| 特性 | Codex CLI | Cline | Cursor |
|---|---|---|---|
| 上下文持久化 | ✅ AGENTS.md | ✅ memory-bank/ | ❌ 仅会话内 |
| 项目级记忆 | ✅ | ✅ | ❌ |
| 全局配置 | ✅ ~/.codex/ | ❌ | ❌ |
| 手动维护 | ✅ | ✅ | ❌ |
| 版本控制友好 | ✅ 单文件 | ✅ 多文件 | ❌ |
关键差异：
- Codex CLI：使用单一的 AGENTS.md 文件，简洁高效
- Cline：使用 memory-bank/ 目录，包含多个专门的文件（facts.md、preferences.md 等）
- Cursor：没有持久化记忆系统，每次会话都是全新的开始
七、实战建议
7.1 项目启动时
# 1. 在项目根目录运行
codex
> /init
# 2. 编辑生成的 AGENTS.md
# 填写项目描述、技术栈和编码规范
# 3. 将 AGENTS.md 加入版本控制
git add AGENTS.md
git commit -m "docs: 添加 Codex CLI 上下文文件"7.2 日常开发中
# 完成重要功能或架构决策后
# 手动编辑 AGENTS.md，添加相关记录
# 项目方向调整时
# 更新 AGENTS.md 中的相关内容，删除过时信息
# 定期维护
# 检查 AGENTS.md 是否仍然准确反映项目状态7.3 团队协作
# 将 AGENTS.md 加入版本控制
git add AGENTS.md
git commit -m "docs: 更新项目上下文和规范"
# 团队成员首次拉取
git pull
# Codex 将自动读取项目的 AGENTS.md
# 代码审查时
# 检查代码是否符合 AGENTS.md 中定义的规范7.4 最佳实践
- 保持简洁：AGENTS.md 应该控制在合理的长度，避免过于冗长
- 及时更新：重要架构决策和技术变更后及时更新
- 团队共识：编码规范和架构原则需要团队达成共识
- 版本控制：将 AGENTS.md 纳入 Git 管理，追踪变更历史
- 定期审查：定期检查 AGENTS.md 的准确性和完整性
八、总结
Codex CLI 通过 AGENTS.md 文件 实现了简洁有效的上下文持久化，解决了 AI 编程助手的”失忆”问题。它让 Codex 从一个”单次对话工具”转变为”长期开发伙伴”，特别适合：
- 🔄 长期项目：跨月、跨年的持续开发
- 👥 团队协作：多人共享编码偏好和架构决策
- 🔀 多项目切换：保持每个项目的独立上下文
- 📈 复杂功能：跨模块、跨文件的一致性维护
核心价值： 用单一的 Markdown 文件，实现 AI 上下文的持久化和共享化，让 AI 真正成为”有记忆”的开发伙伴。
与 Cline 等工具的区别： Codex CLI 采用更简洁的单文件方案，而 Cline 使用专门的多文件 memory-bank 系统。两者各有优势，选择取决于项目需求和个人偏好。