Codex 从目录到入口：找到真正需要修改的代码

配图采集环境：macOS 15.7.5（Build 24G624）；Codex/ChatGPT App 26.721.41059；2026-08-21 核验。Codex 实操部分在 Windows PowerShell 环境完成，正文会单独说明。

真正需要动的文件是哪几个

拿到一个需求，最费时间的往往不是改代码，而是回答一个问题：真正需要动的文件是哪几个。范围圈大了，Codex 会在无关目录里反复翻找；范围圈错了，改完才发现入口在别处。

这篇文章我用两种方式各走了一遍完整的入口追踪。先在本机用只读命令手动追一次，再把同样的问题交给 Codex 做一次只读调查。两次都停在应用补丁之前，重点看每一步排除了什么、留下了什么证据。

图一　从整个仓库出发，逐层排除无关目录，最后落在真正需要修改的文件上。

如果你还没让 Codex 改过项目，建议先看《别一上来就让 Codex 改项目，我已经替你踩过坑了》，再回来对照这里的调查步骤。

先确认仓库状态和目录边界

入口追踪的第一步不是搜索关键词，而是确认自己站在哪里。我固定先跑两条只读命令：

git status --short --branch
rg --files

第一条确认当前分支和未提交改动，避免把别人留下的现场误当成调查结论。第二条列出文件全貌，先建立“这个仓库里有什么”的边界感，再决定往哪里挖。

我用本机一个练习用的订单管理小项目做了第一次演示。需求是“修复订单列表金额偶尔显示为 NaN”，任务是确认真正需要继续编辑的最小文件集。

图二　本机只读调查记录：先看分支状态，再用 rg --files 和 rg -n "NaN|formatAmount" 圈出入口和最小改动范围。

这次调查锁定了四类入口：页面入口是 src/pages/OrderList.vue，数据入口是 src/api/orders.js，格式化入口是 src/utils/format.js，测试入口是 tests/orders.spec.js。最后得出的最小改动范围只有 format.js 里的金额格式化函数和它的测试，其他页面、路由和构建配置一律不碰。

注意这个顺序：先有目录边界，再有入口判断，最后才有改动范围。跳过前两步直接改文件，是范围失控最常见的原因。

从需求里的词开始搜索

确认边界之后，搜索词不要自己造，直接从需求里取。页面名、接口名、报错文本、业务术语，这些词在代码里往往有唯一或接近唯一的命中。

为了用一个公开仓库演示，我选了 GitHub 上的 githubtraining/hellogitworld，假设需求是“修复 plus 计算结果的显示问题”。只读查看，不执行任何修改。

图三　公开示例仓库的静态入口追踪：src/Main.groovy 第 9～14 行依次调用 square、divide、subtract、sum，沿 import static 找到 src/Sum.groovy 的实现。

静态追踪的顺序是：先找到程序入口 src/Main.groovy，再沿 import static Sum.sum 这样的符号引用找到实现文件，最后用一条命令复核：

rg -n 'println|static (int|void)|import static' src

这条命令同时命中输出语句、方法定义和符号引用，一次就能把“入口在哪、实现者有谁”对上。

把“暂不相关”也写下来

圈定范围时，排除项和候选文件同样重要。只写“要改什么”，下次复查时无法判断某个文件是没看过，还是看过之后排除了。

图四　建议先读的文件、关联验证命令和暂不相关项都留痕；结论停在应用补丁之前。

这份记录里，src/Division.groovy 和 src/Square.groovy 被明确标注为“与 plus 逻辑无关”，build.gradle 标注为“本次不改依赖”。关联验证用 rg -n 'sum|plus|println' src README.txt 和 git status --short 两条，确认调查前后工作区保持干净。

最终的最小候选文件只有 src/Main.groovy 和 src/Sum.groovy。范围能收得这么小，靠的不是一次精准搜索，而是每一步都把排除理由写了下来。

把同一个问题交给 Codex

手动流程走完，我把一个同类需求交给 Codex 做只读调查。测试项目有 src、test、notes 三个顶层目录，需求写在 notes/需求说明.md 里：Sum.add(2, 3) 保持返回整数 5，Report.render(5) 返回字符串 "5"，但实际输出多了一个 debug-sum= 前缀。

我给 Codex 的指令是：先只读调查，不要改文件、不要装依赖、不要提交；从仓库状态、目录结构和关键词搜索开始，逐步找出真正相关的入口；每一步说明查了什么、排除了什么、下一步为什么查；证据不够就明说还缺什么，不要猜。

图五　Codex 的只读调查结果：仓库状态、入口定位、关键词搜索与排除、运行环境核对，全程未修改文件。

有几个细节值得单独说。

Codex 先确认仓库在 main 分支、工作区干净，再读 README 确认 src/Main.groovy 是程序入口。搜索阶段 rg 在当前环境启动失败，它没有卡住，改用 PowerShell 文本搜索和 git grep 继续，把“加法、结果、显示、Sum.add、Report.render、debug-sum”都搜了一遍。

搜索结论很干脆：Sum.add 只有一个生产调用点，在 Main.main 第 5 行；src/Sum.groovy 第 2 行的实现就是 left + right，和需求一致，加法逻辑被证据排除；src/Report.groovy 第 3 行拼接了 "debug-sum=${value}"，这才是显示错误的直接原因。它同时注意到测试 test/SumTest.groovy 第 2 行已经写明了期望行为 Report.render(5) == "5"。

最后它还核对了运行环境：找到了 Java，没找到 groovy 命令，所以没有执行测试，并明确写出“静态证据已经足够定位问题，但运行时验证仍缺失”。环境不够时不硬跑、也不假装跑过，这正是只读调查该有的边界感。

最小改动文件集：让结论分三栏

调查完成后，我追问了一步：给出最小改动文件集，只列真正需要修改的文件和理由，同时列出关联测试、配置和调用方证据，按“确认需要改、只需要查看、当前没有证据不应该改”分成三栏，不执行修改，也不生成补丁。

图六　三栏分类后的结论：最小改动文件集只剩 src/Report.groovy，并附完整证据链。

分类之后，调用方 Main.main 归入“只需要查看”，它只是 println Report.render(Sum.add(left, right)) 的组装者，自身没有错误证据；Sum.groovy 归入“不应该改”，需求要求它继续返回整数 5；notes/需求说明.md 是验收依据，不是实现文件。最小改动文件集最终只剩一个 src/Report.groovy。

底部的证据链把整条路径写了出来：Main.main → Sum.add(left, right)（计算正确）→ Report.render(result)（添加了错误的 debug-sum= 前缀）→ println（输出错误结果）。这样的结论不需要信任，可以直接核对。

如果你希望 Codex 每次进项目都先读这类规则，比如“先只读调查再动手”，可以把稳定的要求写进项目规则文件，具体做法见《别再重复提醒 Codex：用 AGENTS.md 让它读项目先读规则》。

入口不唯一时怎么办

有些需求会命中多个入口，比如同一个接口同时被页面和定时任务调用。这时不要急着二选一，先做三件事：

1. 把每个入口的调用方列全，确认它们是同一条链路还是互相独立。
2. 看测试覆盖在哪一侧，有测试的一侧优先作为修改点。
3. 仍然无法区分时，把两个入口和各自证据交给需求方确认，不要替业务做决定。

入口追踪的终点不是“找到一个文件”，而是“找到能被证据支撑的最小文件集”。证据不够时，继续查，或者停下来问。

小结

完整流程回顾一遍：先用 git status 和 rg --files 确认仓库状态和目录边界；再从需求原文取词搜索，沿符号引用追到真实入口；排除项和候选文件一起留痕；最后把结论分成“需要改、只需看、不应改”三栏，停在应用补丁之前。

这套顺序手动跑得通，交给 Codex 也跑得通。差别只在于，手动流程练的是你自己的判断，Codex 流程省的是你的时间，两者的验收标准是同一套。

第一次让 Codex 参与真实项目时，建议就从这种只读调查任务开始，具体理由可以看《第一次让 Codex 改项目，我建议你先从这个小任务开始》。

这套入口追踪流程适合在真实项目中反复练习：先调查、再收敛范围，最后才决定是否修改。