How OpenAI Uses Codex: 7 Real-World Scenarios and 6 Best‑Practice Principles

Seven Internal Scenarios

1. Understanding an Unknown System

Engineers ask Codex to map core logic, trace request, data, and error flows across modules, and generate missing documentation. When incidents occur, Codex helps outline fault propagation. Example prompts include:

这个问题经过哪些模块？
哪一处保存真实状态？
现有测试覆盖了什么？
同类问题还可能藏在哪里？

The returned code map may need refinement, but it narrows the investigation area. Non‑programmers can adopt the same approach by first cataloguing processes, participants, sources, and open items.

2. Cross‑File Refactoring and Migration

When dozens of files require a uniform rewrite, simple search‑replace misses local variations. Codex follows dependency graphs to handle API migrations, legacy dependency swaps, async‑flow rewrites, and duplicate implementation consolidation. The hardest part is enforcing a single rule across all changes while preserving compatibility; missing one old call leaves the migration incomplete.

3. Performance and Reliability Optimization

Codex is used to locate redundant database calls, unnecessary loops, cacheable paths, memory‑heavy patterns, and deprecated high‑risk code. The article stresses that shorter code does not guarantee better performance; tasks must specify measurement methods (query count, memory peak, benchmark, latency targets) and use identical metrics before and after changes.

4. Adding Tests and Boundary Conditions

Codex helps discover edge cases such as empty input, maximum length, null, illegal states, and exception paths, then generates regression tests. The author warns that aiming merely for 90 % coverage is insufficient; tests should protect critical behaviours and highlight the most costly failure scenarios.

5. Handling Fragmentary Work Around Development

At project start Codex can scaffold directories, modules, and API stubs. Near release it can triage bugs, add small features, tidy configuration, or produce a runnable prototype based on product feedback. Delegating these tasks frees engineers to focus on architecture and trade‑offs.

6. Capturing Ad‑Hoc Findings in a Task Queue

When engineers spot a quick fix while reading code, they hand the item to Codex and postpone review until the main work stream finishes. The same pattern applies to pending evidence, anomalous table entries, or second‑round improvements, preventing context loss.

7. Exploring Alternative Solutions and Refuting the Current One

Codex can generate multiple implementations, compare architectural trade‑offs, and check whether an old pattern still exists elsewhere. Teams can assess modification scope, risk, and verification cost without fully committing to each alternative; final decisions remain human.

Six Official Best Practices

1. Investigate and Plan Large Changes

OpenAI uses a “question mode” now called “/plan”. The process reads relevant code and documentation, lists impact scope, identifies unanswered questions, and drafts implementation steps and validation methods. Early planning exposes misunderstandings that could cause costly rework.

2. Prepare the Runtime Environment

Startup scripts, environment variables, network access, and build tools must be reliable. Missing dependencies, wrong directories, or permission errors are often mistaken for model limitations. A stable environment that can be started, built, and tested is more valuable than extensive model explanations.

3. Write Tasks Like Qualified Work Orders

Tasks should include file paths, component names, logs, documentation snippets, and reference implementations. The article contrasts a vague task “Optimize login module.” with a concrete work order that specifies the exact files, preserves the public API, and defines success criteria.

4. Use a Task Queue for Light‑Weight To‑Dos

Small bugs, unverified improvements, and independent alternatives are placed in a queue that reminds and stores them, while formal requirements still go through design review and release planning. The author separates “what not to forget” from “why we do it, how, and when it’s done.”

5. Encode Long‑Term Rules in AGENTS.md

AGENTS.md

stores repository structure, common commands, naming conventions, prohibitions, and verification requirements. Codex reads it on each project entry, avoiding repeated human reminders. Rules must be short and accurate; repeated errors trigger rule expansion.

6. Compare Multiple Solutions for Uncertain Tasks

When the path is unclear, Codex can produce small tweaks, full refactors, or compare low‑risk versus high‑performance implementations. Reviewers focus on change scope, rollback difficulty, test cost, and maintenance impact. Purely mechanical tasks with clear specifications do not need this step.

Isolate Work Before Parallel Execution

Codex documentation advises placing independent tasks in separate chats, tasks, or Git worktrees. Simultaneous edits to the same file cause conflicts that erase the speed advantage. Programmers can use Git worktrees—one per task—and merge after review. Non‑code work (research, writing, fact‑checking) should also define who can edit what.

Run Validation After Generation

After Codex generates code, tests, static analysis, behavior checks, and diff reviews must run. Failures trigger iterative fixes. The typical engineering flow is:

Understand → Plan → Modify → Test → Review → Fix → Deliver

Documentation follows a similar pipeline:

Read sources → Draft → Verify sources → Mark assumptions → Human edit → Publish

Metrics such as traceability, format correctness, and factual sourcing become explicit acceptance criteria; model‑claimed completion cannot replace them.

Roles of AGENTS.md , SSOT, and OpenSpec

The article distinguishes four artifacts:

AGENTS.md : operational handbook for commands, stable rules, navigation, and validation.

SSOT : single source of truth for product definitions, architecture constraints, fields, and business rules.

OpenSpec proposal : defines the current change’s problem, scope, goals, and non‑goals.

OpenSpec design : captures the current change’s architecture decisions, interfaces, and risks.

OpenSpec tasks : outlines phases, status, and acceptance items for the change.

Task queue : lightweight to‑dos and exploratory items.

Test & review : provides evidence of results.

Repository layout example:

repo/
├─ AGENTS.md
├─ docs/ssot/
├─ openspec/
│  └─ changes/<change>/
│     ├─ proposal.md
│     ├─ design.md
│     └─ tasks.md
├─ src/
└─ tests/

Codex first reads AGENTS.md for workflow, then SSOT for long‑term facts, and finally the relevant OpenSpec change for the current goal. After modifications, tests and diffs prove the outcome, and the state is written back to the task files.

Lesson from a Prototype Accident

When Codex generated a portal prototype, it copied a developer‑only comment into the live page, producing a stiff UI. The author removed such internal notes, placeholder data, demo buttons, and “to‑be‑filled” text, then recorded the rule in AGENTS.md: prototype content may stay for structure, but developer notes must not appear in production.

Non‑Programmers Can Follow the Same Process

Even without a code repository, equivalents exist: AGENTS.md maps to writing style guides or brand rules; work orders become task briefs; SSOT becomes policy documents or data dictionaries; tests become verification checklists; diffs become version comparisons; task queues become pending‑item lists; multi‑option comparison becomes side‑by‑side proposal reviews.

Final Thoughts

OpenAI’s seven scenarios—code reading, migration, performance tuning, testing, delivery, and solution exploration—share a common workflow: investigate, prepare environment and data, state constraints, then let test or review results speak. The effectiveness of Codex depends both on the model’s capabilities and on providing a well‑structured, runnable, and verifiable work environment.

Reference Links

OpenAI How OpenAI Uses Codex – https://openai.com/business/guides-and-resources/how-openai-uses-codex/

Best Practices – https://developers.openai.com/codex/learn/best-practices

Using AGENTS.md – https://developers.openai.com/codex/agent-configuration/agents-md

Long‑Running Work – https://developers.openai.com/codex/long-running-work

Git Worktrees – https://developers.openai.com/codex/environments/worktrees

Permissions – https://developers.openai.com/codex/permissions