Codex Prompting

# Codex Prompting Playbook

Last updated: 2026-05-31

## Best Use Cases

Codex is strongest when the prompt gives it a concrete repository task, clear boundaries, inspection rules, and verification gates.

## Default Codex Prompt Shape

1. Goal
2. Operating role
3. Repository inspection rules
4. Source-of-truth rules
5. Non-negotiable requirements
6. Implementation scope
7. Plan mode rules
8. Execution rules
9. Verification rules
10. Browser QA rules, if UI is involved
11. Final report format
12. Stop conditions

## Plan-Only Prompting

Use plan-only when:

- The task is ambiguous.
- The work touches many files.
- The user wants approval before edits.
- The agent must research first.
- The blast radius is high.

Plan-only prompts must include "do not edit files yet" and a required approval phrase if execution should be gated.

## Execute-Immediately Prompting

Use execute-immediately when:

- The task is bounded and low-risk.
- Current repo inspection can identify the right edit.
- The user expects the agent to finish end to end.

Execution prompts should still require inspection, minimal changes, preservation of user work, and verification.

## Codex Verification Rules

Include the narrowest meaningful checks first:

- `npm run test`, `npm run lint`, `npm run typecheck`, `npm run build`, or project equivalents.
- Targeted unit tests when available.
- Browser or screenshot QA for UI.
- Secret scan for security or release work.
- Explicit "unable to verify" reporting when checks cannot run.

## Codex Stop Conditions

Codex should stop before:

- Commits, pushes, deploys, releases, package publication.
- Secret rotation or credential access.
- Production, billing, account, database, or destructive changes.
- Broad rewrites not required by scope.
- Conflicting user instructions or missing source-of-truth files.

## Prompt Smell Checklist

- Missing cwd or repo context.
- No non-goals.
- No verification command.
- No instruction about preserving user work.
- No browser QA for UI.
- No stop conditions for risky actions.
- Vague adjectives without concrete criteria.

## Codex Goal Versus No-Goal Guidance

Use a short Codex Goal when the user wants a persistent objective that Codex can keep checking across a longer run. The Goal should be concise, measurable, and should not carry detailed risky permissions.

Prefer no-goal first-message prompts when strict execution control matters:

- The user wants PLAN MODE ONLY.
- The work is security-sensitive.
- The work touches auth, sessions, secrets, encryption, password managers, billing, production, releases, deployments, databases, or destructive actions.
- The user explicitly says Codex should not execute before planning.

Why: OpenAI describes Goal mode as both a starting prompt and completion criteria. That is useful for continuity, but a strict plan-only task should not rely on Goal mode alone because the goal may encourage Codex to start work toward completion.

## PLAN MODE ONLY Pattern

Use this exact control language in Codex prompts when no edits are allowed: