Codex 实战：用一次真实需求走完「读—改—测—提交」全流程

真实项目里用好 Codex 的关键不是「让它写代码」，而是把需求拆成可验证的小步：先让它读懂项目、再让它出方案、每步小步提交、让它自己跑测试闭环。本文用一个给博客加「文章搜索」的需求走完全程。

这是 Codex 系列第 ③ 篇。建议先看 ② 基础使用：常用命令与日常工作流，本文默认你已熟悉审批模式和常用命令。

前两篇讲了怎么装、怎么用。这一篇不讲概念，直接走一遍真实流程：给一个已有的博客项目加「文章搜索」功能。你会看到从接手到提交的每一步，以及每一步该对 Codex 说什么。

场景设定

假设你接手一个 Astro 博客项目，需求很简单：

首页加一个搜索框，能按标题和标签过滤文章列表。

项目你不熟，代码不是你写的——这恰恰是 Codex 最能帮上忙的场景。

第 0 步：准备工作（别跳过）

cd ~/blog-project

# 确认工作区干净，有未提交的改动先处理掉
git status

# 建一个功能分支，别在 main 上直接让 AI 动手
git checkout -b feat/article-search

在干净的 Git 分支上工作是用 AI 编程的安全底线。有了它，后面无论 Codex 改成什么样，你都能一键回到原点。

第 1 步：让 Codex 读懂项目（只读模式）

codex chat --approval read-only

先别改任何代码。读一下 src/ 目录，告诉我：
1. 文章数据是怎么组织的（在哪、什么格式）
2. 首页文章列表在哪个文件、怎么渲染的
3. 项目用了什么框架和样式方案

Codex 会读取相关文件并给你一份摘要，比如：

- 文章是 Markdown，放在 src/content/posts/，用 Astro Content Collections 管理
- 首页列表在 src/pages/index.astro，通过 getCollection('posts') 取数据后 map 渲染
- 框架 Astro + Tailwind CSS

这一步的价值：你花两分钟就摸清了陌生项目的结构，而且确认了 Codex 的理解是对的——如果它读错了，现在纠正的成本最低。

第 2 步：要方案，不要直接要代码

切到手动审批，让它先出计划：

/approve manual

我要在首页加一个搜索框，按标题和标签实时过滤文章。
先说你的实现思路、会改哪些文件、有没有取舍，我确认后再动手。

Codex 给出方案：

思路：纯前端过滤（文章量不大，不必上搜索服务）
- 改 src/pages/index.astro：加搜索输入框，给每张卡片加 data-title / data-tags 属性
- 加一段 <script>：监听输入，按关键词显隐卡片
- 不引入新依赖，复用现有 Tailwind 样式

取舍：纯前端方案适合几百篇以内；再多需要考虑 Pagefind 之类的方案。

方案合理就继续，不合理就在这里纠正——改一句话，胜过回滚一屏代码。

第 3 步：让它动手，逐步审批

按这个方案实现，先只改 index.astro。

手动模式下，Codex 每次改文件都会给你看 diff 并等确认。认真扫一眼 diff：

改动范围是不是只在预期文件？
有没有顺手删掉不该删的东西？
命名和风格跟项目一致吗？

没问题就 approve，有问题当场让它调整。

第 4 步：让 Codex 自己验证

代码写完不等于能用。让它形成闭环：

启动 dev server，确认页面能正常打开、搜索框能过滤。
如果控制台有报错，贴出来并修复。

# Codex 会执行类似
npm run dev
# 并检查输出 / 报错

如果有测试，更进一步：

跑一下测试，有失败就修到全绿。

「改—测—修」闭环是实战里最省心的部分——让 AI 自己发现并修掉低级错误，而不是把半成品甩给你。

第 5 步：小步提交

功能跑通，立刻提交：

git add -A
git commit -m "feat: 首页文章搜索（按标题和标签过滤）"

如果需求还有后续（比如再加「按分类筛选」），每个独立小功能单独提交。这样任何一步出问题，回滚都不会波及已完成的部分。

完整流程回顾

把上面的节奏抽象出来，就是一套可复用的实战 SOP：

0. 干净分支          → git checkout -b feat/xxx
1. 只读理解          → 让它读，你确认它没理解错
2. 先要方案          → 让它列计划，你把关方向
3. 逐步实现 + 审 diff → 手动模式，每步看清楚
4. 自己验证          → 跑起来 / 跑测试，改到通过
5. 小步提交          → 每个小功能一个 commit

无论任务是加功能、修 bug 还是重构，这套流程都适用。变的是需求，不变的是节奏。

实战中的几个判断

什么时候可以开 auto？ 任务重复、边界清晰、且在 Git 保护下——比如「把这 20 个文件的 var 全改成 const」。探索性任务始终留在手动。
它卡住了怎么办？ 别反复追问同一句。用 /clear 清上下文，把问题重新描述得更具体，或者自己先缩小范围再交给它。
改动太大看不过来？ 说明任务拆得不够细。回到第 2 步，让它把大任务拆成几个能单独提交的小步。