Codex 新手教程：第一次改文件、看 diff、跑测试

只打开这次要练习的项目

先选择一个受 Git 管理、没有生产密钥的练习项目。不要把整个用户目录、下载目录或多个项目的父目录交给 Codex。开始前运行 git status --short，保存已有改动列表；这些改动属于原作者，不是本轮可以随意清理的内容。

把第一题缩成一处无害文案

可以直接输入：‘只修改 src/pages/index.astro 里首页副标题的一句话，不改结构、样式、依赖或其他文件。修改后运行 git diff --check 和 npm test，报告原始结果；失败时不要删除现有改动。’ 文件名和测试命令必须换成当前仓库真实值。

1. 让 Codex 复述边界

   操作

   发送单文件任务后，要求 Codex 在编辑前复述允许文件、禁止项和两条验收命令。

   你应该看到

   计划只出现一个允许文件，没有安装依赖、发布或清理工作树。

   如何确认

   把计划中的路径与 git status --short 记录逐项对照。

   卡住时

   • 如果计划要改多个文件，停止并把任务继续缩成一句纯文本修改。
   • 如果 npm test 不存在，先从 package.json 找到真实 test 脚本，再更新验收命令。

先看 diff，再看 Agent 的总结

编辑完成后运行 git diff -- 目标文件，逐行确认删除和新增是否只覆盖那句话。再运行 git diff --check；退出码为 0 且没有输出，说明没有空白错误，但不证明文案正确或页面能运行。

1. 检查改动范围

   操作

   运行 git diff --check，再运行 git diff -- 目标文件，并确认 git status --short 没有新增越界文件。

   你应该看到

   diff 只显示目标文案的一删一增，git diff --check 退出码为 0。

   如何确认

   亲自核对文件名、删除行、新增行和命令退出码。

   卡住时

   • 如果出现无关文件，不要批量撤销；先让 Codex 解释每个文件来源，并只反向编辑本轮新增内容。
   • 如果 git diff --check 报 trailing whitespace，让 Codex 只修对应行后重跑。

运行仓库自己的测试

示例仓库使用 npm test；你的项目可能使用 pnpm test、pytest 或其他命令。测试退出码为 0 才表示这组自动检查通过。若改的是网页文案，还要启动项目并在浏览器找到那句话；测试通过不等于视觉结果正确。

不满意时做非破坏回退

先保留 git diff 作为依据，再让 Codex 对本轮那一行逐行反向编辑，恢复成改动前文字，然后重跑 git diff --check 和 npm test。不要运行 git reset --hard、git clean 或对整个工作树使用 checkout；它们可能连同你开始前已有的未提交工作一起删除。

本站本次实测：单文件修改、测试与 diff

版本：Codex CLI 0.138.0，显式使用 gpt-5.4 与 workspace-write sandbox。输入：只把 home.txt 的“主按钮：开始”改成“主按钮：查看方案”，不得改其他产品文件或装依赖，然后运行测试。关键输出：Codex 修改 home.txt；npm.cmd test 输出 PASS；git diff --check 无报错。退出码：外层 Codex=0，代理内 npm test=1，跟进 npm.cmd test=0，git diff --check=0。验收结论：通过但依赖 Windows 入口修正，目标文件与确定性测试都已验证。失败项：PowerShell 禁止 npm.ps1，且运行 hook 曾生成 .omx 状态文件；状态文件已移除，原始失败仍保留。下方“本节来源”链接公开命令、输入、输出摘录、退出码和限制的脱敏 JSON 摘要。

来源与转换边界

项目打开方式与 Codex 能力边界以 OpenAI 官方 App 文档和 owner 仓库为事实来源；个人文章只作为第一次使用时常见困惑的案例线索。本文没有翻译文章段落，也不承诺任何人在固定时间内完成；一次本地实测不代表所有 Windows 策略或仓库脚本。