Mastering Codex: Structured Prompts, Agents, and CLI Tricks for Maximum Productivity

1. Clarify How to Ask – More Important Than What

The official team stresses that the main bottleneck is not the model but how you describe the task. A good prompt should resemble a GitHub Issue, containing Goal, Context, Constraints, and Done‑when criteria.

Example of a poor prompt: "Optimize the checkout flow." vs. a detailed prompt that specifies the target directory, exact files to reference, constraints on the public API, and a test command to run.

Structured tasks lead to more controllable results.

2. Use Planning Mode for Complex Tasks

When a task is vague, Codex may produce useless solutions. The recommended workflow is Explore → Plan → Execute → Verify.

For cross‑module refactoring, data migration, auth‑billing changes, or CI/CD script edits, first let Codex read the code, explain behavior, and propose a plan before you apply changes.

# Step 1: Read‑only
"Read the current auth flow without modifying files. List request paths and files affected by token refresh logic, then propose a minimal implementation plan with verification commands."

# Step 2: Execute after approval
"Execute the approved plan, keep the public session format unchanged, and run auth unit tests, summarizing any test gaps."

This prevents Codex from spending time on guesswork.

3. AGENTS.md – Your Team Handbook for Codex

Instead of repeating code‑style rules, context, and prohibited actions in every session, place them in an AGENTS.md file at the project root (or sub‑directories for overrides). Codex reads this file automatically at session start.

# Validation
- After checkout changes, run `pnpm test --filter checkout`
- After TypeScript changes, run `pnpm lint`
- After DB schema changes, run `pnpm prisma generate`

# Constraints
- Do not modify public API response format without explicit approval
- Do not add production dependencies unless requested
- Do not read or write secret files; only reference env var names

# Patterns
- Reference validation helpers at `src/orders/validation.ts`
- Reference background jobs at `src/jobs/send-digest.ts`

When Codex repeats the same mistake, add a rule to prevent it.

4. Session Management: /resume and /fork

/resume

restores a previous session with full history, plan, and approved changes, so you don’t need to repeat context.

# Resume the last session
codex resume --last
# Resume from any directory
codex resume --last --all
# Resume and give next instruction
codex resume --last "Continue with step three and run tests"

/fork

creates a new branch of the conversation to explore alternative solutions without losing progress.

codex fork --last
# In the new thread: "Switch to solution B, an in‑memory LRU cache"

Together they act like a zero‑cost version control system for prompts.

5. Useful Slash Commands

Integrate these commands into daily work to boost efficiency: /review – automatic code review, diff comparison, and analysis of uncommitted changes. /model – switch model or inference depth without restarting. /permissions – change runtime permission mode (Auto / Read‑only / Full Access). /status – view current model, token usage, and loaded files. /compact – manually compress context to avoid window exhaustion. /skills – browse and invoke packaged Skills. /plan – enter planning mode for Codex to propose a solution before execution.

Typical scenarios include running /review after coding, switching to a higher inference depth with /model for risky reasoning, using /permissions for cautious changes, and compressing context with /compact when sessions become slow.

6. Validation Is the Real Delivery

Codex’s final code change message is not a delivery; the delivery is passing tests, observable behavior change, and a bounded diff.

Done when:
- `pnpm test --filter auth` passes completely
- Public API response format remains unchanged
- List modified files and any remaining risks

If tests are missing, ask Codex to write minimal test cases or provide manual verification steps. Use /review as a second check but not a replacement for proper validation.

7. Model Context Protocol (MCP) – Add Only What You Need

MCP lets Codex access external systems like GitHub Issues, CI status, or DB schema. Before adding an MCP, ask four questions: frequency of context changes, copy‑paste cost, need for read‑only vs. tool calls, and reuse frequency. Start with the highest‑value integration and expand only after it stabilizes.

8. Inference Depth and Speed Mode

Switch inference depth mid‑session with /model:

minimal – simple tasks like variable renaming

low – small refactors or feature additions

medium – regular development tasks

high – complex cross‑module refactoring or new architecture

x‑high – data migration or security‑critical logic

Use /fast (currently GPT‑5.4 only) for 1.5× speed without losing intelligence; ideal for quick prototyping but not for bulk CI jobs.

9. Environment Quality Determines Codex’s Ceiling

Many failures stem from environment issues: missing dependencies, absent validation commands, wrong env vars, unstable setup scripts. Ensure the following are configured before starting:

Runtime versions (Node, Python, Go, etc.)

Package manager and install commands

Linter, formatter, type‑checking tools

Validation commands listed in AGENTS.md Required cloud environment variables

Idempotent, repeatable setup scripts

Never paste real secrets into prompts or repository files; Codex removes secrets before the agent phase.

10. Permissions and Network – Keep Defaults Tight

Codex has two safety knobs: sandbox mode (read/write limits) and approval policy (when to pause for confirmation). Default settings are restrictive. Loosen for low‑risk tasks (formatting, unit tests, read‑only exploration). Keep strict for high‑risk tasks (dependency installation, deployment script changes, internet access, secret handling, data migration, bulk deletions, auth/billing changes).

Network access is disabled by default; if enabled, whitelist only necessary domains and HTTP methods, and audit logs. Untrusted web reads can lead to prompt injection.

Conclusion

Using Codex to its fullest isn’t about memorizing commands; it’s about establishing collaborative habits: structured task descriptions, planning for complex work, mandatory validation, and codifying rules in AGENTS.md. Though the methodology adds overhead, it shifts developer time from repetitive guessing to judgment and review, dramatically improving productivity.