这是 Codex 系列的第 4 篇。
前面几篇分别讲了三件事：Codex 的工程 Agent 心智、不同入口怎么选、第一次动手前如何处理目录、Git、权限和回滚。到这里，很多人会自然进入下一个问题：
那我应该怎么写一个好 Prompt？
但我现在更愿意把这个问题往前挪一步：
别急着写 Prompt，先让 Codex 读懂项目。
很多时候，Prompt 写不好只是表象。真正的问题是 Codex 还没有理解项目边界、目录结构、运行方式、已有约定和风险区域。你让它“优化页面”“修一下后台 bug”“整理一篇文章”，它不是不能做，而是会带着太多假设往前冲。
这一篇只解决一件事：把“直接让 Codex 开始改”改成“先让 Codex 形成项目地图，再让它实施”。
整理日期：2026-07-05。本文涉及 Codex 的上下文、Prompt、AGENTS.md 等能力，主要参考 OpenAI Codex 官方文档，并结合这个博客项目的实际使用经验整理。
这篇解决什么问题
读完这篇，你应该能带走三样东西：
| 产物 | 用来解决什么 |
|---|---|
| 项目理解 Prompt | 第一次接触项目时，让 Codex 只读扫描并输出结构化理解 |
| 项目理解报告模板 | 把目录、入口、风险、验证命令和未知问题固定下来 |
| 实施 Prompt 转换方法 | 把“项目地图”变成可执行任务，而不是靠感觉补上下文 |
这篇不会追求所谓万能提示词。我的目标更朴素：让你下次打开一个陌生仓库、一个旧项目、一个别人写的后台，或者自己很久没碰的博客时，知道先让 Codex 看什么、输出什么、问什么，再决定要不要动手。
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、后台登录信息 | 不适合 |
| 很长的产品背景和历史讨论 | 不适合，另放文档再引用 |
| 反复犯错后的纠正规则 | 适合 |
第 6 篇会专门讲 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”的关键一步。
下一篇我会继续沿着这条线写：如何把项目地图变成一条真正可执行的 Codex Prompt。等单次任务说清楚之后，再单独聊 AGENTS.md，把那些每次都会重复的项目边界、命令、分类、验证和不要碰的地方沉淀下来。