在 Codex 系列第一篇上篇我们用一个很小的本地脚本跑通了 Codex CLI 的基本流程进入项目目录启动 Codex然后让它读文件、写代码、跑命令。在这第二篇「让 Codex 读懂项目」我们来让 Codex 先读懂一个开源项目看它是做什么的代码放在哪里测试放在哪里如果要改一点东西应该从哪里开始看。Typer 是什么这次我们选的开源项目叫 Typer。它是一个 Python 命令行工具开发框架。如果你写了一个 Python 函数Typer 可以帮你把它变成一个可以在终端里运行的命令行工具。比如你写了这样一个函数def main(name: str): print(fHello {name})Typer 可以帮你把它变成类似这样的终端命令python3 main.py Q此外它还能自动生成--help、参数说明、错误提示和命令补全。如果我们想把平时写的小脚本整理成更正式的 CLI 工具Typer 是一个很适合入门的项目。Type 地址github.com/fastapi/typerTyper 很适合今天这篇文章。我们用 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目录里启动 Codexcodex这里有一个关键点就是在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 会话。