在 Codex 系列第一篇（上篇），我们用一个很小的本地脚本，跑通了 Codex CLI 的基本流程：进入项目目录，启动 Codex，然后让它读文件、写代码、跑命令。
在这第二篇「让 Codex 读懂项目」，我们来让 Codex 先读懂一个开源项目，看它是做什么的，代码放在哪里，测试放在哪里，如果要改一点东西，应该从哪里开始看。
Typer 是什么
这次我们选的开源项目叫 Typer。它是一个 Python 命令行工具开发框架。如果你写了一个 Python 函数，Typer 可以帮你把它变成一个可以在终端里运行的命令行工具。
比如你写了这样一个函数：
def main(name: str):
print(f"Hello {name}")
Typer 可以帮你把它变成类似这样的终端命令：
python3 main.py Q
此外，它还能自动生成 --help、参数说明、错误提示和命令补全。如果我们想把平时写的小脚本整理成更正式的 CLI 工具，Typer 是一个很适合入门的项目。
Type 地址：github.com/fastapi/typer
Typer 很适合今天这篇文章。我们用 Codex CLI，去读一个 CLI 框架项目，逻辑就很顺。
先把项目下载下来
先找一个你平时放代码的目录，然后执行下面这几行命令：
mkdir -p ~/codex-practice
cd ~/codex-practice
git clone https://github.com/fastapi/typer.git
cd typer
上面的 git clone 就是把 Typer 这个开源项目下载到本地。执行完之后，我们已经进入了 typer 这个项目目录。
可以先看一眼当前目录里有什么：
ls
如果想看得更清楚一点，也可以执行：
find . -maxdepth 2 -type d | sort | head -40
这行命令会列出当前项目里前两层目录。我们不需要马上看懂每一个目录，只要先知道：这是一个真实项目，里面有源码、文档、测试、配置文件。
启动 Codex
接下来，在 typer 目录里启动 Codex：
codex
这里有一个关键点，就是在 typer 这个项目目录里启动 Codex。
普通网页聊天，我们要把代码、报错、目录结构复制给 AI；而在 Codex CLI 里启动它，就可以直接围绕本地项目目录工作。我们在哪个目录里启动 Codex，它就会优先把这个目录当作当前项目。
类似的逻辑在 Codex App 里也存在，只是入口从“在哪个目录启动命令”变成了“在 App 里选择哪个项目文件夹”。无论是 CLI、App，还是 IDE 插件，关键点都一样：先把 Codex 放到正确的项目上下文里，再让它读代码、解释结构、执行任务。
Codex 启动之后，我们先不要让它改代码，只让它读项目。来，把下面这段提示词复制给 Codex：
先不要修改任何文件。
请你阅读当前这个项目，然后用适合新手的方式回答：
1. 这个项目是做什么的？
2. 它主要解决什么问题？
3. 项目里最重要的几个目录分别是干什么的？
4. 源码大概放在哪里？
5. 测试大概放在哪里？
6. 文档大概放在哪里？
回答时请尽量引用具体文件路径。
这一步的目的很简单：先让 Codex 给我们画一张项目地图。
我们第一次打开一个新项目，容易卡在不知道从哪里看起。Codex 这一步做的事情，就是先帮我们把项目拆开：哪些文件是入口，哪些目录是源码，哪些地方是测试，哪些地方是文档。
Codex 解释项目
上面 Codex 读了 README 给我们介绍 Typer，它是一个 Python 库，用来快速构建命令行工具，也就是 CLI 应用。
如果你觉得它讲得还是有点偏工程，可以继续追问一次：
请你再用更通俗的方式解释 Typer。
假设读者只会写一点 Python 脚本，但没写过 CLI 工具。请你说明：
1. CLI 工具是什么？
2. Typer 能把普通 Python 脚本变成什么？
3. 为什么它会用到 Python 类型标注？
4. 用户执行 --help 时，Typer 大概帮我们做了什么？
5. 请用一个非常小的例子解释。
现在你大概清楚 Typer 是怎么样的一个项目。我们开始今天的主菜，让 Codex 带我们读这个项目，添加一个测试和小修改。
Codex 找项目入口
在知道 Typer 是做什么的之后，我们的下一步是找入口。继续给 Codex 输入：
现在请你继续阅读项目。
我想知道：如果我要理解 Typer 的核心代码，应该从哪些文件开始看？
请你按下面格式回答：
- 第一个应该看的文件：
- 这个文件解决什么问题：
- 它和其他文件有什么关系：
最多列 5 个文件，不要列太多。
还是不要修改任何文件。
这里故意加了一句“最多列 5 个文件”。对刚接触一个项目的人来说，Codex 一口气列出十几个文件，信息量反而会太大。先控制在少量关键文件里，我们更容易看清项目入口，也更容易跟着它继续往下读。
读项目的时候，我们不用一开始就理解所有东西。比较稳妥的方式是：先知道最值得看的几个文件，然后一层一层往下追。
这一步里，Codex 建议先看 typer/__init__.py。这个文件是 Typer 对外暴露 API 的入口，用户平时写 import typer 后能用到的 typer.Typer、typer.Option、typer.Argument、typer.run 等，基本都是从这里暴露出来的。
接着是 typer/main.py。它是核心主流程，负责处理 typer.Typer()、@app.command()、typer.run() 这些常见用法，并把 Python 函数转换成命令行命令。然后是 typer/params.py，它定义了 typer.Option() 和 typer.Argument()，也就是告诉 Typer：这个函数参数在 CLI 里应该表现成选项，还是位置参数。
再往下，Codex 推荐看 typer/models.py。这个文件主要保存 Typer 内部用到的数据结构，比如命令信息、参数信息、默认值、文件类型、上下文对象等。最后是 typer/core.py，它负责更底层的命令行行为，比如命令执行、参数展示、帮助信息和错误格式化，也会和底层的 Click 兼容代码配合。
这样一来，Typer 的核心代码就有了一条比较清楚的阅读路线：先看对外入口，再看主流程，然后看参数定义和内部数据结构，最后再进入底层命令行为。
Codex 解读项目运行原理
现在，我们来加点难度，让 Codex 追一条更具体的路线：当用户写了一个 Typer 应用，并在终端里运行它时，代码大概会经过哪些关键步骤。通过这条路线，我们可以进一步理解 Typer 是如何把一个普通 Python 函数变成命令行工具的。继续输入：
请你帮我追一条使用路线。
假设用户写了一个最简单的 Typer 应用，然后在终端里运行：
python main.py --help
请你结合当前项目代码解释：
1. 用户执行命令后，Typer 大概接管了哪些事情？
2. 参数和 --help 信息大概由哪些模块处理？
3. 测试里有没有类似场景？
4. 如果我要理解 --help 是怎么生成的，应该看哪些文件？
请用新手能看懂的方式解释。
不要修改任何文件。
上面这段话，就是本文的核心：
README 告诉我们项目对外怎么介绍自己；
源码告诉我们功能怎么实现；
测试告诉我们项目希望哪些行为保持稳定；
把这三块连起来，我们才算真的开始理解项目。对 Typer 来说，--help 是一个很适合入门的观察点。因为命令行工具最常见的用户入口之一，就是输入 --help 看参数说明。让 Codex 从这个入口往里追，会比抽象地问“请解释源码”更容易得到有用回答。
给 Codex 加一份项目 AGENTS.md
到这里，细心的你可能留意到一件事，前面的每一步项目讲解，我们都在提醒 Codex：
先不要改代码
回答要引用文件路径
解释要适合新手
不要一次列太多文件
修改前先说明计划
像是这种重复性需求，如果每次都人肉提醒，会有点麻烦。这个时候，我们需要用下 AGENTS.md。
AGENTS.md 是一份写给 Codex 的项目说明。我们可以把项目里的协作规则写进去，让 Codex 以后进入这个项目时先读这份说明。
如何写第一份 AGENTS.md
我们先退出当前 Codex 会话。按 Ctrl + C，或者在 Codex 里输入退出命令。
然后在终端里确认自己还在 typer 项目目录：
pwd
现在，我们来创建一份 AGENTS.md。在终端里输入下面命令：
nano AGENTS.md
执行后，终端会打开一个文本编辑界面。把下面这段内容复制进去：
# AGENTS.md
## 阅读项目时
- 先阅读 README.md、pyproject.toml、docs/ 和 tests/。
- 回答项目结构问题时，请引用具体文件路径。
- 面向新手解释时，少用术语，多说“这个文件解决什么问题”。
- 一次最多列 5 个关键文件，避免信息过载。
## 修改代码时
- 修改前先说明计划。
- 优先做小范围改动。
- 不要一次性重构多个模块。
- 修改后说明改了哪些文件，以及建议运行什么命令验证。
## 本文实践要求
- 这次主要目标是读懂项目。
- 除非我明确要求，否则不要修改源码。
复制粘贴完成后，按下面的顺序执行命令来保存刚才的修改：
Ctrl + O 保存
Enter 确认文件名
Ctrl + X 退出 nano
回到终端后，可以输入命令查看我们文件是否保存成功：
cat AGENTS.md
如果终端里能看到刚才写入的内容，就说明 AGENTS.md 已经创建好了。
现在重新启动 Codex。在当前目录（typer）下执行命令：
codex
进入 Codex 后，先问它：
请你先告诉我：你现在能看到哪些项目说明或规则？
如果你读取到了 AGENTS.md，请总结里面最重要的规则。
不要修改任何文件。
这一步是为了确认：Codex 已经知道这个项目里的协作规则。
AGENTS.md 的神奇之处
有了 AGENTS.md 之后，我们再让 Codex 做一次类似的项目阅读任务：
请你根据当前项目和 AGENTS.md 的规则，重新整理一份项目地图。
请按下面结构回答：
1. 这个项目一句话介绍
2. 新手最先应该看的 3 个文件或目录
3. 源码、测试、文档分别在哪里
4. 如果要理解 --help 功能，推荐阅读路线是什么
5. 这个项目里哪些地方暂时不建议新手一开始就深入
不要修改任何文件。
这一次，Codex 的回答应该会更符合我们的要求：路径更明确，解释更偏新手，一次列出的文件也不会太多。
这就是 AGENTS.md 的价值。它不是让 Codex 变聪明的魔法文件，但它可以把我们反复强调的规则固定下来。之后每次进入这个项目，我们就不用重复说一大段前置要求。
如何做测试
我们读项目不能只看源码，测试也很重要。下面我们来看个测试用例，请继续输入：
请你在 tests/ 目录里找一个适合新手理解的测试用例。
要求：
1. 只选一个测试文件
2. 解释这个测试文件在验证什么
3. 选其中一个测试函数，逐行解释它的大概意思
4. 说明这个测试和 Typer 的用户使用体验有什么关系
不要修改任何文件。
这个方式对新手很友好。源码一开始可能会比较绕，但测试通常更接近真实使用场景：用户输入什么命令，程序应该返回什么结果。通过测试，我们可以反过来理解项目的行为。
这一步里，Codex 建议先看 tests/test_cli/test_help.py。这个测试文件主要验证 Typer 生成的 --help 信息是否正常。对 CLI 工具来说，--help 往往是用户第一次接触程序时看到的入口，所以它的显示结果、排版、命令列表、错误信息都很重要。
Codex 还选了其中一个测试函数 test_short_help 来解释。这个测试会创建一个简单的 Typer 应用，注册几个命令，然后模拟用户运行 --help。接着，它会检查命令是否执行成功、帮助信息里是否出现了对应命令，以及过长的帮助文本是否被正确截断。
这样看测试，就不只是看“代码有没有通过”，也能看到 Typer 在保证什么用户体验：帮助信息要能正常显示，命令列表要清楚，长文本不能把终端输出搞乱。对我们读项目来说，这些测试其实就是理解项目行为的一条捷径。
如何上手一个项目
到这里，本文的主题「如何让 Codex 帮我们读懂一个项目」已经完成了：我们让 Codex 读了项目、讲了项目、追深度的运行原理讲解、读测试，还加了一份 AGENTS.md。
作为小彩蛋，我们来让 Codex 做一个轻量级的任务。毕竟我们是新手友好的实践教程，不会一上来就要求 Codex 直接改核心源码，可以先让它只提出修改方案。像是这样，终端输入：
现在请你不要真的修改文件。
请你基于刚才阅读的测试文件，提出一个适合新手练习的小改动。
要求：
1. 改动范围尽量小
2. 最好只涉及一个测试文件
3. 不改核心源码
4. 说明为什么这个改动适合练习
5. 给出你预计会修改的文件路径
6. 给出修改后应该运行的测试命令
Codex 建议在 tests/test_cli/test_help.py 里新增一个测试函数，用来验证命令的 docstring 会不会出现在 --help 输出里。这个改动范围很小，只涉及一个测试文件，也不需要碰 Typer 的核心源码。
这个建议挺适合作为第一次练习。它延续了前面读过的 --help 逻辑：先创建一个简单的 Typer 应用，再注册一个命令，然后模拟用户运行 hello --help，最后检查输出里是否包含对应的帮助文本。
重要的是，Codex 还给出了修改后的验证命令：
pytest tests/test_cli/test_help.py -k command_docstring_help
如果只想跑整个相关测试文件，也可以运行：
pytest tests/test_cli/test_help.py
这一步能看到 Codex 读项目之后的一个完整小闭环：先理解测试文件，再提出小范围改动，再说明会改哪里，最后给出验证方式。对于第一次让 Codex 进入开源项目来说，这样的任务比直接改核心源码更稳。
看得出，这个小任务风险很低，我们现在来让它给我们跑下新增测试用例的任务。
在开始让它修改代码之前，我们先来执行下下面的命令，确保当前仓库是干净的：
git status
里可以看到，除了刚刚新增的 AGENTS.md 之外，项目源码本身还没有被修改。这样后面 Codex 如果改了测试文件，我们就能比较清楚地看到这次新增了哪些变化。
下面，我们让 Codex 来执行下这个命令：
可以按你刚才的方案修改。
要求：
1. 修改前再确认一次文件路径
2. 只做这个小改动
3. 修改后告诉我改了什么
4. 如果能运行测试，请运行相关测试
5. 如果测试跑不起来，请先判断是环境问题、依赖问题，还是代码问题
Codex 报错了，因为我本地的 Python 环境是支持 Python3 不支持 Python 的，所以这里我们给 Codex 上个临时补丁：
这里测试没有继续跑下去，原因也比较明确：当前 python3 环境里没有安装 pytest。也就是说，这一步卡在本地依赖环境上，暂时不能说明刚才新增的测试用例有问题。
这次我们先不继续展开环境配置。对本文来说，重点已经达到了：Codex 完成了一个小范围测试改动，并在验证失败时给出了问题判断，没有继续盲目修改代码。
实践小结
这次用 Codex 读 Typer，最重要的一点是：面对一个新项目，第一步先别急着让它写代码。比较稳妥的做法，是先让 Codex 读目录、找入口、解释核心文件，再沿着一个具体功能追下去，最后通过测试理解项目如何验证行为。
这样做的好处是，我们能一步一步看见 Codex 在读什么、怎么理解、准备从哪里下手。它不只是帮我们补几行代码，也可以先变成一个项目阅读助手，帮我们把不熟悉的仓库整理成一张能跟着走的地图。
第一篇，我们让 Codex CLI 跑起来，完成了一个小工具；这一篇，我们把它放进开源项目里，让它先学会读项目。下一篇，我想继续聊 Codex 里的 slash commands：除了直接聊天，我们还可以用这些快捷命令查看状态、切换模式、管理上下文，更主动地控制一次 Codex 会话。
