Using Codex in a real workflow
Scope a task so it can be verified, iterate on a branch, and keep the human in the loop at the points that matter.
Write a task that can be checked
The quality of the result tracks the quality of the brief. A good task names the files or modules involved, states the constraint that must not change, and defines what done means in terms a command can verify.
# 1. start from a clean tree so every change in the diff is the agent's
git status --short # should print nothing
git switch -c agent/pagination
# 2. one task: scope, constraint, definition of done
codex "Add cursor pagination to GET /api/orders.
- accept ?limit= (default 20, maximum 100) and an opaque ?cursor=
- keep the existing response field names unchanged
- update docs/api.md and tests/test_orders.py
- run pytest and fix what you break, but do not change the happy-path assertions"
# 3. non-interactive variant, useful in scripts
codex exec "fix the failing test in tests/test_payments.py and stop when it passes"- Name the constraint explicitly. Without it, an agent will happily rename fields or rewrite tests to make its change fit.
- Ask for the test it intends to satisfy. If it cannot state one, the task is not yet specified.
- Keep a task to roughly one reviewable idea. Three unrelated fixes in one run produce a diff nobody can read.
- For a long task, ask for a plan first and correct it before any file is written.
The review loop
git diff --stat # scope first: which files moved
git diff # then read the whole patch, not the summary
pytest -q # the project's own gate, run by you
ruff check . && mypy src # cheap verification the repository already has
git add -p # stage deliberately, hunk by hunk
git commit -m "Add cursor pagination to the orders API"| Task | Fits an agent | Why |
|---|---|---|
| Scaffolding from an existing pattern | Well | The repository already shows the shape to copy |
| Mechanical change across many files | Well | Consistent, repetitive, and the compiler checks it |
| Fixing a failing test with a clear error | Usually | The failure is a concrete, verifiable target |
| Domain logic with no tests | Carefully | Nothing verifies the result and the model will guess |
| Security or billing logic | Not unreviewed | Mistakes are silent and expensive |
| Architecture and trade-offs | Poorly | The hard part is the decision, not the typing |
⚠️
Never start an agent run on a dirty working tree, and never run an unattended mode such as
codex exec with broad write access in a repository that holds credentials, production config or uncommitted work. A mistake should cost you one git checkout, not a restore from backup.FAQ
Should I let it run commands automatically?
For read and test commands, yes - that is where most of the value is. For anything that writes outside the repository, installs packages or touches a remote, keep an approval step. The prompt is cheap; an unwanted push is not.
What about large refactors?
Split them. A codebase-wide change is far more reliable as a sequence of small, compiling steps, each committed and reviewed, than as one instruction that must succeed in a single pass.
Related
What Codex is and how to set it up Reviewing output and its limits
Last refreshed 2026-09-18.