How OpenAI Uses Codex Internally: 7 Engineering Scenarios and Practical Patterns

OpenAI's official PDF How OpenAI uses Codex describes how Codex is used across OpenAI's internal engineering teams. The document is based on interviews with OpenAI engineers and internal usage data. Its focus is not a single feature, but a practical question: when Codex is placed inside a complex, fast-moving software engineering environment, where does it actually help?

Note: this page is an editorial rewrite and structured summary based on the official OpenAI PDF. It covers the full structure and core ideas of the document, but it is not a verbatim repost.

Overview: Codex Is Part of OpenAI's Daily Engineering Workflow

Inside OpenAI, Codex is used by teams including Security, Product Engineering, Frontend, API, Infrastructure, and Performance Engineering. The work spans a broad range: understanding unfamiliar code, refactoring large codebases, shipping new features, responding to incidents, improving tests, and reducing technical debt.

The larger point is that Codex is not only useful for writing snippets of code. It can take on parts of the engineering workflow that require context gathering, planning, repetitive edits, test generation, and debugging support. In that sense, it behaves less like a code completion tool and more like an engineering collaborator that can operate inside a repository.

OpenAI groups its internal usage into 7 categories:

1. Code understanding
2. Refactoring and migrations
3. Performance optimization
4. Improving test coverage
5. Increasing development velocity
6. Staying in flow
7. Exploration and ideation

Let's walk through each one.

1. Code Understanding: Getting Oriented in Unfamiliar Systems

One of the most common engineering problems is finding the core logic inside a part of the codebase you do not know well. This comes up during onboarding, bug fixing, incident response, or when temporarily taking over a component. Before making a good decision, engineers often need to answer basic questions: Where is the entrypoint? How does the call chain work? Where does state change? How do failures propagate? Which modules depend on each other?

OpenAI teams use Codex to help answer those questions. Codex can locate the main implementation of a feature, explain relationships between services or modules, trace the flow of requests and data, and surface architecture patterns or missing documentation that would otherwise take time to reconstruct manually.

This is especially useful during incident response. An engineer may not be deeply familiar with the subsystem that is failing, but they can give Codex a stack trace, a log excerpt, or a symptom description and ask it to identify relevant files, component relationships, and likely paths through the system. That helps the human move faster from "where should I look?" to actual diagnosis.

Useful prompts:

• Where is authentication implemented in this repository?
• Explain how a request flows through this service from entrypoint to response.
• Which components interact with this module, and how are failure paths handled?
• Given this stack trace, identify the files and call chain most likely to be involved.

2. Refactoring and Migrations: Consistent Cross-File Changes

The second major use case is refactoring and migration work. Many engineering changes do not fit inside a single function. They span packages, directories, or dozens of files. Examples include API upgrades, replacing old implementation patterns, migrating to a new dependency, converting callback-style code to async/await, splitting oversized modules, or restructuring code to make future testing easier.

Simple search-and-replace is often not enough for this kind of work. The hard part is not just finding matching text; it is understanding what each call site means in context. Codex can apply changes while taking account of file structure, dependencies, local style, and existing implementation patterns.

OpenAI teams also use Codex for cleanup work: replacing obsolete patterns, splitting large files by responsibility, or first scanning for the impact of an old pattern before producing a Markdown summary and related pull requests. For launch blockers, this "scan, summarize, fix" workflow can be particularly valuable.

Useful prompts:

• Find all uses of the old service pattern and group them by impact.
• Split this large file into modules by responsibility and add tests for each module.
• Convert database access from callbacks to async/await while preserving behavior.
• Migrate this directory to match the newer pattern used in another module.

3. Performance Optimization: Finding Slow Paths and Repeated Cost

OpenAI teams also use Codex for performance and reliability work. Typical tasks include analyzing slow paths, identifying memory-heavy code, spotting inefficient loops, finding repeated computation, detecting repeated database calls, reviewing expensive queries, and identifying opportunities for caching.

The hard part of performance work is usually not writing a shorter function. It is finding the path that is worth optimizing. Codex can help scan request handlers, data access layers, and batch processing code to flag potential hot spots and draft alternatives that engineers can review. Human engineers still need to benchmark, validate semantics, and choose the final approach, but Codex can reduce the cost of the first pass.

Another important use is code health review. OpenAI's document notes that teams also use Codex to identify risky or deprecated patterns that are still active in the codebase. That matters not only for immediate performance wins, but also for reducing long-term technical debt and preventing future regressions.

Useful prompts:

• Analyze this request handler for repeated expensive operations.
• Identify database queries that could be batched, and explain the risks of changing them.
• Can this loop use less memory? Explain the complexity tradeoff of your version.
• Scan this module for deprecated APIs or high-risk patterns that are still in use.

4. Improving Test Coverage: Making Edge Cases Systematic

Testing is a natural place for Codex to help, especially in areas with thin or missing coverage. OpenAI engineers ask Codex to suggest edge cases, failure paths, and regression scenarios when fixing bugs or refactoring code. For new code, Codex can generate unit or integration test drafts based on function signatures, surrounding logic, and existing test style.

This work looks simple, but it consumes real attention. Developers usually remember the happy path, but it is easy to miss empty inputs, maximum lengths, invalid states, unusual but valid combinations, permission branches, network errors, or unexpected dependency results. Codex is useful because it can systematically enumerate these cases and turn them into runnable tests.

A more effective pattern is to ask Codex to analyze coverage gaps first, then generate tests. For example, have it compare the implementation with existing tests, list uncovered behavior, and then add tests by priority. That tends to produce changes that are easier to review and merge.

Useful prompts:

• Add unit tests for this function, including edge cases and failure paths.
• Read the existing test file and identify important behavior that is not covered.
• Generate a property-based test for this sorting utility.
• Extend this test suite to cover null inputs, invalid states, and failing dependencies.

5. Increasing Development Velocity: From Scaffolding to the Last Mile

Codex helps development velocity at both ends of the cycle.

At the beginning of a feature, engineers can ask Codex to generate folder structure, starter modules, API stubs, validation logic, logging scaffolds, and initial tests. That gets a project to a runnable state faster, so humans can start validating interfaces and behavior instead of hand-writing boilerplate.

Near release, Codex can also handle small but important finishing tasks: low-priority bug fixes, missing implementation details, rollout scripts, telemetry hooks, config files, and migration notes. Each task may be small, but together they can slow down shipping.

OpenAI's document also describes engineers turning product feedback or specs into starter code with Codex. This is useful when a fuzzy request needs to become a concrete implementation draft that can be reviewed and refined later.

Useful prompts:

• Create an initial implementation from this spec and make the main path runnable.
• Add an API route for POST /events with basic validation and logging.
• Using the existing telemetry template, add success and failure events for this new flow.
• Generate a stub implementation from this product feedback and list the questions that need human confirmation.

6. Staying in Flow: Letting Background Tasks Move Forward

Engineering work is often interrupted by meetings, on-call work, messages, and incident response. Another way OpenAI uses Codex is to help engineers preserve focus.

If an engineer notices a small drive-by fix, they do not always need to switch branches and context immediately. They can send it to Codex as a task and review the pull request later. Slack threads, Datadog traces, issue snippets, logs, and quick notes can also be handed to Codex so it can turn them into plans, prototypes, or follow-up tasks.

This does not remove the need for review. It separates "I noticed something" from "I must interrupt my current work right now." Codex becomes a lightweight staging area for context and initial progress, so when the engineer returns to the issue, there is already an analysis or draft to inspect.

Useful prompts:

• Turn this discussion into an executable refactoring plan.
• Stub out the retry logic and leave TODOs; I will fill in the backoff strategy later.
• Summarize this file's responsibilities and open questions so I can resume tomorrow.
• Given this issue, find the related code and draft the smallest viable fix.

7. Exploration and Ideation: Expanding the Design Space

Codex is not limited to deterministic implementation tasks. OpenAI teams also use it for open-ended exploration: comparing designs, testing assumptions, trying unfamiliar patterns, finding alternative implementations, or rewriting an approach in a more functional, event-driven, or modular style.

This works well when Codex is asked to generate multiple candidate directions and the engineer evaluates the tradeoffs. Codex can help surface considerations such as maintainability, performance, complexity, migration cost, failure recovery, testability, and team familiarity.

Exploration also includes searching for related bugs. After fixing one known issue, engineers can ask Codex to scan the repository for similar patterns, such as hand-written SQL, deprecated APIs, duplicated authorization checks, or repeated edge-case omissions. That can turn one bug fix into a broader cleanup effort.

Useful prompts:

• What would change if this system moved from request/response to event-driven design?
• Find places where SQL is manually constructed and rank them by risk.
• Rewrite this implementation in a more functional style with fewer side effects.
• I just fixed this bug; find similar issues that may exist elsewhere in the codebase.

Best Practices from OpenAI's Teams

The later part of the document focuses on usage habits that make Codex more reliable. The common theme is that Codex works best when tasks have structure, useful context, and room for iteration.

Start with Ask Mode, Then Move to Code Mode

For larger changes, it is better not to ask Codex to modify the code immediately. A more reliable pattern is to first ask for an implementation plan in Ask Mode. Once the scope, risks, and steps look right, that plan can become the input for Code Mode.

This two-step workflow keeps Codex more grounded and reduces the chance of drift. It is especially useful for cross-file refactors, dependency migrations, test coverage work, and performance changes.

OpenAI also gives a practical sizing heuristic: Codex works well on tasks that are clearly scoped, that a human might complete in about an hour, or that involve a few hundred lines of code. As models improve, the size of suitable tasks will grow, but for now it is still worth making tasks small and explicit.

Keep Improving the Codex Development Environment

Codex's environment has a direct effect on its success rate. Startup scripts, environment variables, build dependencies, network access, test commands, and local service configuration all matter.

A good practice is to turn repeated failures into environment improvements. If Codex frequently fails because of the same build error, missing dependency, or unclear command, fix the startup script or repository instructions. This may take a few iterations, but it pays off over time.

Write Prompts Like GitHub Issues

OpenAI recommends writing prompts the way you would write a clear GitHub Issue or pull request description. Instead of saying only "fix this," include:

• the desired behavior
• relevant file paths
• component or module names
• reference implementations
• important diffs or logs
• documentation excerpts
• acceptance criteria

One especially effective pattern is to point Codex to an existing implementation in the repository and ask it to follow that style. "Implement this the same way it is done in module X" is much more useful than a vague request to "make it better."

Use the Codex Task Queue as a Lightweight Backlog

Codex tasks do not always need to become complete pull requests immediately. They can also capture side ideas, partial work, small fixes, and exploratory tasks. For engineers, this becomes a lightweight backlog that can make progress in the background.

When you return to focused work, you can review the results, merge them, iterate, or discard them. The key value is reducing context switching while preserving useful opportunities that might otherwise be lost.

Use AGENTS.md for Persistent Repository Context

The document specifically calls out maintaining an AGENTS.md file to give Codex durable repository-level context. These files can include naming conventions, business rules, known quirks, dependency notes, test instructions, things to avoid, and background that the model cannot infer from code alone.

For a team repository, AGENTS.md is essentially an engineering handbook for the agent. It lets different tasks reuse the same operating rules instead of repeating project habits in every prompt.

Use Best of N to Compare Options

OpenAI also recommends using Best of N for complex tasks: generate multiple candidate responses or implementation directions, then compare, select, or combine the best parts.

This is useful for design choices, complex refactors, performance work, and problems with meaningful uncertainty. Rather than treating the first response as final, use Codex as a generator of options and let engineers review and synthesize.

Looking Ahead: Codex Is Becoming Part of the Engineering Process

OpenAI closes by emphasizing that Codex is still in research preview, but already has a real impact on how its teams build software. It helps engineers move faster, improve code quality, and take on work that might otherwise remain deprioritized.

The more important direction is that, as models improve and Codex becomes more deeply integrated into development workflows, its role will keep expanding. Future Codex workflows may involve longer-running projects, cross-tool collaboration, code review, test maintenance, migration execution, and the preservation of engineering knowledge.

For other teams, the lesson is direct: do not treat Codex only as a code-writing tool. The stronger pattern is to place it across the engineering lifecycle: understanding, planning, editing, testing, debugging, summarizing, and cleanup. The more structured the task, the clearer the context, and the tighter the feedback loop, the more reliable the payoff.