Prompt Codex with task briefs, plan mode and AGENTS.md

Prompting Codex well means giving each task a short brief with four parts (goal, context, constraints, and a “done when” list of commands that must pass) while durable project rules live in AGENTS.md. Plan mode catches a wrong approach before any file changes, and an independent review plus re-run gates prove the result without reading every line.

This page is for developers who drive Codex every day, and for tech leads who want the whole team’s prompts to produce the same kind of evidence. The situation it fixes: two engineers give Codex the same ticket. One gets a tested change in one turn. The other gets a plausible diff that touched 14 files, skipped the tests, and reported “all tests pass” anyway.

If you have not run a first task yet, start with your first Codex task. For tool-neutral prompting principles, see prompting techniques.

What you’ll walk away with from prompting Codex

• A rule for what belongs in the prompt, in AGENTS.md, in a skill, or in a test.
• A four-part task brief whose last part is a list of commands, not a wish.
• An order of operations: check context, plan, execute, review in a fresh thread, re-run the gates.
• A JSON Schema that turns a codex exec run into a report a script can check.
• Five copy-paste prompts, and the recoveries for the ways prompts fail in Codex.

What goes in the prompt, and what goes in AGENTS.md?

Put a line where it costs the least and fails the loudest. Codex loads AGENTS.md into every session, so every line there is paid for on every task, including the ones it has nothing to do with.

The instruction is…	Put it in	Why
True for this task only: the bug, the endpoint, the acceptance criteria	The prompt	It is noise in every other session.
True for every task in the repository: test command, layout, error style	AGENTS.md at the repository root	Codex reads it before doing any work, so you never retype it.
True for one service or package	A nested AGENTS.md in that directory	It loads only when Codex starts in or below that directory.
A multi-step procedure used now and then (release notes, a migration)	A skill	It loads when a task needs it, not on every turn.
A rule that must never be broken	A test, a lint rule or a hook	A prompt is a request; a failing gate is a fact.

Three loading rules decide whether your AGENTS.md text reaches the model at all (checked against Codex CLI 0.157.1 on 2026-09-26):

• One file per directory. From the project root down to the directory where you started Codex, each directory contributes at most one file: AGENTS.override.md if it exists, otherwise AGENTS.md. An override replaces its own directory’s AGENTS.md. It does not cancel the files above it; the chain still joins root to leaf.
• A shared budget. The project files share project_doc_max_bytes, 32 KiB by default. When the chain is too long, the deepest (most specific) files are the ones cut.
• Trust. Since Codex 0.150.0, an untrusted project supplies no project-level AGENTS.md. Only your global ~/.codex/AGENTS.md loads.

The full loader, the budget check for CI, and when to promote a rule to a skill are on Optimize AGENTS.md and skills for Codex.

Write a task brief Codex can finish

A brief has four parts. The first three steer the work. The fourth defines “finished” as something a machine can check, which is what lets you skip reading the diff line by line. Writing and refining instructions this way is prompt engineering.

1. Goal. One behaviour change, stated as an outcome: “POST /api/v2/orders returns 429 after 20 requests per minute per API key.”
2. Context. The files and the pattern to copy: “The route is src/routes/orders.ts. Copy the approach in src/middleware/auth-limiter.ts.”
3. Constraints. The boundary of the change: “Do not change the response body shape. Do not add dependencies. Touch only src/middleware/ and src/routes/orders.ts plus tests.”
4. Done when. Commands with an expected result: “pnpm test src/middleware passes, pnpm lint passes, and a new test fails if you remove the limiter.”

The last clause of step 4 matters most. A test that still passes after you delete the feature proves nothing, so ask Codex to show that its test can fail.

Copy-paste prompt: a verification-first task brief

Goal: POST /api/v2/orders returns HTTP 429 with a Retry-After header after
20 requests per minute per API key.

Context: the route is src/routes/orders.ts. Copy the approach in
src/middleware/auth-limiter.ts, including how it reads the key and the store.

Constraints: do not change the response body of successful requests, do not
add dependencies, and edit only src/middleware/, src/routes/orders.ts and
their tests. If you need to touch anything else, stop and ask.

Done when:
1. Write the test first in tests/middleware/orders-limiter.test.ts and run it.
   Show me it fails before the change.
2. Implement the limiter. Run `pnpm test tests/middleware` and `pnpm lint`.
3. Temporarily disable the limiter, rerun the new test, and show that it fails.
   Restore the limiter.
Finish with: files changed, each command you ran with its exit code, and
anything you assumed.

Prompt Codex in the right order

Most bad results come from the right prompt at the wrong moment: implementation before anyone agreed on the approach, or a review by the same thread that wrote the code.

1. Check what Codex already knows. Run codex debug prompt-input "ping" from the directory where you will start Codex. It prints the model-visible input as JSON, so you can confirm your AGENTS.md files are in it. Inside a session, /status shows the current configuration and token usage.

2. Plan before editing. For anything that touches more than one module, type /plan to switch to Plan mode and ask for a plan. Approve or correct the file list and the test list before Codex writes code. Correcting a plan costs one message; correcting a finished diff costs a new run.

3. Execute with the brief. Leave Plan mode and paste the four-part brief. Keep one behaviour change per thread. For a separate question mid-task, /side starts a side conversation in an ephemeral fork, so the main thread keeps its context.

4. Review in a fresh context. Run /review in a new thread, or codex review --uncommitted from the terminal. A reviewer that did not write the code does not share its blind spots. Review strategies for Codex covers how much review each risk class needs.

5. Re-run the gates yourself. Run the “done when” commands in your terminal or let CI run them. Codex’s own report is a claim; your exit codes are evidence. /diff shows every changed file, including untracked ones, so an out-of-scope edit is visible at a glance.

Copy-paste prompt: a plan you can approve (Plan mode)

Plan the migration of our Express error-handling middleware in src/middleware/
to Fastify hooks. Do not edit files yet.

List:
1. every file you will change and the transformation for each,
2. the existing tests that cover this behaviour, and the tests you will add,
3. the commands that prove the migration is complete,
4. what you will not change, and any risk you see.
Mark each step you are unsure about and say what would resolve it.

Copy-paste prompt: an independent review before merge

Review the uncommitted changes against the task below. You did not write
this code. Do not fix anything.

Task: POST /api/v2/orders returns 429 after 20 requests per minute per key.

Report, with file and line:
1. any change outside src/middleware/, src/routes/orders.ts and their tests,
2. any test that would still pass if the limiter were removed,
3. any behaviour change for successful requests,
4. anything the task asked for that is missing.
Answer "no findings" for a category only after you checked it.

Paste it into a new thread, or pass it as custom instructions: codex review --uncommitted - reads them from stdin.

Tune reasoning effort before you rewrite the prompt

When a well-formed brief still produces shallow work, the cause is often effort, not wording. GPT-6.1 Sol, Codex’s bundled default model since CLI 0.159.1, runs at low reasoning effort by default in Codex (CLI 0.162.1). The /model command chooses both the model and the reasoning effort. To pin a level for a run, pass it as a config override:

# Terminal: one run at high effort, without changing config.toml
codex -c model_reasoning_effort="high" "Find the root cause of the flaky test in tests/queue/retry.test.ts"

The corpus rule applies here: start on the default model, raise effort before you switch model, and switch model only when your own evaluation says so. Current models, effort levels and prices are on the models hub.

Make codex exec output machine-checkable

A prompt for an unattended codex exec run needs a different ending: nobody reads its prose. Ask for a fixed report shape with --output-schema, and write the final message to a file with -o. Save this as .codex/report.schema.json:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["status", "files_changed", "commands_run", "assumptions"],
  "properties": {
    "status": { "type": "string", "enum": ["done", "blocked"] },
    "files_changed": { "type": "array", "items": { "type": "string" } },
    "commands_run": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["command", "exit_code"],
        "properties": {
          "command": { "type": "string" },
          "exit_code": { "type": "integer" }
        }
      }
    },
    "assumptions": { "type": "array", "items": { "type": "string" } }
  }
}

Then run the brief from a file, in a workspace-write sandbox, and check both the report and the real gates:

# Terminal or CI: the brief is read from stdin ("-")
codex exec --sandbox workspace-write \
  --output-schema .codex/report.schema.json \
  -o codex-report.json - < briefs/orders-rate-limit.md

jq -e '.status == "done"' codex-report.json   # the agent's claim
pnpm test && pnpm lint                         # the evidence

The schema makes the report parseable, not true. A commands_run list full of zeros is still the agent’s account of itself, so the pipeline re-runs the gates. Run Codex non-interactively covers JSONL events, sandbox choice and authentication in CI.

Seed AGENTS.md from the repository, then cut it

/init creates an AGENTS.md with instructions for Codex. A generated file tends to restate what the model can read from package.json, so prune it before you commit it.

Copy-paste prompt: prune a generated AGENTS.md

Read AGENTS.md. For each line, classify it as:
KEEP - a rule you could not infer from the code, config or README,
CUT - restates something visible in package.json, tsconfig or the layout,
MOVE - a multi-step procedure that should be a skill,
GATE - a "never" rule that a test, lint rule or hook should enforce.
Rewrite AGENTS.md with only the KEEP lines, under 60 lines, commands in
backticks. List the MOVE and GATE lines separately with a proposed home.

Which prompt patterns waste a Codex run?

Pattern	Example	What to write instead
The kitchen sink	“Refactor auth, add tests, update docs and fix lint.”	One behaviour change per thread; queue the rest.
Placeholder overload	“Add [TYPE] validation to [ENDPOINT] using [LIBRARY].”	“Add Zod validation to POST /users, following src/schemas/order.schema.ts.”
The implicit expectation	“Fix the bug.”	The symptom, the input that triggers it, the suspected file, and a regression test to add.
A “never” with no check	“Never log card numbers.”	Keep the sentence, and add a test or lint rule that fails when a card number reaches the logger.
Self-grading	“Check your work and tell me it is correct.”	Commands with exit codes, then a review in a fresh thread.
The organisation handbook	A root AGENTS.md that describes every team and process.	Repository rules at the root, service rules nested, procedures in skills.

Copy-paste prompt: turn a vague bug report into a brief

Before changing any code, rewrite this bug report as a task brief with
Goal, Context, Constraints and Done when. Find the likely files yourself.
Done when must contain a failing regression test and the commands that
prove the fix. Ask me only the questions you cannot answer from the repo.

Bug report: login returns 500 when the email contains a plus sign.

How do you know a prompt worked without reading every line?

Judge the run by its evidence, in this order:

1. Scope. /diff lists only files the brief allowed. An extra file means the constraints were too loose or ignored.
2. Gates. The “done when” commands pass when you or CI run them, not only in Codex’s report.
3. Test strength. The new test failed before the change, or failed when the feature was disabled.
4. Independent review. A fresh-context /review or codex review --uncommitted reports no findings in the categories you named.
5. Sign-off. The engineer who wrote the brief approves the pull request on that evidence. Tech leads decide which risk classes also need a human read of the code; see review strategies for Codex.

When a brief passes these checks twice for the same kind of task, promote its durable lines to AGENTS.md or a skill so the next engineer does not have to rediscover them.

When prompts and AGENTS.md break in Codex

• Codex ignores a rule you wrote in AGENTS.md. Run codex debug prompt-input "ping" and search for the rule. If it is missing, check two causes: an empty AGENTS.override.md in the same directory hides the file, or the chain exceeded project_doc_max_bytes and the deepest file was cut. Separately, confirm the project is trusted (0.150.0 and later): prompt-input can still show AGENTS.md for an untrusted project (checked on 0.157.1), so a present rule there does not rule trust out. Fix the cause, then start a new thread.
• Codex edits files outside the brief. Name the allowed paths and add “If you need to touch anything else, stop and ask.” Revert the stray files with git restore <path> rather than asking Codex to undo them from memory.
• The report says tests pass, but CI fails. The agent ran a narrower command, or ran none. Put exact commands in “done when”, ask for exit codes, and let CI be the judge.
• The result drifts from the approved plan. Paste the approved plan into the execution prompt as the contract, and ask Codex to state which plan step each change implements.
• Quality drops late in a long thread. The context is full of old attempts. Run /compact, or start a new thread with a handoff note; context patterns for Codex covers when to do which.
• Shallow answers on a hard problem. Raise reasoning effort with /model or -c model_reasoning_effort="high" before you rewrite the brief or change model.

Where to go next with prompting Codex

• Optimize AGENTS.md and skills for Codex: the loader, the 32 KiB budget and skills.
• Context patterns for Codex: long threads, compaction and handoffs.
• Review strategies for Codex: match review depth to risk.
• Run Codex non-interactively: codex exec in scripts and CI.
• Spec-driven development: when a brief grows into a spec.
• The same topic for Claude Code: prompt engineering in Claude Code.