自动摘要
正在生成中……
适用环境： ChatGPT Chat、Codex 桌面端或 CLI、macOS / Linux / Windows
迁移方式： Markdown 知识文档 + AGENTS.md + Codex 项目交接
目标： 让 Codex 继承过去在 ChatGPT 中讨论的项目需求、架构设计、技术决策和开发计划，而无需导入完整聊天记录。
一、背景与原理
在使用 AI 辅助开发时，经常会遇到这样的情况：
一个软件项目最初在 ChatGPT 的普通聊天中讨论，经过多轮交流，逐渐确定了需求、技术栈、整体架构及实现方案。
当项目进入编码阶段，开发工作转移到 Codex 本地代码仓库。
但问题来了：
Codex 并不能自动获得之前 ChatGPT 聊天中的全部项目知识。
即使两个产品使用同一个 OpenAI 账号，它们也没有一个可以直接把指定 Chat 会话完整继承为本地 Codex 项目上下文的一键功能。
最实用的解决方式，是将聊天知识转化为可持续维护的 Markdown 文档。
整体流程如下：
ChatGPT 旧聊天
↓ 提炼历史项目知识
PROJECT_CONTEXT.md + DECISIONS.md
↓ 保存到本地 Git 仓库
AGENTS.md 指导 Codex 阅读
↓ Codex 检查真实代码
HANDOFF.md 记录项目当前状态
↓ 开始后续开发
这套方案不使用 ChatGPT Work，也不依赖 MCP、数据库或第三方同步服务。
二、设计项目知识库
建议在现有代码仓库中增加以下结构：
my-project/
├── AGENTS.md
├── README.md
├── src/
├── package.json
└── docs/
└── ai-context/
├── PROJECT_CONTEXT.md
├── DECISIONS.md
└── HANDOFF.md
每个文件都有独立职责。
1. PROJECT_CONTEXT.md：项目背景与需求
用于回答：
- 这个项目为什么存在？
- 目标用户是谁？
- 需要实现哪些功能？
- 整体技术架构是什么？
- 有哪些功能、性能、部署及兼容性约束？
- 还有哪些需求没有确定？
这份文档主要来自 ChatGPT 的历史讨论。
2. DECISIONS.md：架构决策记录
用于保存技术决策及其原因。
例如：
# Architecture Decisions
## ADR-001: 使用 Cloudflare Workers
Status: Confirmed
### Decision
使用 Cloudflare Workers 作为后端运行环境。
### Reasons
- 减少服务器维护成本
- 满足边缘部署需求
- 与现有 Cloudflare 服务集成
### Alternatives
- 自建 Node.js 服务器
- VPS + Docker
### Notes
该决策来自历史设计讨论，
不代表当前代码已经完成部署。
其中状态可分为：
- Confirmed：已经确认
- Proposed：仍是提议
- Rejected：明确否决
- Superseded：已被后续决策取代
要特别保留“为什么这样决定”，而不是仅记录最终采用了什么技术。
3. HANDOFF.md：开发交接与状态
用于记录：
- 当前 Git 分支和提交
- 实际已实现功能
- 尚未完成的功能
- 历史设计与当前实现的差异
- 已验证的问题与测试结果
- 下一阶段开发任务
此文件应由 Codex 检查当前代码仓库后创建，不应该由不了解实际代码状态的旧 Chat 直接生成。
4. AGENTS.md：Codex 工作指令
用于告诉 Codex：
- 历史知识存放在哪里
- 哪些任务需要阅读哪些文档
- 历史设计和实际代码发生冲突时如何处理
- 何时更新项目文档
与其他三个文件不同，AGENTS.md 是 Codex 能自动发现并加载的项目指令文件。
三、从 ChatGPT 旧聊天提取项目知识
这是整个迁移过程最重要的一步。
步骤 1：打开原始聊天
进入 ChatGPT，找到此前讨论项目架构、需求及开发方案的旧聊天。
建议直接在原来的聊天末尾进行提炼，因为该会话通常保留了最多的相关上下文。
步骤 2：发送知识提取提示词
复制以下提示词，在旧 Chat 中发送：
提示词 A：生成项目知识文档
你现在需要将本次 ChatGPT 会话中关于代码项目的
历史讨论，整理为可迁移到 Codex 本地 Git 仓库的
项目知识文档。
请尽可能利用当前可访问的对话上下文。
不要声称已经读取实际上不可见的历史消息。
生成两份独立的 Markdown 文档。
【文件一：PROJECT_CONTEXT.md】
包括：
1. 项目背景与最终目标
2. 目标用户和实际使用场景
3. 功能需求及其优先级
4. 系统架构与模块关系
5. 技术栈、API、数据结构及重要约束
6. 非功能性要求：性能、安全、兼容性、部署
7. 已讨论但尚未解决的技术问题
8. 明确排除或暂不考虑的功能
9. 重要设计变更及其原因
【文件二：DECISIONS.md】
逐条记录历史技术决策：
- 决策编号及标题
- 状态：Confirmed / Proposed / Rejected / Superseded
- 最终结论或当前提议
- 采用或拒绝的原因
- 曾考虑的替代方案
- 相关技术约束及风险
- 能确认时记录原聊天的依据
重要要求：
1. 以最后明确确认的决策为准。
2. 区分用户决定与 AI 尚未被接受的建议。
3. 不要把开发计划当作已经实现的功能。
4. 不要臆测当前 Git 仓库中的代码状态。
5. 不要补充历史聊天中不存在的技术决策。
6. 无法确定的事实标记为“待验证”。
7. 保留重要设计决策背后的原因。
8. 删除无关闲聊、重复内容及敏感信息。
9. 当不同阶段的讨论存在冲突时，说明变化过程。
10. 优先提供能够指导后续开发的事实信息。
分别输出两份完整的 Markdown 内容，
标明对应文件名，方便保存到本地项目。
步骤 3：人工审核结果
重点检查三个问题：
是否混淆了建议与决定？
例如 ChatGPT 曾建议使用 PostgreSQL，但用户最后选择 SQLite，最终文档应保留 SQLite 这一结论。
是否把计划误认为实现？
例如讨论过“未来支持 OAuth”，不代表当前代码已经具备 OAuth。
是否遗漏了后期变更？
如果最初计划使用 Docker，后来明确改为 Cloudflare Workers，应体现最终决策及变更原因。
需要注意，特别长的历史聊天可能并非全部处于当前可访问的上下文中。因此，重要方案应与原始记录核对。
四、在 Mac 本地项目中保存文档
打开 macOS 终端，进入现有代码项目：
cd /path/to/my-project
创建知识文档目录：
mkdir -p docs/ai-context
创建两份文件：
touch docs/ai-context/PROJECT_CONTEXT.md
touch docs/ai-context/DECISIONS.md
把旧 Chat 生成的 Markdown 内容分别粘贴进去。
可以用 VS Code、Cursor 或其他文本编辑器完成。
这时不要急着生成 HANDOFF.md，因为需要先让 Codex 验证实际项目状态。
五、配置 AGENTS.md
在项目根目录创建 AGENTS.md。
如果已有该文件，保留既有指令，仅合并以下配置。
推荐 AGENTS.md 模板：
# Project Instructions
## Language
- Always respond to the user in Simplified Chinese.
- Keep code, APIs, commands and identifiers
in their original language.
## Project Knowledge
Historical project discussions were migrated
from ChatGPT into this repository.
Reference documents:
- docs/ai-context/PROJECT_CONTEXT.md
Project goals, requirements and architecture.
- docs/ai-context/DECISIONS.md
Historical decisions and rejected alternatives.
- docs/ai-context/HANDOFF.md
Verified implementation status and pending tasks.
## Context Usage
- For requirement or architecture tasks,
consult PROJECT_CONTEXT.md.
- Before revisiting major technical choices,
consult DECISIONS.md.
- When resuming development or planning milestones,
consult HANDOFF.md.
- For small isolated changes,
read only relevant documents.
## Source of Truth
- Current code, configuration and tests take
precedence over historical implementation claims.
- Historical documents describe design intent,
not necessarily current implementation.
- Never assume a feature is implemented merely
because it appears in historical context.
- Identify conflicts between documentation and code.
- Never invent missing requirements or decisions.
## Development Workflow
- Inspect relevant code before making changes.
- Respect existing architecture where appropriate.
- Run relevant tests after modifications.
- Avoid unrelated changes.
- Do not deploy without authorization.
## Documentation Maintenance
- Update DECISIONS.md when significant
architectural decisions are confirmed or changed.
- Update HANDOFF.md after meaningful milestones.
- Record verification evidence and outstanding issues.
- Do not rewrite PROJECT_CONTEXT.md for
routine implementation work.
- Never record secrets or credentials.
为什么不把整个项目说明写进 AGENTS.md？
因为 Codex 会自动发现适用的 AGENTS.md，其中的文字会占用模型上下文。
如果将几十页技术讨论全部放进去，每次使用 Codex 都可能消耗不必要的上下文空间。
更合理的做法是：
AGENTS.md 保持精简，其他文档按需读取。
这样既能长期保留知识，也不会因为文档持续增长而使每次任务都变得沉重。
六、让 Codex 正式接手项目
完成文件准备后，打开 Codex 桌面端，选择本地项目。
也可以在项目目录启动 Codex CLI：
cd /path/to/my-project
codex
建议开启一个新的 Codex 会话，使新增的 AGENTS.md 生效。
第一次交接提示词
复制以下内容发送给 Codex：
请正式接手当前代码项目。
该项目此前在 ChatGPT Chat 中讨论过，
相关项目知识已经迁移至：
docs/ai-context/
请完成以下工作：
第一阶段：理解历史设计
1. 阅读 PROJECT_CONTEXT.md。
2. 阅读 DECISIONS.md。
3. 总结项目目标、技术架构及关键约束。
第二阶段：检查真实项目
1. 检查当前代码仓库结构。
2. 检查主要源代码、依赖与配置。
3. 检查 Git 状态及近期提交记录。
4. 对照历史设计验证现有实现。
5. 找出设计与实现之间的冲突。
第三阶段：生成交接文档
请创建：
docs/ai-context/HANDOFF.md
至少包含：
- 当前 Git 分支与提交
- 已实现功能及代码证据
- 部分实现的功能
- 尚未实现的功能
- 历史设计与代码之间的差异
- 已知问题与风险
- 测试及验证结果
- 下一阶段任务和优先级
注意：
1. 以实际仓库为实现状态依据。
2. 不要将历史计划当作已完成功能。
3. 不要臆造不存在的代码或测试结果。
4. 记录尚未完成验证的事项。
5. 本阶段只允许创建或修改 HANDOFF.md。
6. 不要修改业务代码、依赖或运行部署操作。
完成后，用简体中文报告：
- 项目当前真实状态
- 最重要的架构差异
- 尚待确认的问题
- 下一步最值得优先完成的三个任务
交接完成后应得到什么？
Codex 应生成类似下面的文档：
# Development Handoff
## Last Verified
- Date:
- Git branch:
- Commit:
## Implemented Features
- [x] Feature A
Evidence: src/feature-a.ts
## Partially Implemented
- [ ] Feature B
Missing: ...
## Pending Features
- [ ] Feature C
## Architecture Mismatches
### Mismatch 1
Historical design:
...
Current implementation:
...
Recommended resolution:
...
## Known Issues
- ...
## Verification
- Tests executed:
- Results:
- Not verified:
## Next Milestones
1. ...
2. ...
3. ...
至此，Codex 就具备了两类互补的知识：
历史知识： 项目当初为什么这样设计。
当前知识： 项目实际已经实现到什么程度。
两者结合，才算完成了真正的开发交接。
七、如何检查 Codex 是否正确读取知识
在新的 Codex 会话中输入：
请确认当前项目的 AGENTS.md 是否生效。
列出你能够识别的项目知识文档，
并解释以下文件的不同用途：
1. PROJECT_CONTEXT.md
2. DECISIONS.md
3. HANDOFF.md
请实际读取所需文档，
列出项目的三个主要技术决策。
如果文件不存在或内容无法读取，
请明确说明，不要猜测。
如果 Codex 能列出三个文档的真实内容，并准确说明历史决策，说明知识迁移已经可以工作。
但要注意：仅仅能够说出文档名称，不代表它已经实际读取了文档。应该通过具体内容验证。
八、日常开发时如何维护
知识库不是一次性资料，而是长期维护的项目资产。
普通功能修改
例如修复按钮、调整 API、修改 UI。
让 Codex 检查对应代码即可，不需要每次重新读取完整项目历史。
新的架构决策
例如原先选择 Redis，后来决定改用 Cloudflare KV。
应当：
- 在 DECISIONS.md 中新增或更新决策记录。
- 标记旧决策已被取代。
- 说明变更原因及影响范围。
完成重要开发阶段
例如完成用户认证、数据库迁移或部署方案调整。
要求 Codex 更新 HANDOFF.md，记录实际完成内容、验证证据和剩余工作。
又在 ChatGPT 中讨论了新方案
如果以后继续使用普通 Chat 讨论项目需求，不必重新生成整个知识库。
可以让 ChatGPT 根据新讨论输出一份增量变更说明，再让 Codex 核对仓库、合并到对应文档。
例如：
请将本次聊天中新确认的项目需求和
技术决策整理为增量更新内容。
以便 Codex 合并到现有：
- PROJECT_CONTEXT.md
- DECISIONS.md
只提取新变化，不要重新生成全部历史内容。
区分已确认决策和未确认建议。
九、Git 版本管理与安全
建议将四个 Markdown 文档纳入 Git。
git add AGENTS.md docs/ai-context/
git commit -m "docs: migrate historical project context"
这样项目知识也可以随着 Git 进行版本管理，后续能追溯某项技术决策什么时候发生变化。
不过需要注意：
- 不要保存 API Key、密码、Token 等凭据。
- 不要把私人聊天中的敏感内容直接提交到公开仓库。
- 不要让 AGENTS.md 包含与项目无关的大量规则。
- 不要让 Codex 在未经审核的情况下覆盖已经确认的设计文档。
- 若仓库已有未提交的修改，应先检查 Git 状态，避免把不相关文件一并提交。
如果项目有多人协作，应统一约定由谁审核重要的架构决策，避免 AI 在不同会话中反复修改已确认的方案。
十、常见问题
Q1：以后新开 Codex 会话，需要重新迁移吗？
不需要。
只要项目文件仍在仓库中，Codex 就可以继续使用这些知识文件。
不过每次新会话并不会天然恢复之前所有临时对话内容，所以重要事实应记录在仓库文档里。
Q2：把 PROJECT_CONTEXT.md 写进 AGENTS.md，Codex 就会自动阅读吗？
不一定。
Codex 可以自动加载 AGENTS.md 中的适用指令，但普通 Markdown 文档通常要由模型根据任务需要主动读取。
所以要在 AGENTS.md 中明确规定读取条件。
Q3：为什么不直接导入完整聊天记录？
完整聊天往往包含大量探索性讨论、重复提问、被否决的方案和过时的信息。
将这些内容全部输入 Codex，可能增加上下文成本，还可能造成设计理解混乱。
对代码开发来说，经过筛选的项目知识通常更有价值。
Q4：如果 ChatGPT 旧聊天非常长怎么办？
可以分阶段整理需求、架构和技术决策，也可以使用 ChatGPT 的数据导出功能获得原始聊天记录。
但最终仍建议提炼成结构化 Markdown，而不是让 Codex 每次阅读全部原文。
Q5：需要 MCP 或自动同步服务吗？
初期不需要。
只有当你管理多个大型项目，并且经常需要在 ChatGPT 与 Codex 之间双向传递更新时，才值得考虑专门的知识同步工具。
十一、最终检查清单
迁移前：
- 已找到对应的 ChatGPT 历史聊天。
- 已生成 PROJECT_CONTEXT.md。
- 已生成 DECISIONS.md。
- 已检查重大决策和技术细节。
迁移时：
- 已创建 docs/ai-context/ 目录。
- 已将两个文档保存到本地仓库。
- 已创建或更新 AGENTS.md。
- 已在 Codex 中开启新的项目会话。
迁移后：
- Codex 能够准确理解历史项目目标。
- Codex 已检查真实代码和 Git 状态。
- 已生成 HANDOFF.md。
- 已识别未完成任务和设计冲突。
- 已确认文档没有敏感凭据。
- 已将知识文件提交到 Git。
十二、总结
本方案的核心思想是：
不要让 Codex 机械地记住每一轮旧聊天，而是让它继承经过整理、可以验证和持续维护的项目知识。
四个文件分别承担不同角色：
| 文件 | 主要作用 |
| ------------------ | ------------------ |
| AGENTS.md | 告诉 Codex 如何工作 |
| PROJECT_CONTEXT.md | 告诉 Codex 项目想实现什么 |
| DECISIONS.md | 告诉 Codex 为什么这样设计 |
| HANDOFF.md | 告诉 Codex 当前实际做到哪一步 |
通过这套结构，即使未来更换 Codex 模型、开启新会话，或者将项目迁移到另一台计算机，关键项目知识仍然可以伴随代码仓库长期保存。
最终形成的工作方式是：ChatGPT 负责需求与方案讨论，Markdown 保存项目知识，Codex 负责代码实现、验证与进度维护，Git 负责版本追踪。
官方参考资料
这份教程的具体文件结构和提示词属于推荐实践，并非 OpenAI 强制规定的标准；其中的 AGENTS.md 机制和精简上下文原则参考了以下官方资料：