用 Codex 处理真实项目时，有时会遇到一种很奇怪的情况：

文件明明已经新建了，但 Codex 搜索时却像完全看不到。

常见表现包括：

• 新文件已经存在，Agent却说“未找到”；
• 自己能在资源管理器里看到，Codex却搜索不到；
• 新建配置文件后，任务里一直没有被引用；
• 某些目录里的文件经常被忽略；
• 文件已经修改，但 git status 没有任何变化。

这种问题不一定是 Codex 没有读取能力。

很多时候真正原因和：

Git状态、忽略规则、隐藏目录或者当前工作区范围 有关。

一、先确认文件真的在当前项目里

最先检查的不是 Codex，而是文件路径。

例如项目目录是：

/project/app

但新文件实际创建到了：

/project/app-backup

文件名完全一样，也会让人误以为它就在当前项目。

可以先确认：

pwd

再检查目标文件：

ls

或者直接搜索：

find . -name "config.json"

先确定：

文件确实属于当前工作区。

---

二、检查 git status

如果文件刚刚新增，可以先运行：

git status

正常情况下，未跟踪文件可能会显示：

Untracked files:
  src/new-file.ts

如果完全没有出现，就需要继续检查。

可能是：

• 文件被忽略；
• 文件创建在仓库之外；
• 当前Git仓库不是你以为的那个仓库。

git status 是判断文件真实状态非常直接的方法。

---

三、.gitignore可能把文件排除了

这是最常见原因之一。

例如 .gitignore 里存在：

.env
dist/
logs/
*.tmp

如果你新增的是：

.env

或者：

logs/debug.txt

Git默认就不会把它显示成普通未跟踪文件。

这时候可以检查：

git check-ignore -v 文件路径

例如：

git check-ignore -v .env

如果命令返回匹配规则，就说明这个文件确实被忽略了。

---

四、不要只检查项目根目录的 .gitignore

大型项目里可能不止一个忽略规则来源。

例如：

• 根目录 .gitignore；
• 子目录 .gitignore；
• 全局Git ignore；
• 工具自己的忽略配置。

所以看根目录没有对应规则，不代表文件一定没有被忽略。

尤其是 Monorepo 或长期维护的项目，更容易出现多层配置。

---

五、隐藏文件和隐藏目录也容易被漏掉

很多开发配置本身就是隐藏文件。

例如：

.env
.github/
.vscode/
.config/

有些工具默认展示逻辑可能不会把隐藏内容放在最显眼的位置。

如果任务明确涉及隐藏文件，可以直接告诉 Codex：

请同时检查隐藏文件和以.开头的目录，不要只搜索普通文件。

这样可以减少遗漏。

---

六、生成目录有时本来就不应该直接修改

例如：

dist/
build/
generated/
coverage/

这些目录很多都是由：

• 构建工具；
• 代码生成器；
• 测试工具；

自动产生。

如果Agent发现这些目录被忽略，并不一定是异常。

真正应该修改的可能是：

src/
schema/
templates/

然后重新运行生成命令。

所以发现文件被忽略以后，不要马上删除 .gitignore 规则。

先判断：

这个文件到底应该人工维护，还是自动生成。

---

七、文件存在，不代表已经进入当前任务上下文

还有一种情况：

文件已经存在；

Git也能看到；

但Agent当前任务没有主动读取它。

特别是项目比较大时，Codex通常不会一次把所有文件都当成当前上下文。

这时候可以明确指定：

请读取 src/types/user.ts，并检查它和当前修改的关系。

或者：

搜索所有引用 UserProfile 的文件。

主动指定文件或符号，比单纯说：

你再找一下。

更有效。

---

八、同名文件也可能导致误判

例如项目里同时存在：

src/config.ts
tests/config.ts
legacy/config.ts

如果只说：

修改config.ts。

Agent可能找到的不是你真正想要的文件。

所以涉及新文件或同名文件时，最好使用完整路径：

src/config.ts

而不是只写文件名。

这样能减少搜索结果混淆。

---

九、修改完以后再次检查文件状态

如果Codex新建或修改了文件，建议结束前再运行：

git status

然后根据需要查看：

git diff

对于未跟踪的新文件，还可以单独确认文件内容。

这样能够快速判断：

• 新文件有没有真正创建；
• 是否在正确目录；
• 是否被忽略；
• 修改范围是否符合预期。

---

十、一个比较稳定的排查顺序

遇到 Codex 找不到新文件，可以按这个顺序：

第一步：确认当前工作目录。

第二步：确认文件真实路径。

第三步：运行 git status。

第四步：检查 .gitignore。

第五步：确认是不是隐藏或生成目录。

第六步：明确告诉Codex读取具体文件路径。

通常不用反复搜索很多轮，就能找到问题所在。

---

最后

Codex找不到刚新增的文件，很多时候并不是文件真的不存在。

真正需要检查的是：

文件在哪里、Git怎么看它、忽略规则有没有排除它，以及Agent当前有没有主动读取它。

尤其在大型项目里：

同名文件；

隐藏目录；

生成文件；

多层 .gitignore

都可能让问题变得更复杂。

遇到这种情况，可以先用：

git status

确认真实文件状态，再判断后续应该检查路径、忽略规则还是工作区范围。

---

持续更新 Codex、大模型开发与 AI 编程实战内容，更多技术内容欢迎搜索关注「仙逆GPT」。