别急着写 Prompt：先让 Codex 读懂项目

这是 Codex 系列的第 4 篇。

前面几篇分别讲了三件事：Codex 的工程 Agent 心智、不同入口怎么选、第一次动手前如何处理目录、Git、权限和回滚。到这里，很多人会自然进入下一个问题：

那我应该怎么写一个好 Prompt？

但我现在更愿意把这个问题往前挪一步：

别急着写 Prompt，先让 Codex 读懂项目。

很多时候，Prompt 写不好只是表象。真正的问题是 Codex 还没有理解项目边界、目录结构、运行方式、已有约定和风险区域。你让它“优化页面”“修一下后台 bug”“整理一篇文章”，它不是不能做，而是会带着太多假设往前冲。

这一篇只解决一件事：把“直接让 Codex 开始改”改成“先让 Codex 形成项目地图，再让它实施”。

整理日期：2026-07-05。本文涉及 Codex 的上下文、Prompt、AGENTS.md 等能力，主要参考 OpenAI Codex 官方文档，并结合这个博客项目的实际使用经验整理。

这篇解决什么问题

读完这篇，你应该能带走三样东西：

这篇不会追求所谓万能提示词。我的目标更朴素：让你下次打开一个陌生仓库、一个旧项目、一个别人写的后台，或者自己很久没碰的博客时，知道先让 Codex 看什么、输出什么、问什么，再决定要不要动手。

1. 直接写 Prompt 为什么容易翻车

我以前也常这样开头：

帮我优化一下这个博客后台，分类选择有问题。

或者：

帮我把这篇文章整理得更好一点。

这种 Prompt 不一定错。对于很小的任务，它甚至足够。但一旦进入真实项目，问题会很快冒出来。

这类问题靠“写更长 Prompt”能缓解，但解决得不彻底。因为你仍然是在替 Codex 猜上下文。

更稳的做法是：先让 Codex 自己读项目，并且要求它把理解说出来。不是直接交差，而是先交一份“项目地图”。

2. 项目理解不是让它扫一遍 README

这里容易有一个误区：让 Codex 读项目，不等于把 README、package.json、几段报错全部贴进去。

读项目更像一次小型 onboarding。一个新同事加入项目，你不会只甩给他一个 README，然后第二分钟就让他改生产事故。你会希望他先回答这些问题：

Codex 的优势是它可以读文件、跑命令、看工具输出，也会在一个线程里保留已经做过的事情。官方文档里也强调：Codex 的输出质量会受任务上下文、验证方式、约束和完成标准影响；复杂或模糊任务，先计划会更稳。

我把这一步叫做“项目理解层”。

它的位置在 Prompt 和实施之间：

原始需求 -> 项目理解 -> 结构化任务 -> 实施 -> 验证 -> 沉淀规则

如果跳过项目理解，你的 Prompt 就要承担太多责任：既要描述需求，又要描述项目，又要描述验证方式，还要提醒风险。长到最后，连你自己也不想读。

3. 第一次只读：让 Codex 先画项目地图

真实项目里，我建议第一次给 Codex 的任务不要是“修改”，而是“只读理解”。

可以直接用这个模板：

请先只读项目，不要修改文件，不要安装依赖，不要运行删除、发布、部署、数据库迁移等有副作用的命令。

目标：
我想让你先理解这个项目，后续会让你完成一个具体任务。当前任务先不要实现，只输出项目理解报告。

范围：
- 当前工作目录是项目边界。
- 优先查看 README、package.json、锁文件、框架配置、路由/页面目录、内容目录、测试或构建配置。
- 如果发现多个可能的源代码目录，请先说明你的判断依据，不要直接假设。

请输出：
1. 项目一句话说明：这个项目大概是什么。
2. 技术栈判断：框架、语言、包管理器、构建方式、内容来源。
3. 目录地图：只列重要目录和它们的作用，不要把所有文件机械列出来。
4. 关键入口：页面入口、数据入口、配置入口、发布/部署相关入口。
5. 本任务可能相关的文件：按“为什么相关”说明证据。
6. 可用验证命令：test、lint、typecheck、build、preview 或手动验证方式。
7. 风险点：哪些文件/目录不应该轻易修改，哪些命令需要我确认。
8. 未知问题：你仍然不确定、需要我补充的信息。
9. 下一步建议：如果后续要实施，建议先做哪一步，变更范围多大。

输出要求：
- 用表格和短段落。
- 标注你的依据来自哪些文件或命令输出。
- 不要编造项目不存在的命令。

这个模板看起来长，但它比“帮我看看项目”可靠得多，因为它限制了三件事：

尤其是“不要编造项目不存在的命令”这一句很重要。很多 AI 工具会习惯性给出 npm test、npm run lint、pnpm build 这类命令，但项目里未必真的有。让它从 package.json、README、CI 配置、Makefile 或脚本目录里找证据，会少很多误导。

4. 项目理解报告应该长什么样

我希望 Codex 输出的不是一篇散文，而是一张可以继续工作的地图。

可以要求它按这个模板输出：

## 项目理解报告

### 一句话说明

...

### 技术栈判断

| 项目 | 判断 | 证据 | 备注 |
| --- | --- | --- | --- |
| 框架 |  |  |  |
| 语言 |  |  |  |
| 包管理器 |  |  |  |
| 内容来源 |  |  |  |
| 部署方式 |  |  |  |

### 目录地图

| 路径 | 作用 | 和当前任务的关系 |
| --- | --- | --- |
|  |  |  |

### 关键入口

| 类型 | 文件/目录 | 说明 |
| --- | --- | --- |
| 页面入口 |  |  |
| 数据入口 |  |  |
| 配置入口 |  |  |
| 样式入口 |  |  |
| 构建入口 |  |  |

### 验证方式

| 命令/方式 | 用途 | 是否已确认存在 |
| --- | --- | --- |
|  |  |  |

### 风险和不要碰的地方

| 风险 | 原因 | 建议 |
| --- | --- | --- |
|  |  |  |

### 仍不确定的问题

1. ...

### 下一步建议

...

这张表的核心不是漂亮，而是让你能审。

你可以快速看出：

• 它有没有把项目类型判断对。
• 它有没有找到真实入口。
• 它有没有把“可能相关文件”和“确定相关文件”混为一谈。
• 它有没有知道怎么验证。
• 它有没有主动暴露未知，而不是装懂。

如果 Codex 的项目理解报告本身就很虚，你不要急着让它改代码。先追问：

你刚才的判断哪些来自文件证据，哪些只是推测？请分开列出来。

或者：

请继续只读，重点确认内容发布链路：Markdown/MDX 文件从哪里读取，如何生成列表页，分类和标签在哪里定义。

这一步看起来慢，但通常比改错再回滚更快。

5. 读项目时应该重点看哪些文件

不同项目不一样，但我会让 Codex 优先看这些地方：

这里有个关键点：不要让 Codex 一上来全文扫描所有文件。

更好的顺序是：

先看项目入口和配置 -> 再看任务相关目录 -> 最后按证据扩展

比如这个博客项目里，如果问题是“后台分类下拉没有选项”，就不应该从所有文章逐篇看起，而应该先确认：

• 后台页面在哪里。
• 分类数据从哪里来。
• 分类是写死、从文章 frontmatter 聚合，还是来自数据库/API。
• 当前部署的源码和本地目录是不是同一个。
• 发布后 Cloudflare 实际访问的是哪个构建结果。

这些问题没确认之前，直接改 UI 组件很可能只是修了表象。

6. 让 Codex 区分事实、推测和问题

我现在特别喜欢在 Prompt 里加这一句：

请把事实、推测和需要确认的问题分开写。

原因很简单：Codex 很擅长补全上下文，但真实项目里，补全不等于事实。

可以让它这样输出：

这一步对技术笔记、投资笔记、AI 工具研究也有用。很多误判不是因为信息少，而是把“看起来像”当成了“就是”。

7. 从项目地图变成实施 Prompt

项目理解报告不是终点。它的作用是帮你写下一条真正可执行的 Prompt。

官方文档里推荐 Prompt 至少包含 Goal、Context、Constraints、Done when。我的理解是：项目理解报告就是在帮你补全后面三个部分。

可以这样转换：

举一个接近这个博客项目的例子。

原始需求可能是：

后台文章列表里分类下拉没有选项，操作有时候卡住，帮我看是不是有 bug。

不要直接把这句话扔给 Codex 开改。先让它只读项目，确认后台页面、分类来源、文章 frontmatter、构建/部署方式。等项目理解报告出来后，再写实施 Prompt：

目标：
修复后台文章列表的分类选择问题。当前现象是文章行里的分类下拉显示“未分类”，展开后没有可选分类；部分操作看起来会卡住或没有正确反馈。

上下文：
- 你已经只读检查过项目，并确认后台文章列表组件在 <文件路径>。
- 分类数据可能来自 <文件路径或函数>，文章 frontmatter 中存在 category 字段。
- 博客约定的分类包括：AI 与智能体、工程实践、金融投资、阅读笔记、个人随笔、工具与效率、项目记录。
- 发布链路是 <构建/部署方式>，本次只改源码，不直接发布。

约束：
- 不要改动已经发布的文章正文。
- 不要引入新的大型依赖。
- 保持现有 UI 风格，只修复数据来源、状态更新或跳转问题。
- 如果发现分类模型和后台 UI 设计不一致，先用最小改动修复，不做大重构。

完成标准：
- 分类下拉能显示受控分类列表。
- 选择分类后，当前文章的 category 能正确更新或保存。
- 不再因为选择分类导致页面卡住或错误跳转。
- 运行项目已有的 lint/build/test；如果没有自动测试，说明手动验证步骤。
- 最后输出修改文件、验证结果和剩余风险。

这里的 <文件路径>、<文件路径或函数>、<构建/部署方式> 不是让读者照抄的占位废话，而是提醒你：这些内容应该来自上一轮项目理解报告。没有被确认的上下文，不要急着写进实施 Prompt 里当成事实。

这个 Prompt 比“帮我修一下分类”长很多，但它没有废话。它把 Codex 刚才读出来的项目事实转换成了执行边界。

更重要的是，你和 Codex 对“完成”的理解开始一致。

8. 什么情况下需要继续追问，而不是实施

不是每份项目理解报告都可以直接进入 coding。

如果出现这些信号，我会继续让 Codex 只读或问问题：

我现在会把“继续追问”看成一种节省时间的动作。尤其是博客、后台、部署这类项目，很多 bug 不在当前文件，而在数据链路、发布链路或状态同步上。

9. 可以写进 AGENTS.md 的项目理解

项目理解不要只留在一次对话里。重复出现的内容，应该沉淀到 AGENTS.md。

比如这个博客项目，就适合把这些规则写进去：

## Blog Content Rules

- New blog posts live under `content/blog`.
- Use exactly one primary category.
- Prefer these categories: `AI 与智能体`, `工程实践`, `金融投资`, `阅读笔记`, `个人随笔`, `工具与效率`, `项目记录`.
- Keep AI tutorial posts in series `AI 工具实践`.
- Frontmatter should include title, date, updated, draft, summary, category, tags, and series.
- Do not use old imported/template categories unless the content genuinely belongs there.
- Before publishing, check title, summary, category, tags, links, assets, and draft status.

这类内容不应该每次靠 Prompt 重新说一遍。官方文档里也把 AGENTS.md 定位成给 Codex 的项目说明：它会在任务开始前被读取，适合放仓库布局、构建/测试命令、工程约定、不要做的事、完成标准等。

但 AGENTS.md 也不要写成百科全书。

我自己的判断是：

第 6 篇会专门讲 AGENTS.md，所以这里先不展开。你现在只需要记住一件事：一次项目理解里发现的稳定规则，最好不要浪费。

10. 不同入口下怎么做项目理解

这套方法不绑定某个入口。App、CLI、IDE、Cloud 都能做，只是上下文来源不同。

如果你不确定入口，第 2 篇的结论仍然适用：按任务闭环选入口。但无论哪个入口，第一步都可以是只读理解。

11. 什么时候不用这么重

不是所有任务都需要完整项目理解。

下面这些场景可以轻一点：

但如果任务满足下面任意一条，我建议完整走项目理解：

• 项目你不熟。
• Codex 第一次进入这个仓库。
• 改动会影响构建、部署、后台、数据、权限。
• 你不知道测试怎么跑。
• 你准备让 Codex 连续工作很多步。
• 你担心它改多。

这不是保守，而是在给后面的速度买保险。

12. 一个 30-60 分钟练习

你可以拿任意一个自己的项目做这个练习。

第一步：准备

先确认工作目录和 Git 状态：

git status --short
git branch --show-current

如果有未提交改动，先自己看一眼。不要在一堆未知改动上让 Codex 做项目理解，否则它会把用户改动、旧草稿、临时文件混在一起。

第二步：只读理解

把前面的“项目理解 Prompt”发给 Codex。要求它不改文件，只输出报告。

如果这份报告后面还会复用，可以临时保存成 PROJECT_MAP.md 或放到 docs/ 里的项目笔记。是否提交进仓库取决于团队习惯；个人项目里，我更倾向于先放草稿区，等内容稳定后再把长期规则整理进 AGENTS.md。

第三步：审报告

重点看四件事：

第四步：转成任务 Prompt

选一个小任务，比如：

• 修一个明确 bug。
• 更新一篇博客文章的分类和标签。
• 给一个页面补空状态。
• 给一个工具函数补测试。

让 Codex 基于项目理解报告写实施 Prompt。你自己审完再让它动手。

第五步：沉淀

如果项目理解报告里有长期有效的信息，就整理进 AGENTS.md：

• 常用命令。
• 内容规范。
• 不要碰的目录。
• 验收方式。
• 常见坑。

这一步才是真正拉开差距的地方。你不是只完成了一次任务，而是在让下一次任务更容易。

13. 我的收藏清单

如果你只想收藏最短版本，可以记这几条：

1. 第一次进项目，先只读，不改文件。
2. 让 Codex 输出项目地图，而不是泛泛总结。
3. 要求区分事实、推测和未知问题。
4. 验证命令必须来自项目证据，不要默认存在。
5. 实施 Prompt 至少写清 Goal、Context、Constraints、Done when。
6. 重复出现的项目规则，沉淀到 AGENTS.md。
7. 任务越模糊、仓库越陌生，越要先计划。

我觉得这篇是整个系列里最容易被低估的一篇。很多人会急着学 Prompt 模板、Skill、MCP、自动化，但如果 Codex 连项目都没读明白，后面的能力越强，越可能把错误放大。

先读懂项目，是把 Codex 从“会写代码的模型”变成“能进入现场的工程 Agent”的关键一步。

下一篇我会继续沿着这条线写：如何把项目地图变成一条真正可执行的 Codex Prompt。等单次任务说清楚之后，再单独聊 AGENTS.md，把那些每次都会重复的项目边界、命令、分类、验证和不要碰的地方沉淀下来。

资料来源

• OpenAI Codex Best practices
• OpenAI Codex Prompting
• OpenAI Codex AGENTS.md guide
• OpenAI Codex Manual
• CodexGuide 快速上手
• bozhouDev/codex-orange-book