Codex 使用教程：从第一个工程任务开始

第一步：从小任务开始

第一次使用 Codex，不要直接丢一个“大改整个系统”的需求。更好的方式是选一个边界清楚的小任务，例如：

• 给一个已有页面补 SEO title 和 description。
• 修一个明确报错。
• 给一个纯函数补测试。
• 整理某个模块的 README。

任务越具体，Codex 越容易给出可验证的结果。

第二步：让它先读项目

可以先给它这样一句话：

请先阅读项目结构和 README，不要改代码。告诉我这个项目怎么启动、怎么测试、主要模块在哪里。

这一步的目的是让 Codex 建立上下文，也让你确认它有没有看对仓库。

第三步：描述目标和边界

一个好的任务说明通常包含四件事：

• 你要什么结果。
• 哪些文件或页面相关。
• 哪些事情不要动。
• 做完后用什么命令验证。

例如：

请给教程中心新增一个列表页，只做前台展示，不加后台编辑器。完成后跑 typecheck 和相关测试。

这种描述比“帮我做 SEO 模块”更容易落地。

第四步：看 diff，而不是只看总结

Codex 修改完成后，不要只看它的文字总结。你应该重点看：

• 新增了哪些文件。
• 有没有动到无关模块。
• 有没有引入不需要的新依赖。
• 测试是否覆盖关键逻辑。
• 页面文案是否符合你的产品定位。

如果 diff 太大，可以要求它按文件解释改动。

第五步：跑验证

常见验证包括：

pnpm typecheck
pnpm test
pnpm build

具体跑哪个命令，要看项目已有约定。对线上产品来说，代码修改通过测试不等于已经发版；提交、推送、部署应该分开确认。

第六步：逐步扩大任务

等你熟悉流程后，可以让 Codex 做更复杂的事情：

• 按现有模式新增一个模块。
• 分析线上错误日志并定位代码路径。
• 给一个功能写设计文档和实现计划。
• 做 code review 并修复高风险问题。

最稳的用法不是一次让它“全自动完成一切”，而是让它在每个工程节点给你可检查的证据。