Codex 第一次任务怎么做：从只读分析到安全修改

TL;DR：第一次使用 Codex 先读、再改、最后验证

第一次任务不要直接让 Codex 重写整个项目。先进入一个有版本控制的项目目录，确认状态，要求它只读分析并给出计划；确认范围后再允许小范围修改，最后运行项目已有的测试并检查 git diff。

第一步：准备可回滚的项目目录

进入目标项目，确认当前分支和工作区没有未保存的改动：

cd /path/to/your/project
git status --short
git branch --show-current

如果工作区本来就有修改，先记录它们属于哪个任务。不要为了让输出“干净”而直接执行清理未跟踪文件的命令。

第一次练习可以新建分支：

git switch -c codex-first-task

如果项目还没有 Git 仓库，先按团队流程初始化或使用项目副本；Codex 的自动修改能力不等于版本控制，回滚边界仍需要你自己建立。

第二步：让 Codex 先做只读分析

第一条任务应该容易验证、范围明确，而且不要求写文件：

请阅读当前项目的 README、依赖配置和测试目录，用中文说明：
1. 项目的技术栈和启动命令；
2. 主要入口文件；
3. 现有测试命令；
4. 如果要给工具函数补一个测试，最合适的文件位置。
不要修改任何文件，也不要执行会改变工作区的命令。

检查它是否引用了真实文件、命令和测试目录。若它把不存在的文件当成事实，先纠正任务范围，不要直接进入修改阶段。

第三步：把任务写成验收条件

好的第一次修改任务应同时说明目标、范围和验证方式。例如：

请只修改 src/utils/formatDate.ts 和对应测试文件：
- 为空值补充一个明确的返回行为；
- 保留现有公开函数签名；
- 先说明计划，再等待确认；
- 修改后运行该模块对应的测试命令；
- 最后总结文件变更、测试结果和仍未覆盖的情况。

这类任务比“帮我优化这个项目”更容易审查，也更适合发现 Codex 是否正确理解项目。

第四步：审查修改并验证

任务结束后，不要只看 Codex 的总结。使用 Git 检查真实变化：

git diff -- src/utils/formatDate.ts path/to/formatDate.test.ts
git status --short
npm test -- --runInBand

测试命令应替换成项目真实存在的命令。若项目没有 npm test，先查看 package.json 或 README，不要猜命令。

第一次任务的安全边界

| 边界 | 第一次任务建议 | 暂缓处理 | | --- | --- | --- | | 文件范围 | 一个函数和对应测试 | 全仓库批量重构 | | 权限 | 先只读，再逐条确认 | 一开始使用全自动模式 | | 命令 | 读取、测试、格式检查 | 删除文件、修改生产配置 | | 验收 | Git diff 加已有测试 | 只依据自然语言总结 |

常见报错与解决

| 现象 | 原因 | 处理方式 | | --- | --- | --- | | Codex 找不到项目文件 | 启动目录不是项目根目录 | 先运行 pwd、git status，再重新指定项目目录 | | 输出计划与项目不符 | 上下文读取错误或任务太宽 | 给出真实文件路径，要求先只读检查 | | 修改范围超出要求 | 任务边界和验收条件不明确 | 停止继续执行，检查 diff 后重新拆分任务 | | 测试命令不存在 | 猜测了项目脚本 | 从 package.json 和 README 获取实际命令 |

FAQ：Codex 第一次任务怎么选

第一次应该让 Codex 写什么？

优先选择补一个小测试、解释一个模块、修复一个有明确复现步骤的报错，避免从大型重构开始。

Codex 修改错了怎么恢复？

先查看 git diff，确认文件范围后再按项目流程恢复。不要在没有确认路径的情况下执行批量删除或清理命令。

需要先写 AGENTS.md 吗？

不是必须，但项目有固定命令、目录边界或安全要求时，先写一份简短的 AGENTS.md 规则 会减少重复沟通。

第一次任务可以直接使用全自动模式吗？

不建议。先熟悉审批、文件范围和测试结果，再根据任务风险逐步调整权限。

下一步可以阅读 Codex CLI 登录教程、Codex 官方工作流 和 Codex 401 报错解决。