Codex 实践系列 Vol.03：用 AGENTS.md 让 Codex 读懂 Typer 源码

1. 为什么 Codex 读 Typer 源码总是「差一口气」如果你最近在用 Codex 读开源项目大概率遇到过这种场景把 Typer 仓库克隆到本地在项目根目录启动 Codex问它「命令注册逻辑在哪」它给你一段听起来很顺、但一对照源码就发现路径对不上的回答。不是 Codex 不行而是它缺少一份「项目级说明书」。Typer 这个项目特别适合拿来练手。它是 FastAPI 作者做的 Python CLI 框架核心卖点是把带类型标注的普通函数直接变成命令行工具自动生成--help、参数校验和补全。项目地址在 github.com/fastapi/typer源码、测试、文档分层清晰但目录一多Codex 默认只会扫到 README 和少量入口文件对typer/main.py、typer/core.py、typer/params.py之间的调用关系经常讲得含糊。我试过直接问「Typer 怎么把函数变成命令」Codex 会泛泛谈 Click 封装却说不清app.command()装饰器在哪个文件里落地、Typer类实例化后命令是怎么挂上去的。问题根源在于Codex 每次会话都是「冷启动」它不知道你希望它先读哪些文件、回答时要不要引用路径、一次列几个文件合适。这些偏好如果每次靠人肉提醒效率极低。解决办法就是 AGENTS.md。这份文件放在项目根目录Codex 进入项目时会优先读取相当于给它一份「进项目先看这个」的协作约定。本文就围绕 Typer 源码阅读场景交付一份可复制的 AGENTS.md 骨架、Codex 配置片段以及验证 Codex 是否真的读懂命令注册逻辑的操作步骤。适合已经会用 Codex CLI、想把它从「聊天玩具」变成「项目助手」的 Python 开发者。2. 前置准备把 Typer 放进 Codex 的工作目录在写 AGENTS.md 之前得先让 Codex 站在正确的项目上下文里。Codex CLI 的逻辑是你在哪个目录启动它它就把那个目录当当前项目。所以第一步不是打开 Codex而是先把 Typer 拉下来。找一个你平时放代码的目录执行下面几行mkdir -p ~/codex-practice cd ~/codex-practice git clone https://github.com/fastapi/typer.git cd typer克隆完成后先看一眼目录结构心里有个底find . -maxdepth 2 -type d | sort | head -40你会看到typer/源码、tests/测试、docs/文档、scripts/等目录。这一步不用看懂每个目录只要确认「这是一个真实项目源码和测试是分开的」。接下来是模型接入。Codex CLI 需要配置一个可用的模型端点我这边用的是 TaoToken 的 API它兼容 OpenAI 风格的接口配置起来比较直接。先到控制台拿一个 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite拿到 Key 之后在终端里设置环境变量以 OpenAI 兼容方式为例export OPENAI_API_KEY你的_TaoToken_API_Key export OPENAI_BASE_URLhttps://taotoken.net/api如果你用的是 Codex CLI 的配置文件方式可以在~/.codex/config.toml里写model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key OPENAI_API_KEY配置完成后在typer目录里启动 Codexcodex这里有个关键点一定要在typer目录里启动。如果你在~/codex-practice启动Codex 会把整个练习目录当项目读到的就是typer/子目录路径引用会多一层前缀后面写 AGENTS.md 时容易对不上。3. 可复制的 AGENTS.md 骨架与 Codex 配置现在进入正题。AGENTS.md 的本质是一份写给 Codex 的项目说明它不参与代码运行但会影响 Codex 每次进入项目时的行为。下面这份骨架是我在 Typer 项目里实测下来比较稳的版本你可以直接复制。在typer目录下创建文件nano AGENTS.md把下面内容粘进去# AGENTS.md ## 项目背景 - 这是 Typer一个基于 Python 类型标注构建 CLI 的框架。 - 核心依赖 Click源码在 typer/ 目录测试在 tests/ 目录。 ## 阅读项目时 - 先阅读 README.md、pyproject.toml、docs/ 和 tests/。 - 回答项目结构问题时必须引用具体文件路径。 - 面向新手解释时少用术语多说「这个文件解决什么问题」。 - 一次最多列 5 个关键文件避免信息过载。 ## 修改代码时 - 修改前先说明计划。 - 优先做小范围改动不要一次性重构多个模块。 - 修改后说明改了哪些文件以及建议运行什么命令验证。 ## 本次实践要求 - 主要目标是读懂项目尤其是命令注册逻辑。 - 除非我明确要求否则不要修改源码。 - 解释 --help 生成流程时请指向 typer/main.py 和 typer/core.py。保存退出CtrlO保存Enter确认CtrlX退出然后确认文件写进去了cat AGENTS.md这份骨架有三个设计点值得说明。第一「一次最多列 5 个关键文件」是硬约束Codex 默认喜欢一口气列十几个文件对新手反而是噪音。第二「必须引用具体文件路径」能逼着 Codex 去实际读文件而不是凭训练记忆编。第三「本次实践要求」这一段是场景化的你可以根据当次任务替换比如改成「重点分析测试用例」或「重点分析文档生成」。如果你想让 Codex 在回答时更聚焦命令注册可以在 AGENTS.md 里再加一段## 命令注册相关 - app.command() 的注册逻辑在 typer/main.py。 - 参数解析在 typer/params.py。 - 底层命令执行和帮助信息在 typer/core.py。 - 回答注册流程时请按「装饰器 - Typer 实例 - Click 命令」的顺序讲。这段不是必须的但它能把 Codex 的注意力提前锚定到关键文件上减少它在无关目录里绕圈。4. 验证 Codex 是否读懂 Typer 命令注册逻辑AGENTS.md 写好了接下来要验证它到底有没有生效。验证方法不是问「你读了吗」而是问一个只有真读过源码才能答对的问题。在typer目录里启动 Codex然后输入下面这段提示词先不要修改任何文件。 请阅读当前项目并结合 AGENTS.md 的要求回答 1. 用户写 app.command() 时这个装饰器最终把函数注册到了哪里 2. typer/main.py 里 Typer 类的 command 方法大概做了什么 3. 命令最终是怎么变成 Click 命令的 4. 请引用具体文件路径和函数名。如果 AGENTS.md 生效Codex 的回答应该具备这几个特征引用typer/main.py里的Typer.command方法提到typer/core.py里的TyperCommand或类似类说明装饰器返回的是被包装后的函数注册发生在Typer实例初始化或command调用时。如果它只泛泛说「Typer 封装了 Click」没有具体路径说明 AGENTS.md 没被读到或者你启动 Codex 的目录不对。再追一个更具体的问题验证它对--help生成路径的理解继续不要修改文件。 假设用户运行 python main.py --help 请结合 typer/core.py 和 typer/main.py 说明 1. --help 是在哪一层被拦截的 2. 帮助信息的格式化大概由哪个模块负责 3. tests/ 里有没有覆盖 --help 的用例请给出测试文件路径。这一步能同时验证三件事Codex 是否读了typer/core.py、是否读了tests/、是否按 AGENTS.md 要求引用了路径。如果它给出的测试文件路径在tests/下真实存在基本可以确认 AGENTS.md 在起作用。实测下来加了 AGENTS.md 之后Codex 回答里出现具体文件路径的比例明显上升对typer/main.py和typer/core.py的引用也更准确。没加之前它经常把typer/models.py和typer/params.py的职责讲混。5. 本篇常见错排查5.1 Codex 完全没提 AGENTS.md最常见的原因是启动目录不对。AGENTS.md 必须放在你启动 Codex 的那个目录里。如果你在~/codex-practice启动但 AGENTS.md 在~/codex-practice/typer/Codex 读不到。解决办法是cd typer再启动或者把 AGENTS.md 放到上层目录并在里面写明项目路径。5.2 回答里路径对不上源码如果 Codex 引用了typer/commands.py这种不存在的文件说明它在凭记忆编。这时候检查 AGENTS.md 里有没有写「必须引用具体文件路径」以及你有没有在提示词里明确要求「引用具体文件路径和函数名」。两个都写了还编就把问题拆小比如只问「typer/main.py 里 Typer 类有哪些方法」逼它聚焦单文件。5.3 一次列了十几个文件这是 Codex 的默认行为AGENTS.md 里的「一次最多列 5 个关键文件」就是用来压这个的。如果它还是列很多可以在提示词里再补一句「最多列 5 个按重要性排序」。另外把「避免信息过载」写进 AGENTS.md 比写在提示词里更持久因为提示词每次都要重打。5.4 模型端点连不上如果你在 Codex 里发消息后一直转圈或报连接错误先检查OPENAI_BASE_URL是否设成了https://taotoken.net/api以及 API Key 是否有效。可以在终端里用 curl 快速验证curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY如果返回模型列表说明端点通如果返回 401说明 Key 有问题去控制台重新生成一个API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite5.5 AGENTS.md 写了但 Codex 不遵守AGENTS.md 是「软约束」不是硬规则。Codex 会读但不保证 100% 遵守。提高遵守率的办法是把最重要的规则放在文件最前面用祈使句而不是描述句在提示词里重复一次关键约束。比如 AGENTS.md 里写了「不要修改源码」提示词里再写一次「先不要修改任何文件」双保险。6. 把 AGENTS.md 变成你的项目阅读加速器AGENTS.md 的价值不在于「写一份文件」而在于把重复的协作偏好固化下来。你在 Typer 项目里练熟这套流程后换到任何 Python 开源项目都能复用先克隆、再进目录、写一份针对该项目结构的 AGENTS.md、然后让 Codex 按图索骥。如果你接下来想让 Codex 长期参与编码任务而不是只读项目可以考虑 Coding Plan它在长会话和代码任务上的额度更宽松Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite如果只是想快速验证某个模型对 Typer 源码的理解可以直接在模型对话里贴关键文件片段试模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite接入细节和参数说明看文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一个我踩过的坑AGENTS.md 不要写太长。我一开始塞了二十多条规则结果 Codex 反而抓不住重点。控制在 15 行以内只保留「读什么、怎么答、改不改」三类规则效果最好。