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 里切到 workspace-write，CLI 这样：
bash
codex -C /path/to/project --sandbox workspace-write --ask-for-approval on-request发送：
text
按刚才确认的最小方案实施。
要求：
- 只修改 [允许的文件或目录]；
- 保持公开接口和现有行为不变，除非它正是本次要修的；
- 遵循仓库已有的代码风格；
- 如果发现需要扩大范围，先停下来说明原因；
- 完成后运行最小相关验证，报告命令、退出结果和还没跑的检查；
- 不要提交、推送或发布。第四步：别问"完了吗"，自己看
不要问 Codex"做完了吗"，直接看工作树：
bash
git status --short
git diff --stat
git diff逐项确认：
- 是不是只改了允许的范围
- 有没有夹带格式化、依赖升级、无关重命名
- 测试是不是真覆盖了问题，还是只 assert 了一个恒为真的东西
- 错误处理是不是把异常吞了
- 文案、路径、配置字段是不是精确
发现无关修改，明确指出文件和行号让 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 写任务，把本页的流程压缩成稳定的日常模板。