← Guides

Codex CLI best practices

A practical workflow for scoping tasks, supplying context, steering the agent, testing changes, and reviewing the diff.

Codex CLI performs best when it receives a clear result to produce and a reliable way to check that result. The prompt does not need a rigid format, but important tasks benefit from four pieces: goal, context, constraints, and completion criteria.

Start in the right directory

Launch Codex from the repository or package that owns the task. The working directory affects which files are in scope, which AGENTS.md instructions load, and which project configuration applies.

Run /status at the start of unfamiliar work. Confirm the model, sandbox, approval policy, writable roots, and current directory before troubleshooting the agent’s behavior.

Describe the result

Lead with the outcome rather than prescribing every edit:

Make the parser reject empty input, preserve the existing public API, add a
regression test, and run the focused test suite. Do not change formatting in
unrelated files.

Point to relevant files, errors, examples, or architecture notes. State the constraints that would create real rework if missed. Finish with a checkable definition of done.

Plan when uncertainty is expensive

Use /plan for changes that cross several components, have unclear requirements, or involve a risky migration. A plan is valuable when it exposes decisions; it is overhead for a one-line correction with an obvious test.

If the request is still fuzzy, ask Codex to inspect the repo and identify the questions that materially affect the design before it edits files.

Steer instead of restarting

When the current run needs a correction, send the missing fact with Enter. Codex incorporates it into the active work. Use Tab for a follow-up that should run only after the current turn finishes.

Give evidence-based feedback: name the file, failed test, unwanted behavior, or constraint that was missed. “Make it better” provides little signal.

Make verification part of the task

Ask Codex to run the relevant build, test, lint, format, or type-check commands. For a bug, request a regression test that fails before the fix and passes after it. If a check cannot run, the final response should state why rather than imply that verification succeeded.

Review before accepting

Use /diff to inspect every changed and untracked file. Check for unrelated rewrites, weakened validation, missing edge cases, secrets, and changes outside the stated scope.

Use /review for a separate correctness pass. The final responsibility remains with the person accepting the change: run the application when behavior or visual output matters, and commit only a diff you understand.

Improve the system after repeated friction

When the same mistake happens twice, turn the correction into durable guidance. Update AGENTS.md, a test, a lint rule, or a reusable skill. The strongest Codex workflow gradually converts tribal knowledge into repository checks and concise instructions.