Codex 深度实战指南

一、Codex 的本质：它到底在做什么

理解代码补全 vs 代码生成

Codex 不是在"写代码"，它在做概率预测——给定前面的 token，预测下一个最可能的 token。这意味着：

你给的上下文越精确，它的预测越准
你给的上下文越模糊，它越倾向于"平均"方案

这个认知会影响你所有 Prompt 策略。

为什么 Codex 有时"不听话"

你：写一个高性能的排序算法
Codex：给你一个快排

你：用 Rust 写一个 SIMD 优化的排序算法，处理 10 亿条 u64，
    目标是比 std::sort 快 2 倍，内存限制 1GB
Codex：给你一个真正优化过的实现

区别在于：第一种给了太多自由度，模型会选"最常见"的方案。第二种通过约束把解空间缩小了。

二、Prompt 工程：从入门到精通

层级一：基础 Prompt（大多数人止步于此）

"写一个函数，实现快速排序"

问题：得到的是教科书实现，不考虑你的项目、语言版本、性能要求。

层级二：带约束的 Prompt

"""
实现快速排序，要求：
- Python 3.11+
- 原地排序，O(1) 额外空间
- 支持自定义比较函数
- 对已排序数组退化为 O(n log n)
- 类型注解完整
"""

进步：有明确的技术约束，结果更可控。

层级三：上下文注入 Prompt（真正高效的方式）

"""
我的项目使用 Python 3.11，数据结构如下：

@dataclass
class Record:
    id: int
    score: float
    created_at: datetime

records: list[Record]  # 约 100 万条

需要一个排序函数，按 score 降序排列，score 相同时按 created_at 升序。
数据已经在内存中，不能创建新列表（内存紧张）。
当前在 src/utils/sort.py 中实现。

参考项目中已有的 comparator 模式：src/utils/compare.py
"""

这种方式给了：

1. 精确的数据结构
2. 具体的排序规则
3. 性能约束
4. 文件位置
5. 项目中的参考模式

层级四：系统级 Prompt（构建 AI 编程助手）

messages = [
    {
        "role": "system",
        "content": """
你是一个 Python 后端工程师，工作在一个 FastAPI 项目中。

代码规范：
- 所有函数必须有类型注解
- 使用 async/await
- 错误用自定义 AppError 类抛出
- 日志用 structlog
- 不使用 print

项目结构：
- src/api/ — 路由
- src/services/ — 业务逻辑
- src/models/ — 数据模型
- src/utils/ — 工具函数

你写的代码会被资深工程师 Review，确保质量。
"""
    },
    {
        "role": "user",
        "content": "实现用户注册接口"
    }
]

层级五：Chain-of-Thought 代码生成

"""
我需要实现一个分布式锁。请按以下步骤思考：

1. 先分析需求：锁需要哪些特性？（互斥、防死锁、可重入？）
2. 评估方案：Redis SETNX vs Redlock vs ZooKeeper，各有什么 trade-off？
3. 选择方案并说明原因
4. 实现代码
5. 指出这个实现的已知限制

场景：单机 Redis，QPS 约 1000，锁持有时间 < 30 秒
"""

让模型先"想"再"做"，输出质量显著提升。

三、代码审查：让 Codex 做你的 Reviewer

基础审查（效果一般）

"审查这段代码"

进阶审查（按关注点分层）

"""
审查以下代码，按以下维度逐一分析：

1. 安全性
   - 有无注入风险（SQL/NoSQL/命令注入）
   - 敏感数据是否泄露（日志、错误信息）
   - 认证/授权是否完整

2. 正确性
   - 边界条件处理
   - 并发安全性
   - 资源泄漏（连接、文件句柄）

3. 性能
   - 时间复杂度
   - 空间复杂度
   - 有无不必要的 IO

4. 可维护性
   - 命名是否清晰
   - 职责是否单一
   - 是否便于测试

对每个问题给出严重程度：🔴 高 / 🟡 中 / 🟢 低

代码：
[粘贴代码]
"""

对比审查（最有价值）

"""
我有两版实现，请对比分析：

版本 A：
[代码 A]

版本 B：
[代码 B]

对比维度：
1. 性能差异（具体数据或大 O 分析）
2. 可读性
3. 可测试性
4. 错误处理的完整性
5. 你推荐哪个，为什么？有没有更好的方案？
"""

四、Codex API 高级技巧

技巧一：Few-Shot 代码生成

"""
我需要给项目中所有 API 接口添加统一的错误处理。

这是一个已有的接口实现（好的例子）：

@router.post("/users")
async def create_user(data: UserCreate):
    try:
        user = await user_service.create(data)
        return ApiResponse(data=user)
    except DuplicateError:
        raise AppError(code=409, message="用户已存在")
    except ValidationError as e:
        raise AppError(code=400, message=str(e))

请按照这个模式，实现以下接口：
1. POST /orders — 创建订单
2. GET /orders/{id} — 查询订单
3. PUT /orders/{id} — 更新订单
4. DELETE /orders/{id} — 删除订单

保持错误处理模式完全一致。
"""

通过"好例子"让模型理解你的模式。

技巧二：迭代式 Prompt

# 第一轮：生成基础版本
"实现一个 LRU Cache，支持 get 和 put 操作"

# 第二轮：补充约束
"加上以下要求：
1. 线程安全
2. 支持 TTL 过期
3. 容量满时淘汰最久未使用的"

# 第三轮：优化
"当前实现每次 get 都要加锁，性能不好。
改成读写锁，读操作不阻塞"

# 第四轮：补测试
"为这个 LRU Cache 写单元测试，覆盖：
- 基本 get/put
- 容量满时淘汰
- TTL 过期
- 并发访问"

每轮聚焦一个问题，比一次说清楚效果好得多。

技巧三：元 Prompt（让 Codex 帮你写 Prompt）

"""
我需要一个 Prompt，用来让 Codex 帮我生成 API 接口的单元测试。

要求：
1. Prompt 要能处理不同复杂度的接口
2. 要包含正常场景和异常场景
3. 要 mock 外部依赖
4. 要有清晰的输入输出描述

请帮我写这个 Prompt。
"""

技巧四：角色扮演

"""
你是一个有 10 年经验的数据库 DBA。

我在 PostgreSQL 中有这个查询，执行时间超过 5 秒：
[SQL 查询]

表结构：
[表结构]

数据量：users 表 500 万行，orders 表 2000 万行

请：
1. 用 EXPLAIN ANALYZE 的思路分析这个查询
2. 指出性能瓶颈
3. 给出优化方案（索引、重写查询、或其他方案）
4. 预估优化后的性能提升
"""

角色设定影响模型的"专家程度"。

五、Codex CLI vs Claude Code 深度对比

实际体验差异

什么时候用 Codex

1. OpenAI 生态项目：已经在用 OpenAI API，统一工具链
2. 简单脚本：一次性脚本，不需要项目理解
3. 探索性编码：快速试想法，不在乎项目风格
4. 特定模型优势：某些任务 GPT-4o 确实比 Claude 强

什么时候用 Claude Code

1. 正式项目开发：需要长期维护的项目
2. 多文件改动：涉及模块间协调的重构
3. 团队协作：CLAUDE.md + Skills 的团队配置
4. 深度集成：Git、CI/CD、MCP 的完整工作流

混合使用策略

探索阶段：用 Codex CLI 快速原型
  ↓
确定方案后：切到 Claude Code 正式实现
  ↓
Code Review：两个工具交叉审查
  ↓
最终确认：人工 Review

六、实战案例

案例一：从零构建一个 CLI 工具

"""
构建一个文件重复查找 CLI 工具。

需求：
1. 扫描指定目录，找出内容完全相同的文件
2. 支持排除目录（.git, node_modules）
3. 输出格式：JSON 或表格
4. 支持 dry-run 模式
5. 大文件用 MD5 而不是全量比对

技术要求：
- Python 3.11+
- 使用 click 做 CLI
- 使用 rich 做输出格式化
- 使用 asyncio + aiofiles 做异步 IO
- 使用 xxhash 代替 hashlib（更快）

请分步骤实现：
第一步：项目结构和 CLI 入口
第二步：文件扫描和哈希计算
第三步：重复检测算法
第四步：输出格式化
第五步：完整测试

先从第一步开始。
"""

案例二：数据库迁移脚本

"""
我需要一个 PostgreSQL 数据库迁移脚本。

当前状态：
- users 表有 id, name, email, created_at
- email 字段没有唯一约束
- 数据量：200 万行
- 有约 5% 的重复 email

目标状态：
- email 字段添加唯一约束
- 重复 email 只保留最新的那条
- 旧数据标记为 archived 而不是删除

约束：
- 迁移过程中服务不能停（零停机）
- 必须可回滚
- 需要进度日志

请：
1. 写出迁移 SQL
2. 写出回滚 SQL
3. 写出执行脚本（带进度显示和确认）
4. 分析风险点
"""

案例三：性能优化

"""
以下函数处理一个 CSV 文件，每行是一个交易记录。
当前处理 100 万行需要 45 秒，我需要优化到 5 秒以内。

当前实现：
[粘贴慢的代码]

约束：
- 不能用 pandas（依赖太重）
- 内存限制 512MB
- 必须保持输出格式不变

请：
1. 分析当前实现的性能瓶颈
2. 提出 3 个优化方案，分析各自的优劣
3. 实现最优方案
4. 给出优化前后的性能对比（理论分析）
"""

七、高级模式

模式一：Codex 作为代码转换器

"""
把以下 JavaScript 代码转换成 TypeScript，要求：
1. 保持所有函数签名和行为不变
2. 添加完整的类型定义
3. 处理 JS 中隐式的 undefined 情况
4. 导出所有公开接口的类型

代码：
[粘贴 JS 代码]
"""

模式二：Codex 作为文档生成器

"""
为以下代码生成：
1. JSDoc 注释（每个公开函数）
2. README 中的 API 文档章节
3. 错误码文档
4. 使用示例

代码：
[粘贴代码]
"""

模式三：Codex 作为测试生成器

"""
为以下函数生成测试用例。

要求：
- 使用 pytest
- 每个函数至少 5 个测试用例
- 覆盖：正常输入、边界条件、异常输入、类型错误
- 使用 parametrize 减少重复
- Mock 外部依赖

函数签名：
[粘贴函数签名和简要说明]
"""

模式四：Codex 作为架构分析师

"""
分析以下代码库的架构：

目录结构：
[粘贴 tree 输出]

关键文件内容：
[粘贴核心文件]

请分析：
1. 模块间的依赖关系（画 ASCII 依赖图）
2. 是否存在循环依赖
3. 哪些模块耦合过紧
4. 是否符合 SOLID 原则
5. 重构建议（按优先级排序）
"""

八、实战常见问题与处理

问题：Codex API 返回 429 Rate Limit

症状：请求被拒绝，提示 rate limit exceeded

原因：API 调用频率超过限制

# 解决：
# 方案一：加重试和退避
import time
import openai

def call_with_retry(client, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                max_tokens=4096,
                messages=[{"role": "user", "content": prompt}]
            )
        except openai.RateLimitError:
            wait = 2 ** attempt * 5  # 5s, 10s, 20s
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
    raise Exception("Max retries exceeded")

# 方案二：批量处理时加延迟
import time

prompts = ["task1", "task2", "task3"]
results = []
for p in prompts:
    result = call_with_retry(client, p)
    results.append(result)
    time.sleep(1)  # 每次请求间隔 1 秒

# 方案三：用 batch API（如果可用）
# 一次提交多个请求，价格更低，不触发实时限流

问题：Codex 生成的代码运行报错

症状：代码看起来没问题，但运行时报错

常见原因：
1. 导入了不存在的包
2. API 用了过时的版本
3. 类型不匹配
4. 环境差异（Python 版本、操作系统）

# 解决：
# 1. 让 Codex 先列出依赖
"这段代码需要哪些依赖？列出 requirements.txt"

# 2. 指定精确的版本
"用 Python 3.11，FastAPI 0.109，Pydantic v2"

# 3. 让 Codex 自己跑一遍
"写完代码后，写一个最小的测试用例验证它能运行"

# 4. 给 Codex 看错误信息
"运行报错了：[粘贴错误]，帮我修复"

问题：Codex CLI 响应很慢

症状：Codex CLI 执行命令后等很久才有输出

原因：
1. 用了大模型（GPT-4o 比 GPT-4o-mini 慢）
2. 输入上下文太长
3. 网络延迟

# 解决：
# 1. 简单任务用小模型
codex --model gpt-4o-mini "写一个 hello world"

# 2. 减少上下文
# 差：把整个项目文件都贴给 Codex
# 好：只贴相关的代码片段

# 3. 检查网络
curl -w "%{time_total}" -o /dev/null -s https://api.openai.com

问题：Codex 生成的代码风格不符合项目

症状：Codex 写的代码和项目其他代码风格不一致

原因：Codex 不了解你的项目规范

# 解决：
# 1. 在 system prompt 中定义风格
messages = [
    {
        "role": "system",
        "content": """
代码规范：
- 用 camelCase 命名变量和函数
- 用 PascalCase 命名类和接口
- 所有函数必须有 JSDoc 注释
- 用 async/await，不用 .then()
- 错误处理用 try-catch，不用 .catch()
"""
    },
    {
        "role": "user",
        "content": "写一个用户注册函数"
    }
]

# 2. 给参考代码
"参考这段代码的风格来写：[粘贴项目中的代码]"

# 3. 用 Few-Shot（见本章技巧一）

问题：Codex 生成了有安全漏洞的代码

症状：代码能跑，但有 SQL 注入、XSS 等安全问题

原因：Codex 倾向于生成"最简单"的实现，不考虑安全

# 解决：
# 1. 在 prompt 中明确安全要求
"实现用户登录接口，要求：
- 密码用 bcrypt 哈希，不要明文存储
- SQL 查询用参数化，不要拼接字符串
- 返回的 token 用 httpOnly Cookie
- 限制登录失败次数（5 次后锁定 15 分钟）"

# 2. 让 Codex 做安全审查
"审查这段代码的安全性，重点检查：
SQL 注入、XSS、CSRF、敏感数据泄露、认证绕过"

# 3. 用专门的安全工具配合
# npm audit、bandit（Python）、semgrep