OpenAI Codex: Professional Engineering Workflows
A six-chapter, practical OpenAI Codex learning path covering project instructions, application boundaries, tests, Git review, extensions and team automation.
- Author
- absequ
- Published
- Updated
- Category
- AI Tools
- AI Tools
- OpenAI Codex
- learning path
- professional engineering
Six ordered tutorial chapters. Prerequisites: basic programming and Git; the core path starts from tool installation. The professional path assumes you have finished the core path or can demonstrate the same edit–verify–review loop.
Official tool documentation checked on 2026-11-06. Examples are original teaching exercises for a disposable notes project, not instructions to alter the absequ repository. Platform, account, model, privacy and permission controls can change; follow the cited current documentation for your installation.
- Design repository instructions and a staged plan
- Build a frontend-to-API feature without crossing trust boundaries
- Debug and refactor with unit and integration evidence
- Review, commit and recover without losing user changes
- Add skills and MCP while isolating parallel tasks
- Automate bounded work and manage team cost and privacy
On this page
1. Design repository instructions and a staged plan
Learning objectives: Keep durable project rules separate from a task plan and hand off only the context needed for the next step.
Prerequisites: Complete OpenAI Codex Getting Started & Core Workflows, including the notes lab and diff review.
AGENTS.md is a project instruction surface, not an access-control system. Codex discovers global and repository instructions with nearer-directory guidance taking precedence; project discovery is tied to the working directory. Confirm what was loaded instead of assuming every nested instruction file applies to every task. Personal configuration lives in ~/.codex/config.toml, with trusted project overrides supported.
Write instructions about decisions a new engineer cannot infer cheaply: the supported package manager, protected files, how to validate a change and what needs explicit approval. Keep a task-specific plan in the conversation or a reviewed design note. A huge instruction file containing copied source creates stale context and can hide a short rule that matters.
Practice in order:
- In a learning checkout, draft the sample AGENTS.md below and verify every command against the actual repository before saving it. This is an example, not an instruction to change your employer repository automatically.
- Ask Codex to restate the applicable rules, identify user changes and propose three independently reviewable steps for adding a note search feature.
- At each checkpoint, capture the agreed decision, changed files, checks and unresolved questions. Start the next bounded task with that handoff rather than pasting a whole transcript.
# AGENTS.md — example for the notes lab
Use the existing Node test runner. Do not add packages for small changes.
Preserve unrelated working-tree edits. Ask before changing storage or APIs.
Run node --test notes.test.mjs for notes-function changes.
Never read local credential files or publish changes without approval.Expected outcome: Codex explains the rules that apply and proposes a plan tied to real consumers. You can identify the first task without requiring a later database or UI decision to be guessed. A handoff is short enough to review against the current diff.
Common mistakes and troubleshooting: If an instruction did not load, check the startup directory and discovery hierarchy. Do not solve a permissions error by adding reassuring prose to AGENTS.md: filesystem/network enforcement is configured separately. Remove duplicated rules rather than increasing context indefinitely.
Summary: You have an auditable plan and project context. Next implement a vertical slice while preserving frontend/server boundaries.
2. Build a frontend-to-API feature without crossing trust boundaries
Learning objectives: Use Codex to connect a small React interaction to a validated service contract without silently creating infrastructure.
Prerequisites: Complete chapter 1: Design repository instructions and a staged plan.
A vertical slice proves one user outcome through the relevant layers. Consider filtering notes in a React view backed by a Node API. Keep query state in the UI, validation on the server and persistence behind an existing adapter. A Server Component can read server data; a client component handles interaction. Do not import credentials or Node-only code into browser modules just to make a generated snippet compile.
Before a database change, ask for the contract: allowed input, authorization, error shape, consistency and migration impact. An in-memory demo is useful for a test but is not production persistence. Infrastructure work has cost and operational consequences, so a proposed service or schema migration is a decision to review, not an automatic extension of a UI ticket.
Practice in order:
- Provide the current route/component and ask for a plan that uses the existing API response shape. Specify loading, empty and failure states, keyboard access and reduced-motion expectations.
- Approve a frontend slice first using fixture responses. Then inspect a server patch with bounded query length and explicit status handling. Avoid real credentials and production calls.
- Ask for a targeted component check and an API integration check with a stubbed persistence adapter. Record storage/authorization questions before approving any migration or deployment configuration.
Feature: filter notes by title. Reuse the existing route and response type.
Client: labelled search field; empty state; preserve focus on results update.
Server: reject query strings longer than 100 characters; do not log queries.
Use existing persistence only. No new database, auth, packages or cloud resources.
Propose affected files, boundaries and focused UI/API checks before editing.// Example server-side query boundary; adapt to the existing route.
export function parseNoteQuery(raw) {
if (typeof raw !== 'string' || raw.length > 100) {
throw new Error('Invalid query');
}
return raw.trim();
}The helper illustrates authoritative server-side input bounds, not a complete endpoint. Map its error into the existing route error contract, and test the boundary through that route. Do not import server credentials into a client component to reuse validation.
Expected outcome: The diff preserves a serializable frontend/server boundary and the existing adapter. Invalid input has a predictable response; a failed request does not masquerade as an empty list. You can point to each layer responsible for the behavior.
Common mistakes and troubleshooting: Generated code can validate only in the browser, fetch on every keystroke without cancellation or assume a database exists. Review those assumptions explicitly. Ask for rollback and data compatibility before any approved migration, even if the code change looks small.
Summary: You can scope a feature across UI, API, data and infrastructure. Next diagnose and refactor those boundaries with tests that measure behavior.
3. Debug and refactor with unit and integration evidence
Learning objectives: Choose the smallest meaningful check for a hypothesis and broaden verification only when the change warrants it.
Prerequisites: Complete chapter 2: Build a frontend-to-API feature without crossing trust boundaries.
Unit tests isolate a deterministic contract; integration tests verify that real collaborators agree. For title filtering, a pure comparison function can be unit-tested while a route integration test exercises parsing, validation and adapter calls. Mocking everything with the same assumptions can hide a broken boundary. Ask what failure the proposed test would detect in the old implementation.
Refactoring should preserve external behavior. Separate it from changing sort order or error semantics. A race where an older search response overwrites newer results requires reasoning about cancellation or request identity, not just renaming variables. Supply the timing sequence and ask Codex for a regression test before changing the component.
Practice in order:
- Give a sanitized reproduction: query A starts, query B starts, B finishes, then A finishes. State that only B should remain visible.
- Request a failing regression case using the existing test framework and a controllable response delay. Review whether the test genuinely models out-of-order completion.
- Approve the smallest correction, rerun the focused case and nearby tests, then ask whether changed imports/public interfaces justify wider type or build checks. Report those as separate checks, not as automatic rituals.
Reproduce a stale-result bug with controlled responses: A starts before B,
B completes first, A completes last. Assert that B stays visible.
Use the existing test framework; no real network and no timing sleeps if
a deferred promise can control ordering. Preserve API behavior while fixing UI state.Expected outcome: The test catches the stale update on the old code and passes on the corrected code. You know whether the fix handles cancellation, unmounting and failure for the latest request, rather than merely delaying a race until the test happens to pass.
Common mistakes and troubleshooting: Do not label a tool-launch or sandbox failure a test failure. Compare environment evidence first. A full build after each prose edit wastes time, but skipping route integration after changing request validation leaves an important uncertainty. Choose checks by risk and changed consumers.
Summary: Test selection is now tied to hypotheses and boundaries. Next review the patch as a teammate would, including secrets and Git safety.
4. Review, commit and recover without losing user changes
Learning objectives: Use a branch and diff-based review to make AI work understandable and reversible before publishing.
Prerequisites: Complete chapter 3: Debug and refactor with unit and integration evidence.
An agent can edit quickly enough to mix several concerns in one patch. A branch provides a review boundary; it does not prevent concurrent processes from changing the same files. Begin with a clean baseline or explicitly record existing modifications. The notes lab is a safe place to practice branches; an employer repository may have different commit and approval rules.
Review for concrete failure conditions: input bounds, error propagation, unsafe HTML, server secrets in client imports and accidental provider logging. Ask for a review with file/line evidence and separate definite defects from concerns needing reproduction. Codex /review can assist, but another model response is not independent execution evidence.
Practice in order:
- Create a task branch in a suitable clean checkout. Ask Codex to keep staging, committing and pushing outside its task until you approve a reviewed diff.
- Inspect diff statistics, content and untracked files. Run a whitespace check and the chosen behavioral checks. Inspect candidate additions for secret material without printing it.
- If the patch is wrong, save a comparison and restore only agreed hunks or ask for a corrective patch. Never use a blanket reset to recover while user changes are present. Write a PR description explaining the resulting behavior and validation limits.
git status --short
git switch -c tutorial/note-filter
git diff --stat
git diff
git diff --check
# Also open untracked files reported by git status.
# Stage/commit only after human review; these commands do not publish.Expected outcome: The reviewer can explain every changed file and see evidence for the intended outcome. A local commit, when explicitly authorized, contains one coherent concern. A push or deployment still requires its own authorization and team process.
Common mistakes and troubleshooting: Ignoring .env in Git does not hide it from an agent with filesystem access. Use restricted environments and avoid secrets in task context. Do not assume a checkpoint includes manual edits or remote side effects; inspect its scope before restoring.
Summary: Your patch is ready for a human review decision. Next extend the agent carefully and isolate parallel work.
5. Add skills and MCP while isolating parallel tasks
Learning objectives: Choose between reusable instructions, external tools and parallel workers without widening trust accidentally.
Prerequisites: Complete chapter 4: Review, commit and recover without losing user changes.
A skill packages a repeatable procedure in SKILL.md; MCP connects an agent to an external tool or data source. These solve different problems. A code-review checklist needs instructions, while a read-only issue lookup needs an authorized integration. Inspect a skill or server before enabling it: both can cause the agent to encounter instructions or execute software beyond the repository.
Parallelism helps when tasks have independent inputs and file ownership. Start with two local CLI sessions in separate Git worktrees: one investigates tests, another implements a focused change. Built-in subagent availability and controls vary with the installed Codex surface; use the current documentation rather than assuming all sessions expose the same delegation UI. A worktree separates files but may still share credentials, databases and ports.
Practice in order:
- Draft a small instruction-only review skill: input is a diff; output is a list of evidenced risks and missing checks. Follow current skill discovery/install documentation instead of guessing a global directory.
- For MCP, begin with an approved read-only service and minimal scope. Keep connection secrets outside versioned configuration and require explicit approval before any tool that writes or sends data.
- Create a worktree for a truly independent investigation. Assign owners and prohibit both agents from changing shared contracts. Integrate results sequentially and rerun the checks affected by the combined patch.
git worktree add ../notes-review -b tutorial/notes-review
# In the separate worktree, start a second Codex session.
# Task A: inspect the filter tests; do not edit.
# Task B: implement only the approved filter change in the original worktree.
# Reconcile findings before staging either patch.Expected outcome: You can explain why each extension or worker is necessary, what it may access and who owns the integration decision. Parallel investigation produces evidence without two processes racing to rewrite one file.
Common mistakes and troubleshooting: A trusted MCP name does not make returned data trusted instructions. Do not grant broad network or filesystem access to fix an unrelated server startup error. More agents also mean more duplicated context, inference cost and integration work.
Summary: You can extend capabilities with explicit boundaries. Next package a repeatable workflow for CI and team operation.
6. Automate bounded work and manage team cost and privacy
Learning objectives: Run a non-interactive task with explicit permissions, preserve review gates and diagnose inefficient usage.
Prerequisites: Complete chapter 5: Add skills and MCP while isolating parallel tasks.
codex exec supports non-interactive workflows. Its output is a proposal or report until your pipeline verifies and approves it. Start with a read-only summary on a trusted repository, not an autonomous production repair loop. The current documentation distinguishes final-message stdout from progress stderr and supports machine-readable events; choose the output contract before parsing it.
Automation needs an input trust policy, limited credentials, a timeout, an artifact budget and a human owner. Never expose CI write tokens or deployment secrets to untrusted pull-request content. Team administrators should confirm model availability, data handling and account budgets using current policies; no fixed plan quota or price is promised here. Skills and instructions help consistency but are not a replacement for CI enforcement.
Practice in order:
- Try the bounded read-only command below in a throwaway checkout. Review the report before considering write permissions. Use the current CLI help to verify supported flags on your installed version.
- For a team pilot, choose one repository and one task type. Record success criteria, human review time, validation failures and usage; compare with the manual workflow instead of counting generated lines.
- If cost or latency grows, narrow file scope, summarize resolved findings and stop duplicate workers. If a run is blocked, distinguish access, quota, network and application errors before retrying. Keep a sanitized handoff with the exact last verified state.
codex exec "Read-only: summarize the note-filter diff and list missing behavioral checks. Do not modify files, contact services or publish anything."
# For reproducible automation, also enforce the intended permissions in
# the runner/client configuration; prompt wording alone is not enforcement.Expected outcome: A non-interactive report can be reviewed as an artifact, with no claim that it approved itself. The team has a measurable budget and a procedure for stopping, recovering and assigning ownership when an agent cannot finish safely.
Common mistakes and troubleshooting: An approval prompt is not guaranteed to appear in every headless environment. Never compensate by enabling unrestricted execution. Avoid logging full prompts or events containing secrets, customer records or proprietary code; define retention and access before collecting them.
Summary: You have completed the Codex progression: terminal fundamentals, evidence-driven changes, extension boundaries and controlled team automation. Return to the tool overview to review prerequisites or compare another tool.
References
AGENTS.md discovery — OpenAI
Codex configuration — OpenAI
Codex CLI — OpenAI
Sandboxing — OpenAI
Permissions — OpenAI
Build skills — OpenAI
Model Context Protocol — OpenAI
Codex subagents — OpenAI
Non-interactive Codex — OpenAI