Import to Codex：把现有项目带入 Codex 前要准备什么

适用场景

这篇手册适合准备把一个已有项目交给 Codex 维护的用户。导入不是“把仓库丢给 Codex 就结束”，而是要让 Codex 能理解结构、运行命令、验证结果和安全边界。

OpenAI 官方 Import to Codex 页面介绍了相关入口。具体导入方式以当前官方页面和产品界面为准。

步骤 1：先整理项目入口

导入前先确认项目根目录清楚。

建议检查：

• package.json、pyproject.toml、Cargo.toml 等依赖入口。
• README 是否说明项目用途。
• 测试、lint、build 命令是否可运行。
• 内容目录或源码目录是否清晰。
• 是否有未提交的重要改动。

如果项目本身很乱，Codex 会花更多时间猜测。

步骤 2：补一份 AGENTS.md

AGENTS.md 是给 Codex 的项目说明。

建议包含：

# AGENTS.md

## 项目定位

## 内容或代码目录

## 开发命令

## 验证要求

## 禁止事项

对内容站，可以写：

- 手册文章放在 content/manual。
- 每篇文章必须包含 source 和 status。
- 没有官方截图时不要使用概念图或生成图。

步骤 3：明确验证命令

不要让 Codex 猜项目怎么验证。

示例：

## 验证

- 修改 TypeScript 或路由后运行 `npm run build`。
- 修改 UI 后运行 `npm run lint`。
- 只改 MDX 时检查 frontmatter。

验证越明确，Codex 越容易闭环。

步骤 4：处理敏感文件

导入前检查：

• .env 是否被 Git 忽略。
• token 是否写入文档。
• 本地数据库是否在项目里。
• 日志是否包含客户数据。
• 截图是否包含账号或密钥。

敏感文件不要交给 Codex 作为普通上下文。

步骤 5：先做只读任务

第一次导入后，先让 Codex 只读分析。

请阅读项目结构，总结技术栈、内容目录、验证命令和风险边界。
不要修改文件。

确认它理解项目后，再交给它做修改。

常见错误

不要在项目结构不清时直接要求大范围重构。

不要省略验证命令。

不要把密钥或客户数据提交进仓库。

不要把临时任务写进 AGENTS.md。

小结

导入 Codex 前应整理项目入口、补 AGENTS.md、写清验证命令、处理敏感文件，并先用只读任务确认 Codex 理解项目。准备越好，后续协作越稳。