read-project

这一篇是你真正开始把 Codex 用到项目里的第一步。

注意：本篇只让 Codex 阅读项目，不让它修改文件，不让它运行会改变文件的命令。用户第一次使用 Codex 时，最重要的不是马上改代码，而是确认 3 件事：

2. Codex 能读懂项目结构。

3. Codex 能把不确定的地方说清楚，而不是乱猜。

> 前置教程：国内大模型配置方案

> 如果你还没有确认 Codex 背后使用哪个模型、API Key 放在哪里、配置完成后如何只读验证，先完成前置教程，再回到本篇。

> 依据来源：OpenAI Codex 官方手册中关于 CLI、最佳实践、提示词、审批与沙箱的说明。

跟着本篇做完后，你应该能做到：

2. 启动 Codex CLI。

3. 发出一条只读项目分析任务。

4. 让 Codex 输出项目地图。

5. 判断 Codex 的分析是不是靠谱。

6. 让 Codex 检查 Git 状态并解释有没有文件变化。

7. 得到下一篇“第一次改代码”需要用的任务候选。

本篇不做这些事情：

不让 Codex 修改代码。
不让 Codex 安装依赖。
不让 Codex 运行构建。
不让 Codex 提交 Git。
不在本篇临时配置大模型。
不处理复杂项目重构。

这些都放到后面的教程里。

你需要已经准备好：

Windows 命令提示符（cmd）。
Git。
Node.js 和 npm。
已安装并登录 Codex CLI。
一个练习项目。

如果你跟着前面的教程走，推荐项目是：


D:\code\codex-demo


如果你用的是 C 盘，则可能是：


C:\code\codex-demo


点击开始菜单，搜索：

cmd


打开命令提示符。
不要双击某个脚本文件，也不要从压缩包里打开项目。
如果你的项目在 D 盘，运行：


cd D:\code\codex-demo


如果你的项目在 C 盘，运行：


cd C:\code\codex-demo


然后确认当前路径：

cd


预期结果应该显示你的项目目录。
示例：


Path
----
D:\code\codex-demo

如果你看到的不是项目目录，不要继续。先重新 cd 到正确目录。


确认当前目录没错后，启动 Codex：


codex


进入 Codex 后，先不要随便输入“帮我看看”“帮我优化一下”。
第一次任务要写得非常明确：

只读。
不修改文件。
不运行会改变文件的命令。
输出固定格式。
不确定就说不确定。

把下面这段完整复制给 Codex：


请只读分析当前项目。
重要限制：


不要修改任何文件。
2. 不要创建任何文件。
3. 不要删除任何文件。
4. 可以运行只读检查命令，例如查看目录、查看 Git 状态、列出 package.json scripts。
5. 不要运行会改变文件、安装依赖、构建、测试或提交 Git 的命令。
6. 如果你需要更多信息，请先说明你想查看什么，不要猜。

请按下面结构输出：
1. 当前目录判断

当前项目路径：
这是不是项目根目录：
你的判断依据：
当前 Git 状态是否干净：

2. 项目技术栈

前端技术：
后端技术：
构建工具：
包管理工具：
其他明显依赖：

3. 关键文件和目录

入口文件：
配置文件：
源码目录：
静态资源目录：
构建输出目录：
测试目录：

4. package.json 或构建配置
如果有 package.json，请列出 scripts。
如果是 Maven 项目，请说明 pom.xml 里能看出的信息。
如果都没有，请说明你没有找到。
5. 可以安全查看的命令
请列出你刚才实际使用过或建议使用的 3 到 5 个只读命令，并说明每个命令为什么安全。
6. 新手下一步低风险任务
请推荐 3 个适合第一次让 Codex 修改的小任务。
每个任务都要包含：

任务内容
可能涉及的文件
为什么风险低
怎么验证

7. 不确定的地方
请明确列出你不能确定的地方。
不能确定就写“不确定”，不要编。


第 5 步：等待 Codex 输出项目地图
Section titled “第 5 步：等待 Codex 输出项目地图”
Codex 可能会读取项目文件，然后输出分析结果。
你不要在它还没完成时继续追问。等它输出完成后，再看下面几项。
你应该重点看：


它写的当前路径对不对。
它判断项目根目录的依据对不对。

它有没有找到 package.json 或 pom.xml。


它有没有列出 scripts。
它有没有说明 Git 状态是否干净。
它有没有写“不确定的地方”。


先看 Codex 输出里的这一段：


1. 当前目录判断


你要确认：

当前路径和你刚才 pwd 看到的一样。


2. 它说这是项目根目录时，有依据。

3. 依据来自真实文件，比如 package.json、src、pom.xml、.git。



如果 Codex 只说“看起来像”，但没有依据，你可以继续问：


你刚才判断这是项目根目录, 请列出具体依据。依据必须来自你看到的文件或目录，不要只给结论。


如果是 Vite 项目，Codex 可能会说：


前端技术：Vite。
包管理工具：npm。

配置文件：package.json、vite.config.js。


如果是 Vue 项目，可能还会看到：


Vue。

src/main.js 或 src/main.ts。


如果是 Spring Boot 项目，可能会看到：


Java。
Maven。

pom.xml。

src/main/java。


你要注意：Codex 说的技术栈必须能从文件里看出来。
如果它说了你项目里不存在的技术，比如明明没有 Java，却说是 Spring Boot，继续追问：


你提到了 Spring Boot。请说明你是根据哪个文件判断的。如果没有明确依据，请修正你的判断。

如果项目里有 package.json，Codex 应该能列出 scripts。


常见示例：


dev
build
preview
test
lint


如果 Codex 没有列出 scripts，你不要自己急着去敲命令，可以继续让 Codex 补充：


请只读查看当前项目可用脚本，并用中文解释每个脚本大概做什么。不要安装依赖，不要运行构建，不要修改文件。


注意：本篇不要求运行安装、构建或测试。下一篇之后才会逐步学习让 Codex 运行检查。
第 9 步：让 Codex 确认没有改文件
Section titled “第 9 步：让 Codex 确认没有改文件”
继续在 Codex 里发送：


请检查当前 Git 状态，确认本次只读分析有没有产生文件变化。
要求：


可以运行只读的 git status。
2. 只解释结果，不要修改文件。
3. 如果工作区噪音较多，请列出变化文件，并说明我下一步应该先做什么。



你希望 Codex 告诉你：

工作区干净；或者
哪些文件有变化；以及
这些变化是否和本篇任务有关。

先不要提交，也不要立刻回滚。
继续问 Codex：


我刚才要求你只读分析项目，但现在 Git 状态显示有文件变化。
请只解释：


哪些文件发生变化。
2. 这些变化可能来自哪里。
3. 是否可能是你刚才造成的。
4. 我现在应该先截图、查看 diff，还是暂停处理。

不要继续修改任何文件。


情况 1：Codex 说找不到项目文件
Section titled “情况 1：Codex 说找不到项目文件”
优先检查你是不是在项目根目录。
你可以让 Codex 先解释它看到的路径 and 目录依据。如果当前目录不对，退出 Codex，重新打开正确项目后再启动。
情况 2：Codex 一直想运行会改变项目的命令
Section titled “情况 2：Codex 一直想运行会改变项目的命令”
你可以回复：


这篇教程只允许只读分析。请不要运行任何命令，只根据已经能读取到的文件说明项目结构。如果信息不足，请列出你缺少什么。


情况 3：Codex 推荐的第一个任务太大
Section titled “情况 3：Codex 推荐的第一个任务太大”
比如它推荐：


重构整个页面结构


这对第一次改代码来说太大了。
你可以要求它缩小：


这些任务对第一次练习太大了。请重新推荐 3 个只涉及 1 个文件、可以用 git diff 检查、失败后容易回滚的小任务。


情况 4：Codex 的输出太抽象
Section titled “情况 4：Codex 的输出太抽象”
比如它只说：


这是一个现代前端项目。


这不够。
你可以追问：


请把你的判断写具体。每个结论都要列出对应文件依据，例如 package.json、vite.config.js、src/main.js。


本篇不要求你创建文件，但你可以把 Codex 的输出复制到临时笔记里。
推荐保存 these 内容：

项目技术栈。
入口文件。
scripts 命令。
低风险任务候选。
不确定事项。

后面“第一次让 Codex 改代码”会用到这些信息。
做到这里，如果满足下面 7 条，就说明你已经跑通了第一次“先读项目”的流程：


你能进入正确项目目录。
2. 你能在项目目录里启动 Codex。
3. Codex 能输出当前目录判断。
4. Codex 能列出项目技术栈和关键文件。
5. Codex 能列出它使用过或建议使用的安全只读检查。
6. Codex 能推荐 3 个低风险修改任务。
7. Codex 已经帮你检查并解释：本篇没有产生文件改动，或已经说明异常变化。

你学会的是 Codex 使用里最重要的第一条习惯：


先读项目，再改代码。

你也学会了让 Codex 按固定格式输出，而不是让它随意发挥。

这会直接影响后面所有实战教程的成功率。

下一篇看：第一次让 Codex 改代码。

那一篇会从本篇推荐的低风险任务里选一个，正式让 Codex 修改文件，并教你怎么检查 diff 和回滚风险。