外观
Codex 写代码实战：分析项目、修改文件、运行测试与查看 Diff（2026）
如果你条件有限，强烈推荐国内 API 站
这是站主自主搭建纯 GPT API 站，无需梯子，实时更新 GPT 最新模型（仅支持电脑端），价格是官方的 三分之一，操作简单，连接稳定，价格便宜，保证没有任何掺水、收集信息等低劣行为，保证爽用 GPT。
Codex 真正有价值的地方，不是一次生成几百行代码，而是围绕现有项目完成一条可复核的工作链路：读取仓库 → 定位问题 → 制定计划 → 小范围修改 → 运行测试 → 查看 Diff → 人工验收。
这篇教程不追求让 Codex “全自动接管项目”。更稳妥的分工是：Codex 负责分析、修改和验证，人负责明确需求、控制范围与最终上线决定。
本文更新于 2026 年 8 月 3 日。客户端界面、权限提示和功能会变化，应以当前版本为准。
一、开始前：准备一个可以恢复的项目
不要第一次就修改没有版本管理的生产项目。练习仓库最好满足：
- 已使用 Git 管理；
- 能在本机运行测试或构建；
- 不包含真实密钥、用户数据和生产数据库；
- 即使修改失败，也能从 Git 找回原始版本。
进入项目后，先手动执行：
bash
git status --short
git branch --show-current第一条检查当前工作区是否已有改动，第二条确认所在分支。如果 git status --short 已列出文件，先判断它们是不是你自己的修改；不要让 Codex 覆盖或“顺手整理”无关内容。
不要把密钥交给编程代理
检查项目中是否包含 .env、云服务凭证、数据库密码、私钥或真实用户数据。工具能够读取，不代表这些内容适合发送给外部 AI 服务；公司项目还应先确认内部政策。
二、认识 Codex 项目界面
不同系统和版本布局略有差异，但项目工作通常围绕目录、对话、执行记录和文件改动展开。
上图用于说明项目和任务界面。型号、按钮名称和位置可能更新，不能把截图当作当前模型或固定功能清单。
CLI、App 和 IDE 扩展的核心原则相同：先确认打开的是正确仓库，再用 Prompt 限定任务范围。
三、实战任务：修复表单空白输入
下面用一个小型真实需求演示完整流程：
用户提交表单时，空字符串会被拦截，但只输入空格仍可以提交。需要修复校验，并补充测试。
这个例子包含定位代码、理解现状、修改逻辑、补测试和检查 Diff。第一次练习建议把范围控制在 1～3 个文件。
四、第一步：只读分析仓库
低质量结果往往不是模型不会写代码，而是它没理解项目就开始改。第一轮明确要求只读：
text
请先只读分析这个项目，不要修改文件，也不要安装依赖。
任务背景：
用户提交表单时，空字符串会被拦截，但只输入空格仍然可以提交。
请完成：
1. 阅读 README、依赖配置和项目规则文件；
2. 找到表单提交、字段校验和相关测试；
3. 说明调用链和问题可能出现的原因；
4. 列出可能需要修改的文件；
5. 告诉我还缺少哪些信息。
限制：
- 不修改文件；
- 不执行具有写入效果的命令；
- 不升级依赖；
- 不处理无关代码。重点核对它找到的文件是否真实存在、测试框架是否判断正确、是否区分前端和后端校验，以及是否准备扩大到大量无关文件。
五、第二步：先制定最小计划
定位基本正确后，再让 Codex 给出计划，暂时不编辑：
text
根据刚才的分析给出最小修改方案，暂时不要编辑文件。
计划需要包含：
- 每个待修改文件的作用；
- 每处修改解决什么问题；
- 需要新增或调整的测试；
- 准备运行的验证命令；
- 可能影响的现有行为。
优先复用已有校验方法和代码风格，不引入新依赖。计划应该覆盖这些边界：
| 输入 | 预期结果 |
|---|---|
"" | 拒绝提交 |
" " | 拒绝提交 |
"\t\n" | 拒绝提交 |
"正常内容" | 允许提交 |
" 正常内容 " | 是否裁剪由产品规则决定 |
最后一种情况需要人工确认。拦截纯空白字符，不等于一定要改变正常内容的原始格式。
六、第三步：批准小范围修改
确认计划后，继续写清边界：
text
可以按刚才的最小方案修改。
要求：
1. 只修改计划中列出的文件；
2. 保持现有风格，不做顺手重构；
3. 不升级或新增依赖；
4. 为纯空格、Tab 和换行补测试；
5. 不提交 Git；
6. 完成后列出实际修改文件及理由。“不要顺手重构”非常重要。简单 Bug 如果同时触发变量重命名、目录调整、全仓库格式化和依赖升级，Diff 会难以审查。
修改后先运行：
bash
git status --short检查文件数量是否符合预期。未被 Git 跟踪的新文件不会完整出现在普通 git diff 中，所以不能只看 Diff。
七、第四步：运行匹配任务的测试
先让 Codex 读取项目脚本，再选择验证命令：
text
请检查项目现有的测试和构建脚本，选择与本次修改直接相关的最小验证命令。
先告诉我准备运行什么命令以及原因；不要安装新依赖，不要修改锁文件。JavaScript 或 TypeScript 项目常见命令可能包括：
bash
npm test
npm run lint
npm run typecheck
npm run build这些只是例子。仓库也可能使用 pnpm、yarn、Vitest 或 Jest；没有读取 package.json 前不要机械照抄。
测试失败时怎么判断
测试失败不一定等于代码修改错误，要区分：
- 本次修改导致的断言失败；
- 环境缺少依赖；
- 修改前已经存在的失败；
- 网络或外部服务不可用；
- 命令或参数使用错误。
可以继续要求：
text
请分析测试失败，但先不要修改文件。
区分它属于本次修改、测试本身、本地环境，还是无关的既有失败。
引用关键错误信息并给出最小处理建议。不要为了“让测试变绿”而删除断言、跳过测试或吞掉异常。
八、第五步：查看 Git Diff
Codex 说“已完成”不等于结果正确。最终验收应回到真实文件：
bash
git status --short
git diff --stat
git diff --check
git diff它们分别用于检查变更文件、改动规模、空白/冲突问题和逐行内容。Diff 很长时可限定文件：
bash
git diff -- path/to/changed-file.ts还可以让 Codex 做只读自审：
text
请只读审查当前未提交的 Diff，不要继续修改。
重点检查：
1. 是否完整解决纯空白字符可提交的问题；
2. 是否改变正常输入的既有行为；
3. 测试是否覆盖空字符串、空格、Tab、换行和正常内容；
4. 是否有无关修改；
5. 是否存在安全、兼容性或维护风险。
先列出问题；没有明确问题时，也说明仍未覆盖的风险。九、第六步：由人决定提交与部署
提交前至少确认：
- 改动文件与计划一致；
- 没有误改
.env、锁文件或生成文件； - 相关测试通过；
- 构建或类型检查结果可接受；
- 页面行为经过人工检查；
- 没有遗留调试日志。
确认后再由你执行：
bash
git add path/to/changed-file.ts path/to/changed-file.test.ts
git commit -m "fix: reject whitespace-only form input"生产部署会影响真实用户和外部服务，不应只根据一句“测试通过”自动执行。
十、可复用的完整项目 Prompt
text
你正在协助我修改一个现有代码仓库。
目标：
修复表单允许纯空白字符提交的问题，并补充回归测试。
开始前：
- 先运行 git status 并说明工作区状态；
- 阅读 README、依赖配置和仓库规则；
- 第一阶段只读分析，不修改；
- 找到实现文件、调用链和相关测试。
修改范围：
- 只处理字段校验及其测试；
- 复用现有工具和风格；
- 不新增或升级依赖；
- 不做无关重构；
- 不覆盖现有未提交改动。
验证要求：
- 覆盖空字符串、空格、Tab、换行和正常输入；
- 运行最相关测试；
- 如项目已有脚本，再运行类型检查或构建；
- 不通过删除断言或跳过测试规避失败。
输出：
1. 先给分析和最小计划；
2. 等我确认后再修改；
3. 列出文件、原因和实际命令结果；
4. 最后审查 git diff，但不提交或部署。更多模板见 Codex 提示词与 AGENTS.md 最佳实践。如果这套项目检查流程会在多个仓库重复使用，可以按 Codex Skills 教程 把说明、脚本与参考资料整理成可复用工作流。
十一、5 个常见失误
1. 一上来修改很多文件
暂停任务，让它解释每个文件与需求的关系，再缩小到必需改动。如果工作区已有个人修改，不要运行会一起清除用户内容的命令。
2. 无故修改锁文件
先确认是否真的需要依赖变化。任务不需要依赖时，应说明原因并移除本次产生的无关变更，不能覆盖原有用户改动。
3. 测试通过但页面仍异常
自动测试只证明被覆盖的场景。还要检查真实交互、浏览器控制台、接口响应、移动布局和异常输入。
4. Diff 中看不到新文件
普通 git diff 不完整展示未跟踪文件。先运行 git status --short，再决定是否纳入版本管理。
5. 请求更高权限
先看具体命令。读取项目、运行已有测试，与删除目录、安装全局软件、访问生产服务不是同一级风险。只为必要操作临时授权。
十二、完成标准：留下一条证据链
| 检查项 | 合格标准 |
|---|---|
| 问题定位 | 指向真实文件、函数和调用关系 |
| 修改范围 | 只涉及需求所需文件 |
| 代码实现 | 符合仓库风格，无无关重构 |
| 测试 | 覆盖正常输入和关键边界 |
| 命令结果 | 区分通过、失败与未运行 |
| Git Diff | 人工检查过重要改动 |
| 风险说明 | 列出尚未验证的环境和场景 |
| 提交部署 | 由用户验收后主动决定 |
把任务拆成“分析 → 计划 → 小范围修改 → 测试 → Diff → 人工验收”，通常比一句“帮我把项目改好”更容易得到稳定、可审查的结果。