Appearance
开发者第一次使用 Codex：完成可验证的小改动
第一次任务不要选择“重写整个项目”。你需要先跑通一个完整但可控的闭环：记录现状、让 Codex 调查、批准一处小改动、运行验证、审查差异。这个流程以后会原样扩展到更复杂的任务。
本页要求 Git 仓库、终端和测试，是开发者教程。不会编程或只想完成办公、PPT、电商和内容任务，请改走 普通人的第一次文件任务。
选择合适的小任务
从真实仓库中选一个满足以下条件的任务：
- 最多影响一到三个文件；
- 你知道正确结果长什么样；
- 有现成测试、构建或人工检查方式；
- 不涉及生产数据库、付款、发布或凭证；
- 即使失败，也能通过明确编辑恢复。
适合的例子：修正一个错误提示、给已有函数补边界测试、更新一条已经验证的启动命令、修复一个稳定复现的样式问题。
第一步：记录修改前基线
bash
cd /path/to/project
git status --short --branch
git diff --stat如果已有未提交修改，把它们视为当前工作的一部分。记录文件名，不要让 Codex“顺便清理”。
再找出项目验证入口：
bash
ls常见证据包括 package.json、pom.xml、build.gradle、go.mod、Makefile、CI 工作流和仓库根目录的 AGENTS.md。
第二步：先让 Codex 只调查
启动：
bash
codex -C /path/to/project --sandbox read-only把下面模板中的方括号替换成你的任务：
text
目标：[描述一个小而具体的问题]。
先只调查，不修改文件。请：
1. 找到真实实现和调用方；
2. 说明问题为什么会发生；
3. 给出最小修改方案和预计影响文件；
4. 找到项目已有的验证命令；
5. 标出你还不能确认的地方。
边界：不要安装依赖，不要改无关文件，不要提交或推送。不要只看结论。检查它引用的路径、函数名和命令是否真实存在。
第三步：允许最小范围修改
确认调查正确后，新开可写任务，或在 App 中切换到工作区写入权限：
bash
codex -C /path/to/project --sandbox workspace-write --ask-for-approval on-request发送：
text
按刚才确认的最小方案实施。
要求：
- 只修改 [允许的文件或目录]；
- 保持公开接口和现有行为不变，除非它正是本次修复目标；
- 遵循仓库已有代码风格；
- 如果发现需要扩大范围，先停下来说明原因；
- 完成后运行最小相关验证，并报告命令、退出结果和未运行的检查；
- 不要提交、推送或发布。第四步：检查它到底改了什么
不要先问“完成了吗”，直接看工作树：
bash
git status --short
git diff --stat
git diff逐项确认：
- 是否只改了允许范围；
- 是否夹带格式化、依赖升级或无关重命名；
- 测试是否真正覆盖问题，而不是只断言一个恒真结果；
- 错误处理是否吞掉异常；
- 文案、路径和配置字段是否精确。
发现无关修改时，明确指出文件和行，让 Codex做定点调整。不要使用一条宽泛的“恢复所有文件”命令。
第五步：自己运行验证
先运行 Codex 报告的最小检查，再按风险决定是否扩大：
bash
# 示例，按项目替换
npm test
npm run build验证结果至少记录：
- 执行了什么命令；
- 退出码是否为 0；
- 有多少测试通过或失败；
- 哪些检查因环境限制没有运行；
- 如果是界面问题，在哪个 URL 和操作路径上人工确认。
第六步：让 Codex 做一次独立复核
bash
codex review --uncommitted "只报告会导致错误、安全问题或回归的发现；忽略纯风格偏好"审查不是权威裁决。对每条发现回到代码和测试中核实，再决定修改。
一份完整的完成报告应该长这样
text
已修改：
- src/example.ts：修复空输入处理
- test/example.test.ts：补充空输入回归测试
已验证：
- npm test：通过，42 tests passed
- npm run build：通过
未验证：
- 未运行端到端测试，因为本机缺少浏览器依赖
工作树：
- 仅上述两个文件有修改
- 未提交、未推送“代码看起来没问题”不是完成报告。
第一次任务最容易失败的地方
任务太大
把“完成用户系统”拆成“确认现有登录链路”“增加一个字段”“补一条回归测试”等独立任务。
没有先记录工作树
任务完成后你会分不清哪些是原有修改。任何编辑前先运行 git status --short。
验证命令只是 Codex 猜的
要求它指出命令来自哪个配置文件，并自己运行一次。
一次给了太多附加要求
先完成必须目标，再单独做重构、性能和视觉优化。把“顺便”从高风险任务中删掉。
完成门槛
- [ ] 修改前后工作树都有记录。
- [ ] 先完成只读调查，再开始编辑。
- [ ] 修改范围没有意外扩大。
- [ ] 至少运行一项与问题直接相关的验证。
- [ ] 能用自己的话解释修改为什么有效。
- [ ] 清楚知道哪些检查尚未执行。
下一步
继续学习 怎样给 Codex 写任务，把本页流程压缩成稳定的日常提示模板。