让 Codex 长期接手大型项目：把项目记忆放进 Git 仓库
要让 Codex 长期完成一个大型项目，核心不是把所有内容塞进同一个聊天，而是把项目规则、项目事实、当前进度、执行计划和验收标准全部放进 Git 仓库。
Codex 每次进入仓库后，先读取这些文件，就能在新线程中恢复项目状态。聊天只负责当次执行，仓库负责保存长期事实。
下面这套结构适合 Spring Boot / RuoYi + Vue + MySQL 这类大型管理系统项目，也适合大多数前后端分离项目。
一、推荐目录结构
snow-scenic-platform/
├── AGENTS.md # Codex 总规则，最重要
├── README.md # 给人看的项目说明
├── CHANGELOG.md # 版本和重要变更记录
├── Makefile # 统一开发、测试、构建命令
├── docker-compose.yml # 本地依赖环境
├── .env.example # 环境变量示例，不保存真实密码
├── .gitignore
│
├── .codex/
│ └── config.toml # 项目级 Codex 配置
│
├── .agent/
│ └── PLANS.md # 长任务执行计划的编写规范
│
├── .agents/
│ └── skills/ # 可重复执行的 Codex 工作流
│ ├── implement-feature/
│ │ └── SKILL.md
│ ├── fix-bug/
│ │ └── SKILL.md
│ ├── review-code/
│ │ └── SKILL.md
│ └── update-context/
│ └── SKILL.md
│
├── docs/
│ ├── index.md
│ ├── project/
│ │ ├── PROJECT.md # 项目目标、角色、范围
│ │ ├── SCOPE.md # 做什么、不做什么
│ │ ├── GLOSSARY.md # 项目术语
│ │ └── CODING-STANDARDS.md # 通用编码规范
│ ├── requirements/
│ │ ├── REQUIREMENTS.md
│ │ ├── auth-requirements.md
│ │ ├── ticket-requirements.md
│ │ ├── order-requirements.md
│ │ └── hotel-requirements.md
│ ├── architecture/
│ │ ├── ARCHITECTURE.md
│ │ ├── MODULES.md
│ │ ├── SECURITY.md
│ │ ├── ERROR-HANDLING.md
│ │ └── LOGGING.md
│ ├── decisions/
│ │ ├── ADR-001-modular-monolith.md
│ │ ├── ADR-002-jwt-auth.md
│ │ ├── ADR-003-flyway.md
│ │ └── ADR-004-redis-cache.md
│ ├── database/
│ │ ├── DATABASE.md
│ │ ├── ER-DIAGRAM.md
│ │ ├── TABLE-DICTIONARY.md
│ │ └── DATA-RULES.md
│ ├── api/
│ │ ├── API-CONVENTIONS.md
│ │ ├── openapi.yaml
│ │ ├── auth-api.md
│ │ ├── ticket-api.md
│ │ └── order-api.md
│ ├── plans/
│ │ ├── active/
│ │ │ └── order-create.md
│ │ ├── completed/
│ │ └── backlog/
│ ├── testing/
│ │ ├── TEST-STRATEGY.md
│ │ ├── ACCEPTANCE-CRITERIA.md
│ │ ├── TEST-CASES.md
│ │ └── TRACEABILITY.md
│ ├── operations/
│ │ ├── LOCAL-DEVELOPMENT.md
│ │ ├── DEPLOYMENT.md
│ │ ├── BACKUP-RESTORE.md
│ │ └── TROUBLESHOOTING.md
│ └── status/
│ ├── CURRENT_STATE.md # 当前项目状态，最重要
│ ├── TASKS.md # 当前任务清单
│ ├── KNOWN_ISSUES.md
│ └── SESSION_HANDOFF.md # 新线程接力摘要
│
├── backend/
│ ├── AGENTS.md # 后端专属 Codex 规则
│ ├── pom.xml
│ ├── README.md
│ └── src/
│
├── frontend/
│ ├── AGENTS.md # 前端专属 Codex 规则
│ ├── package.json
│ ├── vite.config.ts
│ ├── tsconfig.json
│ ├── README.md
│ └── src/
│
├── database/
│ ├── AGENTS.md # 数据库修改规则
│ ├── migrations/
│ ├── seed/
│ └── rollback/
│
├── tests/
├── scripts/
├── docker/
└── .github/
目录可以多，但真正让 Codex 能稳定接力的关键是四层：
AGENTS.md
docs/status/
.agent/PLANS.md
.agents/skills/
二、AGENTS.md：告诉 Codex 怎么工作
AGENTS.md 是 Codex 的项目级工作规则。官方文档建议把仓库结构、启动方式、构建测试命令、工程规范、禁止事项和完成条件写进去；同时保持简洁，把详细架构和任务说明放到其他文档中。
根目录可以这样写：
# Codex 项目规则
## 必读文件
开始任务前阅读：
- docs/project/PROJECT.md
- docs/architecture/ARCHITECTURE.md
- docs/status/CURRENT_STATE.md
- docs/status/TASKS.md
- 与当前任务相关的需求、API 和数据库文档
## 项目结构
- backend：Spring Boot 后端
- frontend：Vue 3 前端
- database：数据库迁移
- docs：项目事实和设计文档
- tests：跨模块测试
## 工作流程
1. 阅读任务相关文件。
2. 检查当前实现。
3. 对复杂任务创建 ExecPlan。
4. 列出影响文件。
5. 进行最小范围修改。
6. 编写或更新测试。
7. 执行验证命令。
8. 审查 git diff。
9. 更新项目状态文档。
## 禁止事项
- 不得擅自升级依赖。
- 不得删除已有正常功能。
- 不得直接修改已执行的数据库迁移。
- 不得把密码、Token、密钥提交到仓库。
- 不得进行与任务无关的重构。
- 不得声称未执行的测试已经通过。
- 不得修改 API 合同，除非任务明确要求。
## 复杂任务规则
复杂功能、跨模块修改和重大重构必须使用 .agent/PLANS.md 中定义的 ExecPlan。
计划保存到：
docs/plans/active/<任务名称>.md
## 完成标准
任务只有满足以下条件才能标记完成：
- 后端编译通过
- 后端测试通过
- 前端类型检查通过
- 前端构建通过
- 验收条件通过
- git diff 已审查
- CURRENT_STATE.md 已更新
- TASKS.md 已更新
Codex 会读取不同层级的 AGENTS.md。可以在根目录放通用规则，在 backend/、frontend/、database/ 放模块专属规则。越靠近当前工作目录的规则越具体，也越适合放模块约束。
三、docs/status：解决新上下文失忆
docs/status/ 是新线程接力的核心。这里不放长篇设计，只放当前有效状态。
CURRENT_STATE.md
# 当前项目状态
更新时间：2026-07-16
## 当前里程碑
订单模块。
## 已完成
- 登录注册
- JWT 认证
- 角色权限
- 门票分类
- 门票信息
- 订单查询
## 正在开发
创建订单功能。
## 当前实现
已有：
- OrderController
- OrderService
- OrderMapper
- Order 实体
- 订单主表
- 订单明细表
缺少：
- OrderCreateDTO
- 后端金额计算
- 库存原子扣减
- requestId 幂等处理
- 事务测试
## 下一步
按照 docs/plans/active/order-create.md 实现订单创建。
## 当前验证状态
- 后端编译：通过
- 后端测试：通过
- 前端构建：通过
- 订单创建：尚未实现
TASKS.md
# 当前任务
## ORDER-001 创建订单
- [x] 确认业务需求
- [x] 确认数据库字段
- [ ] 创建 OrderCreateDTO
- [ ] 实现服务端金额计算
- [ ] 实现库存原子扣减
- [ ] 增加事务
- [ ] 增加 requestId 幂等控制
- [ ] 编写单元测试
- [ ] 编写接口测试
- [ ] 更新 API 文档
## 暂不处理
- 微信支付
- 自动退款
- 分布式事务
- 微服务拆分
SESSION_HANDOFF.md
每次准备开启新 Codex 线程前，更新接力摘要：
# Codex 线程接力
## 当前任务
实现创建门票订单。
## 必读文件
- AGENTS.md
- docs/status/CURRENT_STATE.md
- docs/status/TASKS.md
- docs/requirements/order-requirements.md
- docs/api/order-api.md
- docs/plans/active/order-create.md
## 允许修改
- backend/src/main/java/com/example/scenic/order/
- backend/src/test/java/com/example/scenic/order/
- docs/status/
- docs/api/order-api.md
## 禁止修改
- 认证模块
- 公共返回结构
- 已执行的数据库迁移
- 前端模块
## 当前风险
- 并发库存超卖
- 重复订单
- 前端伪造价格
- 事务不完整
新线程只需要告诉 Codex：
阅读 AGENTS.md 和 docs/status/SESSION_HANDOFF.md，继续完成当前任务。
不用复制旧聊天。
四、PLANS.md：控制复杂任务
复杂、耗时或跨模块任务，不应该直接开写。更稳的做法是让 Codex 先维护一个活的执行计划。
推荐结构：
.agent/
└── PLANS.md
docs/plans/
├── active/
│ └── order-create.md
├── completed/
└── backlog/
.agent/PLANS.md 定义“计划应该怎么写”。docs/plans/active/order-create.md 是某个具体任务的计划。
示例：
# ExecPlan：创建门票订单
## 目标
实现创建门票订单，并保证金额可信、库存安全和请求幂等。
## 当前情况
订单查询已经完成，但订单创建尚未实现。
## 业务规则
1. 价格必须从数据库读取。
2. 门票必须处于上架状态。
3. 库存不足时创建失败。
4. 相同 requestId 不能重复创建。
5. 订单写入和库存扣减必须处于同一事务。
## 允许修改
- order 模块
- ticket 模块的库存扣减方法
- 对应测试
- 订单 API 文档
## 禁止修改
- 登录认证
- 公共 Result
- 已执行数据库迁移
- 支付功能
## 实施步骤
- [ ] 分析已有订单代码
- [ ] 创建 OrderCreateDTO
- [ ] 实现门票查询和状态校验
- [ ] 实现金额计算
- [ ] 实现库存条件更新
- [ ] 实现订单写入事务
- [ ] 实现 requestId 幂等处理
- [ ] 编写正常流程测试
- [ ] 编写库存不足测试
- [ ] 编写重复请求测试
- [ ] 执行全部验证
- [ ] 更新状态文档
## 验收标准
- 正常请求只生成一条订单。
- 金额与数据库价格一致。
- 库存不足不写入订单。
- 相同 requestId 不产生重复数据。
- 异常时订单和库存全部回滚。
## 验证命令
```bash
cd backend
mvn clean test
mvn package
```
## 执行记录
由 Codex 在实施过程中持续更新。
这样计划不是一次性文档，而是任务执行过程中的控制台账。
五、Skills：把重复提示词变成工作流
如果某些提示词反复使用，就不要每次复制粘贴。把它们放进 .agents/skills/。
.agents/skills/
├── implement-feature/SKILL.md
├── fix-bug/SKILL.md
├── review-code/SKILL.md
└── update-context/SKILL.md
例如 update-context/SKILL.md：
---
name: update-project-context
description: 在完成功能、修复缺陷或准备切换 Codex 线程时，更新项目状态和接力文档。
---
执行以下操作：
1. 阅读 git diff。
2. 确认实际完成的功能。
3. 更新 docs/status/CURRENT_STATE.md。
4. 更新 docs/status/TASKS.md。
5. 更新 docs/status/SESSION_HANDOFF.md。
6. 如产生架构决策，创建或更新 ADR。
7. 不得把未验证内容标记为完成。
8. 写明实际运行的验证命令及结果。
9. 删除已经失效的临时说明。
10. 保持文档简短，只保留当前有效状态。
以后可以直接让 Codex：
使用 update-project-context skill 更新项目上下文。
官方文档中，Skills 适合承载可重复的工作流、领域规则、脚本和参考资料。它比在每次聊天里写一大段提示词更稳定，也更容易团队共享。
六、后端、前端、数据库各自放 AGENTS.md
backend/AGENTS.md
# 后端开发规则
## 技术栈
- JDK 17
- Spring Boot 3.x
- MyBatis-Plus
- MySQL 8
- Maven
## 分层规则
- Controller 负责接收参数和返回结果。
- Service 负责业务逻辑。
- Mapper 负责数据库访问。
- Entity 不直接作为新增和修改请求参数。
- 新增和修改使用 DTO。
- 接口响应使用 VO。
- Controller 不得直接调用 Mapper。
## 验证命令
修改 Java 代码后必须执行：
```bash
mvn test
mvn package
```
## 禁止事项
- 不得跳过参数校验。
- 不得相信前端传入的金额、权限和用户身份。
- 不得在 Controller 中编写事务逻辑。
- 不得通过捕获异常后返回成功来隐藏错误。
frontend/AGENTS.md
# 前端开发规则
## 技术栈
- Vue 3
- TypeScript
- Vite
- Element Plus
- Pinia
- Axios
## 规则
- API 请求集中存放在 src/api。
- TypeScript 类型集中存放在 src/types。
- 页面不得直接硬编码后端地址。
- 接口字段必须符合 docs/api/openapi.yaml。
- 不得擅自修改后端接口字段。
- 页面必须处理加载、空数据和错误状态。
## 验证命令
```bash
pnpm lint
pnpm type-check
pnpm test
pnpm build
```
database/AGENTS.md
# 数据库修改规则
- 所有结构变化必须创建新的迁移文件。
- 已执行的迁移文件不得修改。
- 金额使用 decimal。
- 时间使用 datetime。
- 密码不得保存明文。
- 新增索引必须说明查询场景。
- 删除表和删除字段必须人工确认。
- 数据库变化必须同步更新 TABLE-DICTIONARY.md。
局部规则比一个巨大的根目录 AGENTS.md 更容易维护。根目录写通用原则，模块目录写局部约束。
七、.codex/config.toml 放运行配置
.codex/config.toml 负责 Codex 怎么运行，AGENTS.md 负责 Codex 在这个项目中怎么工作。不要把二者混在一起。
项目配置可以保持简单：
approval_policy = "on-request"
sandbox_mode = "workspace-write"
更适合个人的配置，例如模型、推理强度、个人 MCP 配置，建议放在：
~/.codex/config.toml
项目专属配置放在：
.codex/config.toml
Codex 的项目配置只有在项目被信任时才会加载，这一点也要注意。
八、信息优先级
大型项目最怕“聊天里说过”和“代码实际情况”互相打架。建议把优先级写进根目录 AGENTS.md：
实际代码和测试
↓
API 与数据库合同
↓
架构决策 ADR
↓
CURRENT_STATE.md
↓
当前 ExecPlan
↓
聊天内容
发生冲突时：
- 已通过测试的代码行为优先。
- 明确批准的接口和数据库合同优先。
- ADR 中已确定的架构决定优先。
- 当前状态文档优先于旧计划。
- 当前计划优先于临时聊天讨论。
- 聊天总结不能覆盖实际仓库状态。
这条规则很重要。它能避免 Codex 把旧聊天里的废弃方案重新当成事实。
九、Codex 的实际工作流程
采用这套目录后，每个任务按下面的流程运行：
读取根 AGENTS.md
↓
读取模块 AGENTS.md
↓
读取 CURRENT_STATE.md
↓
读取 TASKS.md
↓
读取需求/API/数据库文档
↓
复杂任务创建 ExecPlan
↓
修改少量相关代码
↓
运行测试和构建
↓
审查 git diff
↓
更新 CURRENT_STATE.md
↓
更新 TASKS.md
↓
计划移入 completed
↓
Git 提交
Codex 不是靠记住某个聊天来持续工作，而是靠每次进入仓库后读取当前事实。
十、先采用精简版
刚开始不需要一下创建几十个文件。最低可用结构如下：
project/
├── AGENTS.md
├── README.md
├── .codex/
│ └── config.toml
├── .agent/
│ └── PLANS.md
├── docs/
│ ├── PROJECT.md
│ ├── ARCHITECTURE.md
│ ├── DATABASE.md
│ ├── API.md
│ ├── DECISIONS.md
│ ├── CURRENT_STATE.md
│ ├── TASKS.md
│ └── plans/
│ ├── active/
│ └── completed/
├── backend/
│ ├── AGENTS.md
│ ├── pom.xml
│ └── src/
├── frontend/
│ ├── AGENTS.md
│ ├── package.json
│ └── src/
├── database/
│ ├── AGENTS.md
│ └── migrations/
├── tests/
└── scripts/
└── verify.sh
先维护好这几个文件：
AGENTS.md
docs/PROJECT.md
docs/CURRENT_STATE.md
docs/TASKS.md
docs/DECISIONS.md
.agent/PLANS.md
已经足以解决大部分“对话太长、新线程难以接续”的问题。
最关键的一条规则
根目录的 AGENTS.md 中必须明确要求：
每次完成任务后，Codex 必须更新：
1. docs/CURRENT_STATE.md
2. docs/TASKS.md
3. 当前 ExecPlan
4. 相关 API 或数据库文档
这样 Codex 的记忆不再依赖某个聊天线程，而是依赖仓库。
即使换电脑、换线程、换模型，只要打开同一个 Git 仓库，Codex 就可以继续开发。