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

这是 Codex 系列的第 4 篇。

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

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

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

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

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

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

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

这篇解决什么问题

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

产物	用来解决什么
项目理解 Prompt	第一次接触项目时，让 Codex 只读扫描并输出结构化理解
项目理解报告模板	把目录、入口、风险、验证命令和未知问题固定下来
实施 Prompt 转换方法	把“项目地图”变成可执行任务，而不是靠感觉补上下文

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

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

我以前也常这样开头：

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

或者：

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

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

常见翻车点	表面现象	背后的原因
改错目录	Codex 看起来做了很多，但不是你要发布的源代码	项目源代码、草稿目录、部署产物没有区分
误解框架	它按常见 Next.js / Astro / Vite 习惯写，但项目并不这么组织	没有先读配置、路由和内容加载方式
验证缺失	它说“已完成”，但你一打开页面还是不对	没有提前确认 test、lint、build、预览或手动验收方式
改动过大	为了一个小 bug 顺手重构多个文件	没有约束变更范围和风险边界
忽略已有改动	你本地的草稿、用户改动、未提交文件被混在一起	没有先看 Git 状态和文件归属
语义不一致	分类、标签、系列名越改越乱	没有项目层面的内容规则和信息架构

这类问题靠“写更长 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 优先看这些地方：

类型	常见文件/目录	看什么
项目说明	README.md、docs/、AGENTS.md	项目目标、约定、开发方式
包管理	package.json、pnpm-lock.yaml、yarn.lock、package-lock.json	脚本、依赖、包管理器
框架配置	next.config.*、astro.config.*、vite.config.*、nuxt.config.*	框架入口、构建设置
语言配置	tsconfig.json、eslint.config.*、biome.json	类型、lint、格式化规则
路由页面	app/、pages/、src/routes/、src/app/	页面组织和数据流
内容目录	content/、posts/、data/、public/	文章、图片、静态资源
测试配置	vitest.config.*、jest.config.*、playwright.config.*	测试入口和验收能力
部署配置	wrangler.toml、vercel.json、netlify.toml、.github/workflows/	发布链路和 CI

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

更好的顺序是：

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

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

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

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

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

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

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

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

可以让它这样输出：

类型	例子	怎么处理
事实	package.json 里有 build 脚本	可以作为后续验证依据
推测	看起来像 Next.js 项目，但还没确认路由入口	需要继续读配置或目录
问题	分类数据源不明确，需要确认 API 或数据文件	先问用户或继续只读调查

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

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

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

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

可以这样转换：

实施 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 只读或问问题：

信号	说明	下一步
找不到真实源代码	本地目录可能只是草稿、构建产物或镜像	先确认仓库来源和部署链路
验证命令不存在	Codex 给不出可靠验收方式	先补手动验证步骤，必要时加最小测试
相关文件太多	它把半个项目都列为相关	要求收敛到调用链和证据
风险点为空	真实项目通常都有风险，空白反而可疑	让它专门做一次风险扫描
推测很多	技术栈、数据来源、入口都不确定	继续读配置或请用户补充
任务目标不稳定	用户自己还没决定要修 bug、改设计还是重构	先让 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 也不要写成百科全书。

我自己的判断是：

内容	是否适合写进 AGENTS.md
每次都要遵守的项目分类、命令、目录规则	适合
某篇文章的一次性写作要求	不适合，放当前 Prompt
密码、token、后台登录信息	不适合
很长的产品背景和历史讨论	不适合，另放文档再引用
反复犯错后的纠正规则	适合

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

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

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

入口	推荐做法	注意点
Codex App	打开项目目录，先发“只读项目理解 Prompt”	注意当前选择的是 Local、Worktree 还是 Cloud
Codex CLI	在项目根目录执行，要求先 rg --files、看配置和脚本	权限模式要收住，第一次不要全权限乱跑
IDE Extension	用打开文件和 @file 辅助定位，再要求它补项目地图	不要只靠当前选区理解整个项目
Web / Cloud	从 GitHub 仓库任务开始，让它先读 README、CI、配置和目标 issue	不能依赖你本机未提交文件，除非明确同步

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

11. 什么时候不用这么重

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

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

场景	可以怎么简化
单文件解释	直接给文件，让 Codex 解释结构和关键逻辑
小范围样式修改	给目标组件、截图和验收标准即可
明确报错修复	给复现步骤、错误日志、相关文件和期望结果
已熟悉项目里的重复任务	依赖 AGENTS.md 和已有工作流，不必每次重扫

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

• 项目你不熟。
• 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”的关键一步。

下一篇我会继续沿着这条线写：如何写一个真正有用的 AGENTS.md。不是放一堆口号，而是让 Codex 每次进入项目时，都能自动知道项目边界、命令、分类、验证和不要碰的地方。

资料来源

• OpenAI Codex Best practices
• OpenAI Codex Prompting
• OpenAI Codex AGENTS.md guide
• OpenAI Codex Manual
• CodexGuide 学习路线
• bozhouDev/codex-orange-book