Codex 工程化指南：16 条可复用、可验证的工作流

Codex 的专业用法，不在于花哨的提示词，而在于构建一套可复用、可验证、权限可控、经验可沉淀的工程化工作流

说白了就是：那些琐碎的、重复的、要翻来覆去查的事情，交给 Codex；你要做的，是定目标、画边界、守标准和做最后拍板的那个人。

1. 专家不会上来就说"帮我写代码"

新手可能会这样开口：

帮我做一个登录功能。

但专家会这样说：

目标： 为现有项目增加邮箱 + 密码登录功能。

范围： 前端登录页、表单校验、错误提示；后端登录 API；必要时新增用户表字段。不要动现有注册流程。

约束： 不新增大型依赖；保持现有 UI 风格；不要直接提交 commit。

验收标准：

1. 空邮箱、错误邮箱、错误密码都有提示
2. 登录成功后跳转到 dashboard
3. 登录失败不泄露用户是否存在
4. 添加必要测试
5. npm test / lint / typecheck 通过

工作方式： 先阅读代码并给实现计划，不要马上修改。

你看，差距不在于"措辞花哨"，而在于专家把一个问题拆成了目标、范围、约束、验收标准和执行流程。模糊的需求交给任何工具都只能得到模糊的结果。

2. 每次进新项目，先让它"逛逛"，别急着改

Codex CLI 能读、能改、能跑你本地的代码。也正因为它是真刀真枪能动手的，专家进新项目的第一件事永远是"只读分析"。

每到一个新项目，先发这样一条：

请只阅读项目，不要修改任何文件。

输出：

1. 项目是做什么的
2. 技术栈
3. 目录结构
4. 关键业务流程
5. 启动、测试、构建命令
6. 最容易出问题的模块
7. 建议写入 AGENTS.md 的项目规则

等它跑完，再问一句：

请找出和【某功能】相关的所有文件，并画出调用链。不要修改代码。

这两步花不了几分钟，但能帮你省下后面大量的返工时间。着急让它改代码，往往是最慢的做法。

3. 花点时间维护一个 AGENTS.md，绝不会亏

AGENTS.md 是 Codex 在工作前一定会读的"行为说明书"。有了它，每次任务都有一致的预期，不用你一遍遍重复同样的要求。

先用 /init 生成一个初始版本，但别止步于此——根据你们团队真实的构建、测试、review 和发布流程手动打磨。

一份好用的 AGENTS.md 长这样：

# AGENTS.md

## 项目说明
这是一个 Next.js + TypeScript 项目，用于 xxx。

## 常用命令
- 安装依赖：npm install
- 本地启动：npm run dev
- 类型检查：npm run typecheck
- Lint：npm run lint
- 测试：npm test
- 构建：npm run build

## 工作规则
- 修改前必须先说明影响范围和计划
- 默认最小改动
- 不要无理由新增依赖
- 不要重写无关模块
- 改业务逻辑必须补测试
- 改 UI 必须检查 loading、empty、error、mobile 状态
- 完成后必须说明测试结果和潜在风险

## 完成标准
- 相关测试通过
- lint / typecheck / build 通过
- 行为符合验收标准
- diff 可 review

一个很实用的诀窍：每次 Codex 犯了错，直接把规则补进 AGENTS.md。

比如它动不动就给你加新依赖，你就写进去：

禁止新增依赖，除非先说明原因、替代方案和体积影响，并获得确认。

积累下来，这份文件就是你在这个项目里的"团队默契"。

4. 大任务先用 /plan，别让它一头扎进去

专家不会把一个大任务甩给 Codex 然后期待它自己搞定，而是先让它出计划。

/plan 我要把当前项目的支付流程重构成更清晰的 service 层。请先分析影响范围、风险、迁移步骤和测试策略。不要修改代码。

你可以让它按固定格式输出：

1. 你理解的目标
2. 涉及文件
3. 风险点
4. 分阶段方案
5. 每阶段验收标准
6. 需要我确认的问题

计划没过你这一关，就别让它碰代码。 多花五分钟审查计划，可能省下半小时收拾残局。

5. 长任务用 /goal，给它一个明确的终点

迁移、重构、修一波测试……这些不是一条指令就能收工的事，试试 /goal。

它适合让 Codex 围绕一个可验证的停止条件持续干活，跑偏了自己绕回来。

比如这样写：

/goal 完成从本地状态管理到 Zustand 的迁移。

停止条件：

1. 应用行为不变
2. 所有测试通过
3. npm run build 成功
4. 状态管理代码有文档
5. 输出迁移总结

停止条件越具体，它越不会在路上一去不回。

6. 权限别一直开着，分三种模式用

Codex 的 sandbox 是它的"安全护栏"——让它自主行动，但不给它无限制的机器权限。

日常建议分三种模式：

只读分析模式： 读代码、审查、解释、规划时用。这时候它只需要看，不需要动手。

常规开发模式： 日常写代码、跑测试。工作区内自由读写，越界操作需要你点头。

高风险操作模式： 碰到下面这些事，必须收紧——

删除文件、数据库迁移、生产配置、密钥、支付、认证权限、CI/CD、部署、批量重构

这些场景下，让它只分析、只提方案，别直接动手。

权限不该是"开"或"关"二选一，而是根据风险灵活切换。

7. 别信它说的"完成了"，让它跑给你看

Codex 说"改好了"，专家的第一反应是：跑一下。

请完成修改后运行：

1. npm run lint
2. npm run typecheck
3. npm test
4. npm run build

如果失败：先解释失败原因，再修复。不要掩盖测试，不要删除测试。

还有一句很关键，很多人会漏掉：

如果无法运行测试，请明确说明原因，并告诉我应该手动运行哪些命令。

别信任任何口头的"看起来没问题"，只相信跑出来的结果。

8. 写完别合，先让 /review 当第二双眼睛

代码写完，先别急着合回去。让 Codex 换个视角，帮你看看自己写的东西：

/review
请 review 当前未提交改动，重点检查：

1. 逻辑 bug
2. 安全风险
3. 边界条件
4. 测试缺失
5. 过度设计
6. 是否违反 AGENTS.md

如果你想更正式一些：

请不要修改代码，只输出 review 结果。
按 P0 / P1 / P2 分类。
每个问题包含：问题描述、相关文件、为什么有风险、建议修复方式。

让同一个模型审视自己的输出，是成本最低的查漏补缺。

9. 用 Subagents 来一次"专家会诊"

Subagents 是 Codex 的高级能力——它可以同时派出几个子 agent，各看一个维度，最后汇总回来。

上线前做一次全面体检：

请使用 subagents 并行审查当前改动：

Agent A：检查业务逻辑和边界条件
Agent B：检查安全、认证、权限问题
Agent C：检查测试覆盖
Agent D：检查性能和可维护性
Agent E：检查 UI/UX、移动端、可访问性

不要修改代码。最后合并成一份 review 报告，按严重程度排序。

适用的时候别犹豫： 上线前审查、大型重构后检查、安全敏感功能、复杂 bug 定位、多模块改动——都比你自己一个个检查快得多。

10. 别每次都写长提示词，封装成 Skill

Skill 是把说明、资源和可选脚本打成一个任务能力包，让 Codex 每次都能可靠地跑同一套流程。

说白了就是：今天花十分钟封装，以后每次只用一句话调用。

比如创建一个 frontend-polish Skill：

---
name: frontend-polish
description: 改善 UI 质量、布局、响应式、可访问性、加载状态等。
---

触发时：
1. 检查受影响组件
2. 检查布局、间距、排版和响应式行为
3. 确保 loading、empty、error 状态存在
4. 检查可访问性标签和键盘导航
5. 避免修改无关业务逻辑
6. 运行 typecheck / build
7. 总结视觉和行为变化

之后只需要一句：

$frontend-polish 请优化当前 dashboard 页面，但不要改业务逻辑。

一套好用的 Skill 库，是你和 Codex 之间最保值的投资。

11. 高频操作用自定义 Slash Command 一键搞定

把常用的工作流程压成自定义命令，一次定义，以后打几个字就触发。

值得创建的几个：

/deep-review、/fix-tests、/refactor-safely、/security-audit、/frontend-polish

比如 /deep-review 你可以这样写：

请深度 review 当前 diff。
检查：correctness、edge cases、security、performance、tests、maintainability、是否遵循 AGENTS.md。
不要修改代码。按 P0 / P1 / P2 输出。

以后每次上线前 /deep-review 就行，不用重新组织语言。

12. MCP 让 Codex 不只是"看着代码"

MCP（Model Context Protocol）打破了"Codex 只能看本地代码"的局限，让它能接入你的外部工作台。

它能连上的东西：

• GitHub — 读 issue、PR、CI 结果
• Linear / Jira — 读任务和验收标准
• Figma — 读设计稿
• Sentry — 读线上报错
• Notion — 读产品文档

有了这些上下文，Codex 不再是"只认代码"，而是更贴近你在做的事：

请读取这个 Linear ticket 的验收标准，再检查当前代码是否满足。如果不满足，先给实现计划，不要修改代码。

13. 长会话久了，给上下文"喘口气"

任务做得久了，Codex 可能会慢慢忘记前面的约束。这不是它不听话，是上下文太长了。

用 /status 看看当前消耗，然后主动整理一下：

请总结当前任务状态：

1. 原始目标
2. 已做改动
3. 已确认的决策
4. 失败过的尝试
5. 当前剩余问题
6. 下一步计划
7. 需要继续遵守的约束

后续请基于这个摘要继续。

定期"整理战场"是个好习惯，后面的工作会顺畅很多。

14. 8 个高频模板，拿来就能用

以下是我日常用得最多的 8 个模板，基本覆盖了大部分场景。

A. 读项目

请只读项目，不要修改文件。
输出：项目目标、技术栈、目录结构、核心数据流、关键文件、启动 / 测试 / 构建命令、潜在风险。

B. 做功能

请实现【功能】。先给计划，不要马上改。确认计划后再实现。实现后运行测试并总结。

C. 修 Bug

先复现 → 找根因 → 给最小修复方案 → 修改最少代码 → 补充回归测试 → 跑测试 → 总结风险。

D. 重构

目标：提升可读性和可维护性。
约束：外部行为不变、API 不变、不新增依赖、每一步都保持测试通过。
先列出重构计划和风险。

E. 写测试

覆盖：正常路径、边界条件、错误输入、权限问题、回归场景。
不要为了让测试通过而修改业务逻辑，除非发现真实 bug。

F. Review

请 review 当前 diff，不要修改代码。
重点：逻辑 bug、安全问题、边界条件、性能问题、缺失测试、过度复杂、是否违反 AGENTS.md。
按严重程度输出。

G. 写文档

生成 README：项目介绍、功能列表、技术栈、本地运行、环境变量、测试命令、部署方式、常见问题。

H. 复盘沉淀

总结这次任务中可以沉淀到 AGENTS.md 的规则。
输出：新增规则、为什么需要、应放在哪个章节、是否会影响未来任务。

15. 一条流水线，每次任务照走就行

每次任务都按这 13 步来，稳得住：

1. 明确目标
2. 明确范围
3. 明确不做什么
4. 明确验收标准
5. 让 Codex 只读分析
6. 让 Codex 给出计划
7. 你确认计划
8. 小步实现
9. 跑测试
10. Review diff
11. 修复 review 问题
12. 更新文档
13. 沉淀规则到 AGENTS.md / Skill

还有一个万能起手模板，新建会话时直接丢给它：

你是我的 Codex 专家级编程搭档。

工作规则：

1. 不要急着写代码
2. 先阅读相关文件
3. 先说明你理解的目标、范围、风险
4. 给出计划后等待确认
5. 修改时保持最小改动
6. 不要无理由新增依赖
7. 修改后必须运行相关测试
8. 如果测试无法运行，说明原因和手动命令
9. 最后输出改动摘要、测试结果、潜在风险
10. 发现可复用经验时，建议写入 AGENTS.md 或 Skill

当前任务：【写你的任务】
验收标准：【写怎样算完成】

16. 自检：你跟 Codex 到哪一步了

以下 10 条，做到一半以上，你已经在正确的路上了：

1. 不再写模糊提示词，而是给目标、范围、约束、验收标准
2. 每个项目都有 AGENTS.md
3. 大任务先 /plan，长任务用 /goal
4. 按风险切换权限，而不是一直全开放
5. 每次改完都要求测试、lint、typecheck、build
6. 用 /review 和 subagents 做多角度审查
7. 把重复流程封装成 Skill 或自定义命令
8. 用 MCP 接入 issue、设计稿、日志、文档等上下文
9. 让 Codex 复盘，把经验沉淀下来
10. 永远不盲信 Codex，最后拍板的人是你自己

最后一句话：Codex 帮你跑得快，但方向盘永远在你手里。它负责高强度的执行，你负责做工程师该做的判断。把 Codex 放进一套好的工作流里，它才能成为你真正靠谱的搭档。

参考来源： Codex CLI — OpenAI Developers