课程章节

本文目录

快速入门第 3 章

第一次使用 Codex 修改代码：从检查项目到验证结果

通过一个完整的小任务学习 Codex 的标准开发闭环：检查、计划、修改、测试、审查与提交。

入门 20 分钟 13 节 2026-07-14 更新

第一次使用 Codex 修改代码：从检查项目到验证结果

第一次使用 Codex，不建议直接让它开发一个完整系统。最合适的练习是：修改范围小、预期结果明确、可以自动测试。

本章以“给一个已有的字符串格式化函数补充空值处理”为例，演示完整闭环。你可以替换成自己项目中的小问题。

1. 开始前检查 Git 状态

进入项目：

cd ~/code/my-project
git status

如果工作区不干净，先提交、暂存或切换分支：

git switch -c codex/first-change

记录当前测试基线：

npm test

如果原有测试已经失败，必须把基线失败告诉 Codex，否则它可能误以为失败由本次修改造成。

2. 启动 Codex

codex

先让 Codex理解项目，不修改代码：

先不要修改文件。
请确认：
1. 项目使用什么语言和测试框架；
2. 字符串格式化相关代码在哪里；
3. 对应测试在哪里；
4. 最小可运行的测试命令是什么。

这一步的目的不是让 Codex输出长篇架构分析，而是确认它找到了正确文件和正确验证方式。

3. 给出一个可执行的任务

推荐提示词：

目标：
让 formatDisplayName 在输入 null、undefined 或空字符串时返回“未命名”。

范围：
- 只修改该函数及其直接相关测试；
- 不改变其他格式化逻辑；
- 不新增依赖；
- 保持现有导出方式不变。

验证：
- 添加 null、undefined、空字符串测试；
- 运行最小相关测试；
- 最后汇报修改文件、行为变化和测试结果。

这条提示词包含四类信息：目标、范围、禁止项、验证方式。

4. 在 Codex 执行时观察什么

Codex 可能会：

搜索函数定义；
搜索调用位置；
阅读现有测试；
修改实现；
添加测试；
运行测试；
汇报结果。

你需要重点检查：

它是否修改了任务范围外文件；
是否运行了真实测试，而不是只说“应该通过”；
是否保留了已有行为；
是否新增了不必要依赖；
是否使用了项目已有代码风格。

当 Codex准备执行有风险的命令时，权限系统可能要求批准。阅读命令和作用范围后再批准。

5. 如何在中途纠偏

如果 Codex选错实现方向，不需要等它完成再重来，可以立即输入：

停止当前实现。不要引入新的 helper，直接在现有函数内处理空值，并保持当前函数签名。

如果修改范围过大：

把修改缩小到 src/utils/name.ts 和对应测试文件，恢复其他文件的变更。

如果它没有运行测试：

现在运行最小相关测试。不要只根据代码推断结果，给出实际命令、退出码和关键输出。

Codex 的高质量使用方式是持续提供方向，而不是一次输入后完全不检查。

6. 查看 Git Diff

任务完成后，在另一个终端检查：

git status
git diff --stat
git diff

建议按以下顺序审查：

文件数量是否合理；
是否有锁文件、配置文件等意外变化；
实现是否最小；
测试是否覆盖需求；
是否存在格式化噪音。

也可以在 Codex 中输入：

/review

选择“Review uncommitted changes”，让独立审查流程检查未提交改动。

7. 手工复验

即使 Codex声称测试通过，也应手工运行一次：

npm test -- name

如果项目有 Lint：

npm run lint

如果是 TypeScript：

npm run typecheck

一个最小前端改动通常至少验证：

npm run lint
npm run typecheck
npm test -- <相关测试>

不要每次都盲目运行整个大型测试套件。先跑最小相关测试，提交前再按项目规范运行完整检查。

8. 要求 Codex输出标准总结

推荐使用固定格式：

请按以下格式总结：

## 修改内容
- 文件：
- 行为变化：

## 验证
- 命令：
- 结果：

## 未验证项
- 无法运行或未覆盖的内容：

## 风险
- 兼容性和边界风险：

这样可以防止“完成了”这种含糊结论。

9. 提交代码

确认无误后：

git add src/utils/name.ts tests/name.test.ts
git commit -m "fix: handle empty display names"

不要习惯性执行 git add -A，除非你已经确认所有变化都属于当前任务。

10. 一个真实页面修改示例

假设你要给设置页增加确认提示：

目标：
用户点击“清空历史记录”时，先显示现有项目风格的确认对话框。

相关文件：
- src/pages/settings.tsx
- src/components/ConfirmDialog.tsx

要求：
- 复用现有 ConfirmDialog；
- 确认后才调用 clearHistory；
- 取消时不发请求；
- 保持键盘可访问性；
- 不新增依赖。

验证：
- 添加或更新组件测试；
- 验证确认、取消两个分支；
- 运行 Lint、类型检查和最小测试。

这种任务很适合作为第一次真实修改，因为范围清晰、交互明确、测试分支可枚举。