OpenAI Codex Training Guide

The OpenAI Academy guide says Codex is designed to accelerate builder productivity and move toward more autonomous execution of software tasks. For a business audience, the deeper point is that Codex changes the work system around software. It affects how requirements are written, how technical discovery happens, how defects are investigated, how evidence is gathered, and how reviews are prepared.

Codex should be understood through five operating capabilities:

• Comprehension: It can inspect unfamiliar code, documentation, logs, or artifacts and explain structure, intent, and dependencies.
• Transformation: It can turn requirements into drafts, code changes, tests, migration plans, documents, and summaries.
• Execution: When permitted, it can run commands, operate tools, use browsers, and perform multi-step workflows.
• Validation: It can run tests, compare outputs, capture screenshots, review diffs, and explain risks.
• Coordination: It can work in threads, resume prior context, use instructions, and support parallel subtasks.

The business lesson is that Codex does not merely "write code." It compresses the distance between a business question and a reviewable artifact. That artifact might be a patch, test result, technical explanation, PR review, spreadsheet analysis, slide deck outline, or formal recommendation.

The Academy guide identifies GPT-5-Codex as purpose-built for Codex and agentic coding. The business implication is not simply "a stronger model." It changes which tasks are realistic to delegate. A more steerable model can follow tighter instructions. Adaptive reasoning means simple work can stay fast while complex work can take more time. Strong code review capability makes it useful before, during, and after implementation. Image input matters for frontend work because a screenshot, mockup, bug image, or UI state can become concrete context.

The same request can be low risk or high risk depending on the surface. A request to "review this diff" inside a GitHub pull request is review-oriented and visible. The same request inside a local folder with uncommitted changes may require the user to decide what should be shared, committed, or ignored. A request to "summarize these emails" depends on whether Codex has authorized access to a connector, an export file, or only a pasted excerpt.

Use four questions before choosing a surface:

1. Where does the source material live? Repository, PR, local folder, email, browser, spreadsheet, transcript, design image, or document.
2. What action is needed? Explain, draft, edit, test, operate a browser, inspect desktop UI, create an artifact, or review.
3. What must be auditable? Diffs, source citations, command output, screenshots, review comments, formulas, or decision log.
4. What authority is required? Read-only analysis, local edit, PR comment, outbound message, production deployment, or external publication.

The Academy guide names headless CLI workflows and CI/CD automation as advanced uses. This does not mean "let Codex do anything in automation." It means Codex can be used in repeatable, bounded, noninteractive workflows when the input, permissions, output format, and review gate are clear.

For business users, the critical point is that automation shifts risk from "one person clicked a button" to "a workflow can repeat." Therefore, noninteractive Codex use should have narrow scope, explicit credentials handling, controlled environment variables, logged output, and a human review step before production impact.

Noninteractive task pattern:
Input: failing test output, target directory, and expected behavior.
Instruction: propose and implement the smallest fix.
Constraints: do not change public API, do not add dependencies, do not touch unrelated files.
Output: summary, diff, tests run, residual risks.
Gate: open PR or produce patch for human review; do not merge automatically.

The Codex manual's goal, context, constraints, and done criteria pattern is simple, but it is not shallow. It is a compact management discipline. Good prompts do the same work as a good assignment memo: they define the mission, provide the relevant background, make boundaries explicit, and describe acceptable proof.

A semi-technical business user does not need to write like an engineer. They need to write like a clear operator. The most common failure is not a lack of technical vocabulary. It is failing to say what should happen, why it matters, what should not happen, and how the result will be reviewed.

Use plan-first work when the task has ambiguity, risk, multiple files, multiple stakeholders, unclear requirements, sensitive data, production impact, or uncertain tool access. The point of planning is not delay. It is preventing Codex from filling gaps with assumptions.

Goal: Prepare a migration plan for moving customer notifications from the legacy service to the new messaging service.
Context: Inspect the repository first. Focus on notification creation, retry logic, templates, and tests.
Constraints: Do not edit files yet. Identify risks around billing, compliance, and customer-facing copy.
Done when: Provide a phased plan, files likely affected, test strategy, rollback approach, and questions that need human answers.

Use the approved migration plan. Implement phase 1 only: add tests around current notification behavior and document existing retry rules.
Do not change runtime behavior.
Done when tests pass and the summary lists changed files, tests run, and remaining phases.

Reusable prompt patterns help users avoid starting from a blank page. They should be adapted, not copied blindly.

Codebase orientation:
Inspect this repository and explain the business process it supports. Identify the main modules, data flow, external integrations, and highest-risk areas. Do not edit files. Cite file paths and list open questions for the product owner.

Bug investigation:
Investigate this issue using the error log, screenshot, and repository. First summarize the observed symptom and expected behavior. Then identify likely causes, propose a reproduction path, and recommend a fix plan. Do not implement until I approve the plan.

PR review:
Review this change like an owner. Prioritize correctness, security, regressions, test gaps, maintainability, and user impact. Provide findings first, ordered by severity, with file references and verification suggestions.

Business document:
Convert these notes and source files into a formal decision memo. Separate facts, assumptions, analysis, options, recommendation, risks, and next steps. Cite source files or messages for any material claim.

Spreadsheet analysis:
Analyze this workbook for variance drivers. Preserve source data. Show calculations, assumptions, exceptions, and a management-level narrative. Create a table of findings and identify what should be verified manually.

Codex output should be evaluated by the strength of its evidence. A confident explanation is a starting point, not a finish line. The evidence ladder below helps non-engineers ask better review questions.

GitHub review is valuable because the unit of work is already structured: a pull request has a branch, diff, comments, checks, reviewers, and merge rules. Codex can provide a high-signal review pass, but the reviewer should still decide whether a finding is valid, whether a fix is appropriate, and whether the PR is ready.

A strong Codex review request should say what matters most:

@codex review
Prioritize correctness, security, privacy, data integrity, regression risk, and missing tests.
Use our AGENTS.md review guidance.
Avoid low-value style comments unless they indicate a real maintainability risk.
For each finding, explain impact, exact location, and suggested verification.

For business teams, PR review evidence should answer: what changed, why it matters, what was tested, what risk remains, and who is authorized to merge.

The Academy guide highlights image input as part of Codex's agentic coding value. In practical terms, screenshots and browser inspection close a gap that tests alone may miss. A UI can compile and pass tests while still being unusable, inaccessible, clipped, or visually inconsistent.

• Use screenshots when: layout, spacing, responsive behavior, text overflow, dashboards, forms, charts, modals, or visual regressions matter.
• Ask for viewport coverage: desktop, tablet, and mobile sizes relevant to the audience.
• Ask for interaction coverage: hover, focus, keyboard navigation, validation states, loading states, and error states.
• Ask for accessibility checks: labels, contrast, focus order, readable text, and non-overlapping content.

The Codex manual describes sandboxing, approval policies, permissions, trusted projects, managed configuration, hooks, and governance. The business translation is: Codex can be powerful only if its authority is intentionally bounded. The organization must know what Codex can read, where it can write, when it can call external systems, and when a human must approve an action.

Separate four concepts that are often blurred together:

• Capability: What Codex or a connected tool can technically do.
• Permission: What the current session, sandbox, connector, or policy allows.
• Approval: When Codex must stop and ask a user before continuing.
• Accountability: Who is responsible for the outcome if the work is accepted or acted upon.

Codex can encounter untrusted instructions inside web pages, emails, tickets, dependency READMEs, documents, or logs. A malicious or irrelevant source might say "ignore previous instructions" or ask the agent to exfiltrate data. The user should treat outside content as data to analyze, not instructions to obey.

For larger organizations, Codex governance should connect to existing security, compliance, and operational processes. The Codex manual describes enterprise ideas such as managed configuration, governance dashboards or APIs, admin setup, access controls, and policy enforcement. A business rollout should translate those into practical operating questions.

• Identity: Which users, roles, and groups can use each Codex surface?
• Repository access: Which repositories are connected, and do branch protections still apply?
• Data policy: Which classes of information may be used in prompts, connectors, screenshots, or exports?
• Tool policy: Which MCP servers, plugins, browser tools, and desktop apps are allowed?
• Approval policy: Which actions require user, reviewer, manager, security, or legal approval?
• Auditability: What logs, task summaries, PR comments, and output artifacts must be retained?
• Measurement: How will usage, review quality, risk, and value be tracked?

Codex customization is a stack. Each layer has a different scope and failure mode. The most mature teams do not put everything in one place. They choose the smallest durable surface that matches the need.

AGENTS.md is where teams make Codex less generic. It should be practical and grounded in repeated friction. The strongest AGENTS.md files tell Codex how the project is organized, how to build and test, what not to touch without approval, what quality means, and how to summarize work.

# AGENTS.md Structure

## Business Context
What the application does, who uses it, and which workflows are most sensitive.

## Repository Map
Key folders, ownership areas, generated files, and directories to avoid.

## Commands
Install, build, test, lint, typecheck, visual test, and data-generation commands.

## Coding Standards
Existing patterns, dependency policy, accessibility expectations, error handling, logging, and naming.

## Review Standards
How Codex should report changes: business impact, files changed, tests run, risks, and assumptions.

## Stop Conditions
When to pause: secrets, migrations, production data, legal copy, external messages, destructive commands.

Do not turn AGENTS.md into a vague values document. Codex benefits most from concrete commands, examples, boundaries, and review requirements.

Model Context Protocol and app connectors let Codex work with external tools or private data when authorized. This is the bridge from "agent that sees a folder" to "agent that can work with a business system." Examples include GitHub, Gmail, Google Drive, Slack, documents, spreadsheets, custom internal APIs, or databases through approved tools.

The business rule is straightforward: live connectors create live governance questions. A connector should have a purpose, owner, permission model, and review expectation. For example, an email connector may be approved for summarizing and drafting but not for sending without explicit approval. A database connector may be approved for read-only analysis but not data mutation.

• Good MCP use: "Read support ticket data through the approved tool and produce a cited trend analysis."
• Risky MCP use: "Connect to every system and make whatever updates seem useful."
• Good connector output: source list, access boundaries, findings, drafts, and actions requiring approval.

Skills and plugins are how repeated work becomes more than a prompt. A skill can encode a workflow such as "generate a board report from a workbook and meeting notes." A plugin can bundle skills with tools, MCP configuration, assets, or app connections. Hooks can enforce lifecycle checks, such as blocking risky commands or requiring a post-tool review. Automations can run stable recurring work.

A serious Codex rollout should not be measured only by how many people have access. Access is an input. Adoption is whether specific workflows become faster, more reliable, better documented, and easier to review. Treat Codex use cases as a portfolio with different risk and value profiles.

Good Codex metrics combine speed, quality, risk, and adoption. A single productivity number is rarely enough.

• Cycle-time metrics: request to first artifact, artifact to review, review to acceptance, time saved versus baseline.
• Quality metrics: test coverage added, review findings caught before merge, escaped defects, rework rate, documentation accuracy.
• Governance metrics: percentage of tasks with evidence, percentage requiring approval, policy exceptions, high-risk task volume.
• Learning metrics: repeated mistakes converted into AGENTS.md, skills, prompts, or process changes.
• Adoption metrics: active users by role and workflow, not just total prompts.

For leadership, the best narrative is not "we used AI more." It is "we reduced discovery time by 40%, increased test coverage on touched modules, and improved PR review quality without expanding production risk."

A work order should be detailed enough to prevent guessing but short enough to use. For higher-risk work, it should become a reusable intake form.

1. Business Intent
- What decision, workflow, or user outcome does this support?
- What value is expected if the task succeeds?

2. Source Material
- Repositories, branches, PRs, tickets, documents, emails, transcripts, screenshots, logs, workbooks.
- Which sources are authoritative?
- Which sources are background only?

3. Scope
- In scope:
- Out of scope:
- Stop before:

4. Constraints
- Security:
- Privacy:
- Brand/tone:
- Architecture:
- Dependencies:
- Timeline:

5. Codex Surface
- App, CLI, IDE, Web/Cloud, GitHub, browser, computer use, connector, or plugin.
- Why this surface is appropriate.

6. Evidence Required
- Tests:
- Screenshots:
- Source citations:
- Calculations:
- Diff summary:
- Assumptions and limits:

7. Human Decision
- Approver:
- Accept/revise/escalate criteria:
- Action allowed after approval:

1. Business intent: Customers cannot complete profile setup on mobile; support volume increased.
2. Codex plan request: Inspect logs, screenshots, and profile setup code. Do not edit yet. Identify likely cause, affected files, reproduction path, and validation plan.
3. Human review: Product owner confirms expected behavior and prioritizes mobile fix.
4. Implementation request: Fix only the mobile validation issue. Preserve desktop behavior. Add or update tests if possible. Validate at mobile and desktop widths.
5. Evidence: diff, test output, screenshot notes, reproduction before/after, residual risks.
6. Decision: Accept fix, request additional testing, or escalate if root cause touches profile data policy.
7. After-action: Add a prompt pattern or AGENTS.md note for future responsive-form validation tasks.

1. Business intent: Leadership needs to understand why renewal delays increased in Q2.
2. Sources: exported CRM data, support emails, sales notes, meeting transcript, and prior Q1 deck.
3. Codex task 1: Analyze sources separately. Produce a source inventory and top hypotheses with evidence.
4. Codex task 2: Create a variance table and identify the largest drivers. Separate facts from assumptions.
5. Codex task 3: Draft a 10-slide leadership narrative with speaker notes and risk caveats.
6. Human review: Validate calculations, remove sensitive examples, confirm recommendation.
7. Decision: Approve presentation for leadership, request additional data, or escalate to revenue operations.

This example is intentionally non-code. The same Codex work principles apply: source material, constraints, evidence, review, and decision.

Codex is rooted in builder workflows, but the broader agentic pattern applies to many business tasks when the proper tools are available. The work is not "ask AI to think for me." The work is "assign a bounded transformation of source material into a reviewable artifact." That source material may be a repository, an email export, a Teams transcript, a Zoom chat, a spreadsheet, a Word document, a slide deck, a website, or a desktop application screen.

The capability depends on environment. Some sessions may have app connectors, plugins, browser control, computer use, document tools, spreadsheet tools, or presentation tools. Other sessions may not. A mature user learns to ask: what tools are available, what sources can be used, what actions are allowed, and what evidence will prove the result?

Email and chat are high-value because they contain commitments, objections, timelines, sentiment, risk signals, and undocumented decisions. Codex can help convert messy communication into structured operational intelligence.

Email triage prompt:
Use the authorized mailbox/search results or attached export only.
Group messages into urgent, needs reply, waiting on someone else, informational, and possible escalation.
For each item, provide sender, date, topic, why it matters, suggested action, and source message reference.
Draft replies only for the messages I mark. Do not send anything.

Meeting transcript prompt:
Summarize this transcript into decisions, action items, owners, due dates, risks, disagreements, and unresolved questions.
Separate direct transcript evidence from your interpretation.
Draft a follow-up email for review, but do not send.

Review rule: do not let a polished summary become the official record until a human confirms decisions, owners, and sensitive content.

Spreadsheet work benefits from Codex because it combines calculation, interpretation, explanation, and artifact generation. The key risk is unsupported narrative. Codex should show formulas, assumptions, data quality issues, and calculation logic.

Spreadsheet prompt:
Analyze this workbook for Q2 renewal-delay drivers.
Preserve source data.
Create a findings table with metric, calculation, source tab, evidence, business interpretation, and confidence.
Flag missing data, formula assumptions, and anything that needs a human finance or operations review.

Codex can help turn scattered material into formal artifacts: decision memos, reports, redlines, summaries, presentations, speaker notes, and executive narratives. The serious-user standard is source traceability. Every material claim should tie to a source, calculation, or stated assumption.

Browser and desktop tasks can help when the workflow exists only in a user interface: testing a form, gathering screenshots, checking a dashboard, navigating a tool, or preparing a draft in an application. These tasks need explicit approval boundaries because UI actions can have real-world effects.

• Safe browser task: Inspect a web page, collect observations, capture screenshots, and report issues.
• Higher-risk browser task: Submit a form, make a purchase, update a record, or publish content. Require explicit approval.
• Parallel task pattern: One thread analyzes messages, one checks spreadsheet numbers, one drafts a report, and one reviews a PR. The user consolidates evidence and resolves conflicts.
• Conflict rule: Do not let multiple agents edit the same artifact unless ownership and merge order are clear.

Parallel work prompt:
Create three independent workstreams:
1. Analyze source emails for customer themes.
2. Analyze workbook data for quantitative support.
3. Draft an executive narrative using only verified findings from 1 and 2.
Return separate evidence summaries and a final reconciliation table showing which claims are supported by which sources.