Codex辅助软件开发实用教程

正式使用前：写好 AGENTS.md

Codex 的项目级说明文件叫：AGENTS.md，它类似 Claude Code 的 CLAUDE.md，用于告诉 Codex 项目规则、运行方式、测试命令、代码风格、Review 标准。

Codex 在开始工作前会读取 AGENTS.md，并支持全局、项目、子目录多层级指令。

在项目根目录创建AGENTS.md

示例：

# AGENTS.md

## Project Overview

这是一个 SaaS 管理后台项目。

## 技术栈

- Frontend: React + TypeScript + Vite
- Backend: Node.js + NestJS
- Database: PostgreSQL
- Package manager: pnpm

## 常用命令

- 安装依赖：pnpm install
- 启动开发环境：pnpm dev
- 类型检查：pnpm typecheck
- 代码检查：pnpm lint
- 单元测试：pnpm test
- 构建：pnpm build

## 开发规则

- 修改业务逻辑必须补充或更新测试。
- 不要随意新增生产依赖，新增前必须说明原因。
- 不要直接修改数据库迁移文件，除非明确要求。
- 不要自动提交 Git，除非我明确说"提交"。
- 大型重构必须先给方案，再执行。
- 修改完成后必须说明改动文件、验证命令和测试结果。

## 审查规则

- 重点检查安全风险、权限绕过、边界条件、并发问题、数据一致性问题。
- PR 描述必须包含背景、主要改动、测试情况、风险和回滚方案。

个人偏好可以放到：~/.codex/AGENTS.md，项目规则放在仓库根目录的 AGENTS.md；更具体的子模块规则可以放在子目录里，Codex 会按目录层级组合这些说明。

需求分析阶段：先让 Codex 读代码，不要直接开写

需求不清楚时，不要一上来就让 Codex 实现功能。先让它做影响范围分析。

示例 1：理解已有功能

请分析当前项目中的"用户登录"功能实现链路。
要求：
1. 找到前端入口、API 调用、后端 controller/service、数据库相关代码；
2. 输出文字版调用链；
3. 说明当前实现有哪些潜在问题；
4. 不要修改任何文件。

示例 2：评估新需求影响范围

我准备新增"手机号验证码登录"功能。
请先分析影响范围：
1. 前端页面和组件；
2. 后端接口；
3. 验证码存储方式；
4. 鉴权逻辑；
5. 数据库或缓存影响；
6. 测试用例；
7. 安全风险。
先不要写代码。

示例 3：陌生项目 onboarding

我第一次接触这个项目。
请生成一份 onboarding 文档，包括：
1. 项目用途；
2. 技术栈；
3. 目录结构；
4. 核心模块；
5. 本地启动方式；
6. 常见开发任务；
7. 新人最容易踩坑的地方。
不要修改文件。

这一步的重点是：让 Codex 先建立代码库上下文，再进入实现。

方案设计阶段：让 Codex 输出可审查计划

中大型需求，建议先让 Codex 出计划：

请为"手机号验证码登录"制定技术方案。
要求：
1. 先分析现有认证模块；
2. 给出最小可行实现方案；
3. 列出需要新增和修改的文件；
4. 设计接口参数和返回值；
5. 设计数据库表；
6. 说明安全风险；
7. 给出测试计划；
8. 不要修改文件，等我确认。

对于迁移类任务，可以要求 Codex 先做 inventory，再分 checkpoint 迁移。

开发实现阶段：本地用 CLI / IDE，复杂任务用 Cloud

本地交互式开发

进入项目：

codex --sandbox workspace-write --ask-for-approval on-request

然后输入：

按照刚才确认的方案开始实现。
要求：
1. 每次只完成一个小步骤；
2. 修改前说明将要改哪些文件；
3. 修改后运行相关测试；
4. 如果测试失败，先分析原因再修复；
5. 不要提交 Git。

适合本地处理的任务：

修一个具体 bug
补测试
重构一个模块
修 TypeScript 类型错误
优化一个 API
根据日志定位问题

非交互式执行：codex exec

脚本化任务用：

codex exec "请分析当前 git diff，指出潜在 bug 和安全风险"

或者短写：

codex e "请总结这个项目的技术栈和核心模块"

codex exec 用于脚本或 CI 风格的非交互式运行，可以把结果输出到 stdout 或 JSONL，也可以恢复之前的会话。

也可以通过 stdin 传入内容：

git diff | codex exec "请 review 这个 diff，输出高风险问题"

云端并行任务：Codex Cloud

云端任务适合"可以独立完成、可以开 PR、可以并行"的任务，例如：

补充订单模块测试
修复一个非阻塞 bug
升级某个依赖
迁移一个组件库
生成 API 文档
处理一个 GitHub issue

在 CLI 中可以直接发起云端任务：

codex cloud exec --env ENV_ID "请为订单模块补充单元测试，并创建 PR"

如果想让 Codex 生成多个候选方案，可以用：

codex cloud exec --env ENV_ID --attempts 3 "请给出三种实现手机号验证码登录的方案，并分别创建可审查改动"

codex cloud 可以在终端里查看、启动和处理 Codex Cloud 任务；--attempts 支持 1--4 次 best-of-N 运行。

测试阶段：让 Codex 形成闭环

不要只说"写测试"，而是让它完成测试闭环：

请为刚才的改动补充测试。
要求：
1. 先说明应该覆盖哪些场景；
2. 使用项目现有测试框架；
3. 不引入新的测试库；
4. 写完后运行相关测试；
5. 如果测试失败，先分析原因再修复。

不要只让 Codex 做代码改动，还应该让它创建或更新测试、运行相关检查、确认行为符合需求、Review diff。

常用提示词：

请运行 lint、typecheck 和相关测试。
如果失败：
1. 判断是代码问题、测试问题还是环境问题；
2. 先解释根因；
3. 再做最小修复。

请为这个 bug 增加回归测试。
要求测试必须在修复前失败、修复后通过。

代码 Review 阶段：让 Codex 做第二审查人

本地 Review：

请 review 当前 git diff。
重点检查：
1. 逻辑 bug；
2. 安全风险；
3. 权限绕过；
4. 并发问题；
5. 数据一致性；
6. 边界条件；
7. 测试缺失；
8. 是否符合 AGENTS.md。
只输出问题清单，不要修改文件。

Codex 也支持 /review 这类 Review 工作流，可以 review base branch、未提交改动、某个 commit，并可结合团队自己的 code_review.md 和 AGENTS.md 形成统一 Review 标准。

GitHub PR Review：

@codex review

GitHub 集成支持在 PR 评论里用 @codex review 触发 Review，也可以开启自动 Review；Codex 会基于 PR diff 和仓库指导发出 GitHub code review，重点聚焦高优先级问题。

Git 与 PR 阶段

让 Codex 总结改动

请查看当前 git diff，总结本次改动。
要求：
1. 按文件分组；
2. 说明每个文件为什么改；
3. 说明是否有风险；
4. 不要提交。

生成 commit message

请根据当前 git diff 生成 Conventional Commit message。
要求：
1. 标题不超过 72 个字符；
2. body 说明主要改动；
3. footer 标注 breaking change，如果有。

生成 PR 描述

请根据当前分支相对 main 的 diff 生成 PR 描述。
包括：
1. 背景；
2. 主要改动；
3. 测试情况；
4. 风险点；
5. 回滚方案。

如果使用 Codex App，它内置 diff 面板，可以查看改动、添加行内反馈、stage / revert 具体 chunk，也可以直接 commit、push、创建 PR。

并行开发：一个任务一个线程 / worktree

Codex 的强项之一是并行处理任务。建议规则是：

一个任务 = 一个 Codex thread
一个较大需求 = 多个子任务
一个可独立合并的改动 = 一个 PR

Codex App 支持在多个项目中运行 thread，也支持 worktree；可以明确要求：

为这个项目在worktree中创建一个单独的thread来更新测试。

也可以要求 Codex 在 worktree 中创建独立后台 thread 来处理任务。

适合并行拆分：

线程 A：实现验证码发送接口
线程 B：实现前端验证码登录页
线程 C：补充认证模块测试
线程 D：更新接口文档
线程 E：Review 安全风险

对于复杂 Review，Codex 还支持显式要求启动多个 subagents，并在它们完成后汇总结果；让不同 agent 分别检查 security、code quality、bugs、race、test flakiness、maintainability。

上线前：安全、权限、配置检查

上线前可以让 Codex 做一次发布检查：

请做一次上线前检查。
重点包括：
1. 配置项是否完整；
2. 环境变量是否有默认值；
3. 日志是否包含敏感信息；
4. 权限校验是否完整；
5. 数据库迁移是否可回滚；
6. 是否有破坏性变更；
7. 测试是否覆盖关键路径。
只输出检查结果，不要修改文件。

也可以要求 Codex Security 做安全扫描。Codex Security 可以通过插件或 cloud 扫描代码变更和仓库，帮助发现和修复潜在漏洞；Codex Security cloud 适用于连接 GitHub 仓库的用户，并会基于仓库上下文验证高信号问题。

上线后维护：Automations

Codex App 支持 Automations，用于定时或周期性任务。例如：

每天上午 9 点检查 main 分支最近 24 小时的失败测试，并生成报告。

每周一检查项目依赖是否有安全更新，输出建议，不要直接升级。

每 30 分钟检查这个 PR 是否有新的 review feedback，如果有，请整理成待办清单。

自动化任务可以在 dedicated background worktree 或项目目录中运行，结果会进入 Triage；但 full access 的后台自动化风险更高，建议谨慎设置 sandbox 和 rules。

权限与安全建议

Codex 有 sandbox 和 approval 两个核心安全控制。建议新手从默认权限开始，保持 approval 和 sandbox 严格，只在可信仓库或明确工作流中逐步放宽。

推荐默认：

codex --sandbox workspace-write --ask-for-approval on-request

不推荐日常使用：

codex --dangerously-bypass-approvals-and-sandbox

CLI 文档明确提示，绕过审批和沙箱是危险模式，只应在隔离 runner 中使用。

如果要管控命令，可以用 rules。Codex rules 支持 allow、prompt、forbidden 三种决策，用于允许、提示或阻止某类命令。

完整实战流程示例：新增"手机号验证码登录"

第 1 步：启动 Codex

cd your-project
codex --sandbox workspace-write --ask-for-approval on-request

第 2 步：让它读代码

请分析当前登录认证模块。
要求：
1. 找到前端登录页；
2. 找到后端登录接口；
3. 找到 token 生成和校验逻辑；
4. 找到用户表结构；
5. 找到现有测试；
6. 不要修改文件。

第 3 步：出方案

我要新增手机号验证码登录。
请先给技术方案：
1. 最小可行实现；
2. API 设计；
3. 验证码存储策略；
4. 安全限制，比如频率限制、过期时间、防刷；
5. 需要修改的文件；
6. 测试计划；
7. 风险和回滚方案。
不要写代码。

第 4 步：小步实现

按照确认后的方案执行第 1 步。
每完成一步就停下来说明：
1. 改了哪些文件；
2. 为什么这样改；
3. 运行了哪些测试；
4. 下一步是什么。

第 5 步：测试闭环

请补充验证码登录的测试。
覆盖：
1. 正常登录；
2. 验证码错误；
3. 验证码过期；
4. 频率限制；
5. 未注册手机号；
6. 重放攻击。
写完后运行相关测试。

第 6 步：Review

请 review 当前 git diff。
重点检查安全风险、权限绕过、边界条件、测试缺失。
只输出问题清单，不要修改文件。

第 7 步：生成 PR

请根据当前 diff 生成 PR 描述。
包括背景、主要改动、测试情况、风险点和回滚方案。

推荐提示词模板

需求影响分析

请分析以下需求对当前项目的影响：
【需求】

要求：
1. 找到相关模块；
2. 输出调用链；
3. 列出需要修改的文件；
4. 说明数据库/API/前端影响；
5. 说明测试范围；
6. 说明风险；
7. 不要修改文件。

功能开发

请实现以下功能：
【功能描述】

要求：
1. 遵循 AGENTS.md；
2. 先给实现计划；
3. 小步修改；
4. 每步后运行相关测试；
5. 不做无关重构；
6. 不自动提交 Git。

Bug 修复

请修复以下 bug：
【bug 描述】

要求：
1. 先定位根因；
2. 给出最小修复方案；
3. 增加回归测试；
4. 运行测试验证；
5. 总结修复文件和风险。

重构

请重构以下模块：
【模块路径】

目标：
1. 保持外部行为不变；
2. 不改变公共 API；
3. 降低复杂度；
4. 保留或增加测试；
5. 每个 checkpoint 后运行验证命令。

PR Review

请 review 当前分支相对 main 的 diff。
重点检查：
1. P0/P1 级别 bug；
2. 安全风险；
3. 数据一致性；
4. 并发问题；
5. 测试缺失；
6. 回滚风险。
只输出高价值问题，不要泛泛而谈。

团队落地规范

建议团队这样使用 Codex：

1. 每个仓库必须有 AGENTS.md。
2. 大需求必须先让 Codex 输出方案，不允许直接开写。
3. 一个 Codex thread 只处理一个明确任务。
4. 本地执行用 workspace-write + on-request。
5. 不允许默认开启危险全权限。
6. 所有代码变更必须跑 lint、typecheck、test。
7. 所有 PR 必须经过人工 Review。
8. Codex Review 作为第二审查人，不替代人类负责人。
9. 云端任务适合并行和 PR 化，不适合直接操作生产环境。
10. Automations 先从只读报告开始，再逐步开放写权限。

最终建议：

如果你是个人开发者，先用 Codex CLI + IDE 插件。 如果你有多个任务并行，加入 Codex App / Cloud。 如果你是团队使用，一定要接 GitHub Review、AGENTS.md、权限规则和自动化。