夜雨聆风AI观察-期望你读完有一点点收获
前几天，OpenAI 官方亲自下场，发布了一份内部文档，教你怎么用 Codex。
《How OpenAI uses Codex》，13 页，没有花哨设计，就是白底黑字。文档分了 7 个使用场景和 6 条最佳实践。我们一个一个来看。
OpenAI 的众多技术团队，例如安全、产品工程、前端、API、基础设施和性能工程团队，每天都在使用 Codex。
团队利用 Codex 加速完成各种工程任务，从理解复杂系统和重构大型代码库，到在紧迫的期限内发布新功能和解决突发事件。
他们通过对 OpenAI 工程师的访谈和内部使用数据，整理了一系列用例和最佳实践，重点介绍了 Codex 如何帮助我们的团队更快地行动、提高工作质量并大规模地管理复杂性。
所以说是"官方发布"可能不太准确——因为这是对 OpenAI 工程师的访谈 + 内部使用数据。也就是说，不是产品经理写的宣传稿，是工程师们实际工作方式的复盘。
01 代码理解
什么时候用：入职交接、调试、处理线上事故
Codex 帮助我们的团队在新员工入职、调试或调查事件时，快速掌握代码库中不熟悉的部分。
他们经常使用 Codex 来定位功能的核心逻辑，绘制服务或模块之间的关系图，并追踪系统中的数据流。它还有助于发现架构模式或缺失的文档，否则这些文档需要耗费大量人工才能生成。
工程师原话：
"When I'm on-call, I paste the stack trace and ask Codex where the auth flow lives. It jumps straight to the right files so I can triage fast."
翻译：值班的时候，把报错堆栈贴给 Codex，问"认证流程在哪"。Codex 直接跳到正确的文件，快速分类处理。
另一个例子：
"Codex answers my 'Where would I do this?' repo questions across Terraform and Python way faster than grep."
翻译：Codex 回答我在 Terraform 和 Python 代码库中的"这个需求在哪里实现"的问题，比 grep 快得多。
推荐 prompt：
·"Where is the authentication logic implemented in this repo?" 翻译：这个代码库中认证逻辑在哪里实现的？
·"Summarize how requests flow through this service from entrypoint to response." 翻译：总结请求是如何从入口点到响应的流程经过这个服务的。
·"Which modules interact with [insert module name] and how are failures handled?" 翻译：哪些模块与 [模块名] 交互，失败是如何处理的？
02 重构和迁移
什么时候用：更新 API、改变实现模式、迁移依赖
Codex 通常用于对多个文件或包进行更改。例如，当工程师更新 API、更改模式的实现方式或迁移到新的依赖项时，Codex 可以轻松地实现更改的一致性。
当需要在数十个文件中进行相同的更新，或者更新需要了解难以通过正则表达式或查找替换轻松识别的结构和依赖关系时，Codex 尤其有用。
这是 Codex 最实用的场景之一。跨多个文件或包的变更——用正则或查找替换最容易出错，但是 Codex 能理解结构和依赖关系。
工程师原话：
"Codex swapped every legacy getUserById() for our new service pattern and opened the PR. It did in minutes what would've taken hours."
翻译：把所有遗留的 getUserById() 换成了新的服务模式，还开了 PR。几分钟完成了原本需要一个小时的工作。
另一个例子：
"To clear launch blockers, I have Codex scan for every instance of the old pattern, summarize the impact in Markdown, then open PRs with the fixes."
翻译：为了清除发布障碍，让 Codex 扫描所有旧模式的实例，用 Markdown 总结影响范围，然后开 PR 修复。
推荐 prompt：
·"Split this file into separate modules by concern and generate tests for each one." 翻译：把这个文件按关注点拆分成独立的模块，并为每个模块生成测试。
·"Convert all callback-based database access to async/await." 翻译：将所有基于回调的数据库访问转换为 async/await。
03 性能优化
什么时候用：调优、可靠性改进、识别技术债务
在进行性能调优或可靠性优化时，他们的工程师会调用 Codex 分析缓慢或内存密集型的代码路径，例如低效的循环、冗余操作或开销巨大的查询，并提出优化的替代方案，从而显著提升效率和可靠性。
Codex 还用于维护代码健康，识别仍在使用的风险或已弃用的代码模式。我们的团队依靠 Codex 来帮助减少长期技术债务并主动预防回归问题。
工程师原话：
"I use Codex to scan for repeated expensive DB calls. It's great at flagging hot paths and drafting batched queries I can later tune."
翻译：我用 Codex 扫描重复的昂贵数据库调用。它很擅长标记热点路径，并起草可以后续优化的批量查询。
另一个例子：
"Codex is great for spotting performance issues quickly— I save 30 minutes of work by spending 5 minutes on a prompt."
翻译：Codex 非常擅长快速发现性能问题——花 5 分钟写 prompt，省 30 分钟工作。
推荐 prompt：
·"Optimize this loop for memory efficiency and explain why your version is faster." 翻译：优化这个循环的内存效率，并解释为什么你的版本更快。
·"Find repeated expensive operations in this request handler and suggest caching opportunities." 翻译：找出这个请求处理器中重复的昂贵操作，并建议可以缓存的地方。
·"Suggest a faster way to batch DB queries in this function." 翻译：建议一个更快的方式来批量处理这个函数中的数据库查询。
04 提升测试覆盖
什么时候用：覆盖率薄弱的模块、新代码的测试、边界条件
Codex 可以帮助工程师更快地编写测试——尤其是在测试覆盖率低或完全缺失的情况下。
在进行 bug 修复或重构时，工程师经常会请求 Codex 生成覆盖边界情况或可能出现故障路径的测试。对于新代码，它可以根据函数签名和周围逻辑生成单元测试或集成测试。
Codex 对识别边界条件特别有帮助：空输入、最大长度、异常但有效的状态——这些在初始测试中经常被遗漏。
工程师原话：
"I point Codex at low-coverage modules overnight and wake up to runnable unit-test PRs."
翻译：睡前把 Codex 指向低覆盖率模块，醒来就有可运行的单元测试 PR。
另一个例子：
"When switching mono-repo branches is painful, I have Codex write the tests and kick-off CI while I keep working on my branch."
翻译：切单仓分支很痛苦的时候，让 Codex 写测试并启动 CI，自己继续在原分支工作。
推荐 prompt：
·"Write unit tests for this function, including edge cases and failure paths." 翻译：写这个函数的单元测试，包括边界情况和失败路径。
·"Generate a property-based test for this sorting utility." 翻译：生成这个排序工具的属性测试。
·"Extend this test file to cover missing scenarios around null inputs and invalid states." 翻译：扩展这个测试文件，覆盖空输入和无效状态等遗漏的场景。
05 提升开发速度
什么时候用：项目启动、临近发布、处理用户反馈
Codex 在开发周期的两端都起作用：
启动阶段：生成样板代码——文件夹、模块、API 存根，快速搭建可运行的代码框架。
发布阶段：处理小而重要的任务——分类 bug、填补最后几行实现、生成发布脚本、配置文件等等。
工程师原话：
"I was in meetings all day and still merged 4 PRs because Codex was working in the background."
翻译：开了一整天会，还是合并了 4 个 PR——因为 Codex 在后台工作。
另一个例子：
"Codex helped ship 3-4 low-priority fixes perfectly that would've languished in the backlog, which was super empowering."
翻译：Codex 帮我完美地处理了 3-4 个低优先级修复，这些原本会在 backlog 里积灰——这非常有成就感。
推荐 prompt：
·"Scaffold a new API route for POST /events with basic validation and logging." 翻译：为 POST /events 搭建一个新的 API 路由，包含基本的验证和日志。
·"Generate a telemetry hook for tracking success/failure of the new onboarding flow, using this template [example]." 翻译：生成一个遥测钩子来追踪新引导流程的成功/失败，使用这个模板 [示例]。
·"Create a stub implementation based on this spec: [spec content]." 翻译：基于这个规格说明创建一个存根实现：[规格内容]。
06 保持高效工作状态
什么时候用：日程碎片化、频繁被打断、值班期间
这是我觉得最有趣的一个场景。
OpenAI 的工程师用 Codex 来捕获未完成的工作、把笔记转成可工作的原型、启动可以稍后回顾的探索性任务。
核心洞察：当日程被会议和值班打断时，Codex 让你可以暂停和恢复工作而不丢失上下文。
工程师原话：
"If I spot a drive-by fix, I fire a Codex task instead of swapping branches and review its PR when I'm free."
翻译：看到一个顺手可以修的小问题，不切换分支，直接让 Codex 处理任务，有空的时候再 review PR。
另一个例子：
"I routinely forward Slack threads, Datadog traces, issues and more to Codex so I can stay focused on high priority work."
翻译：我经常把 Slack 讨论、监控告警、issue 都转发给 Codex，这样我能专注在高优先级工作上。
推荐 prompt：
·"Generate a plan to refactor this service and split it into smaller modules." 翻译：生成一个重构这个服务的计划，并拆分成更小的模块。
·"Stub out the retry logic and add a TODO — I'll fill in the backoff logic later." 翻译：先把重试逻辑的框架写出来，加上 TODO——我后续再填入退避逻辑。
·"Summarize this file so I can pick up where I left off tomorrow." 翻译：总结这个文件，这样我明天可以接着继续。
07 探索和构思
什么时候用：寻找替代方案、验证设计决策、识别相关 bug
Codex 还被工程师用于开放式工作：提示不同的解决问题方式、探索不熟悉的模式、压力测试假设。
它也被用来识别相关 bug——给定一个已知问题或废弃方法，Codex 可以在代码其他地方找到类似模式。
工程师原话：
"Codex helps me solve the cold-start problem — I paste a spec and docs and it scaffolds code or shows me what I forgot."
翻译：Codex 帮我解决冷启动问题——把规格说明和文档贴进去，它会生成代码框架，或者提醒我遗漏了什么。
另一个例子：
"After I fix a bug I ask Codex where similar bugs might lurk, then spin follow-up tasks."
翻译：修完一个 bug，问 Codex 类似的 bug 可能藏在哪里，然后启动后续任务。
推荐 prompt：
·"How would this work if the system were event-driven instead of request/response?" 翻译：如果系统是事件驱动而不是请求/响应模式，这个会怎么工作？
·"Find all modules that manually build SQL strings instead of using our query builder." 翻译：找出所有手动拼接 SQL 字符串的模块，而不是使用我们的查询构建器。
·"Rewrite this in a more functional style, avoid mutation and side effects." 翻译：用更函数式的方式重写，避免状态变更和副作用。
08 六条最佳实践
文档后半部分总结了六条最佳实践。
第一条：从 Ask 模式开始
对于大改动，先用 Ask 模式让 Codex 生成实现计划，然后再切换到代码模式执行。
这个实践也是我平时用的最多的一条，因为只有让你和AI在实现过程中达成实现细节上的一致，最终的结果基本上比较满意。
原文：
"For large changes, start by prompting Codex for an implementation plan using Ask mode, which then becomes the input for follow-up prompts when you switch to Code Mode."
翻译：对于大改动，先用 Ask 模式生成实现计划，这个计划会成为切换到代码模式后后续 prompt 的输入。
第二条：迭代改进 Codex 的开发环境
设置启动脚本、环境变量、网络访问，能显著降低 Codex 的错误率。
原文：
"Setting a startup script, environment variables, and internet access significantly reduces Codex's error rate."
翻译：设置启动脚本、环境变量和网络访问，能显著降低错误率。
第三条：像写 GitHub Issue 一样写 prompt
提示词中包含文件路径、组件名称、diff 和文档片段。只有告诉更加详细明确的信息，Codex才不会胡乱搜索。
这条在我将设计稿转为实现的时候，我会明确指定现在要帮我实现的那个页面，会指定文件完整路径，并指定文件中设计页面的名称，最终实现还原都是比较好的，返工次数基本上很少。
原文：
"Codex responds better when prompts mirror how you'd describe a change in a PR or issue."
翻译：Codex 在 prompt 模仿你在 PR 或 issue 中描述变更的方式时表现更好。
第四条：把 Codex 任务队列当作轻量级 backlog
不指望一次生成完整 PR。
原文：
"There's no pressure to generate a full PR in one go. Codex works well as a staging area you can return to when you're back in focus."
翻译：Codex 适合作为一个暂存区，你可以在重新专注时回来处理。
第五条：用 AGENTS.md 提供持久上下文
维护一个 AGENTS.md 文件，帮助 Codex 在代码库中更有效地工作。
这条应该是必须的，需要你制定项目规范和个人规范，这样可以有效约束Codex，完成的工作也会让你满意。
原文：
"These files typically include naming conventions, business logic, known quirks, or dependencies Codex can't infer from the code alone."
翻译：内容包括命名约定、业务逻辑、已知怪癖，或 Codex 仅凭代码无法推断的依赖关系。
第六条：利用"Best of N"改进输出
同时为单个任务生成多个响应，快速探索多种解决方案并挑选最好的。
原文：
"For more complicated tasks, you can review several iterations and combine parts of different responses to get a stronger result."
翻译：对于复杂任务，可以审查多个迭代，组合不同响应的部分，得到更强的结果。
我的感受
OpenAI 的工程师在给到 prompt 时，都指向一个具体的功能、一个明确的问题、一个可执行的动作。这里的提示词一定是要明确的，你们是否经常会给到“帮我优化下代码”、“写一个好看的页面”等等提示词。
如果是我，我会改成：
“先帮我分析下下面的代码，找出可以优化的内容，给出优化的具体实施方案，待我明确后再执行。”
“按照我上传的design.md来设计页面”或者“给出好看页面的参考或者design.md，我确认后，再按照此design.md来修改”
区别在哪？
模糊的 prompt 把判断和决策交给了 AI。具体的 prompt 把判断和决策留给了工程师，只让 AI 执行。
如果你还不确定要什么，先用 Ask 模式——这也是文档第一条最佳实践。
知道要什么的人，用具体 prompt 让 Codex 执行；还不知道要什么的人，用 Ask 模式让 Codex 帮你想。
两种用法，没有对错，但前提都是：不要模糊。
写在最后
这份文档的结尾很克制：
"Codex is still in research preview, but it's already making a real impact in how we build, helping us move faster, write better code, and take on work that would've otherwise never been prioritized."
翻译：Codex 仍在研究预览阶段，但它已经在我们构建产品的方式上产生了真实影响——帮助我们走得更快，写更好的代码，承担那些原本不会被优先处理的工作。
但作为一个读者，我看到的是：一家 AI 公司，正在用 AI 重构自己的工作方式。
而且他们把过程公开了——不是作为产品宣传，而是作为工程实践分享。
这份文档的价值，不在于告诉你 Codex 能做什么，而在于展示了一种可能性：
当 AI 成为工作流的基础设施，而不是一个需要刻意使用的工具，会发生什么
OpenAI 正在用自己的日常工作回答这个问题。
