CODEX PROMPTING

# Codex Prompting
*Version:* v1.0  
*Date:* 2026-03-29  
*Last reviewed:* 2026-03-29

This file captures the prompting patterns that make Codex more reliable in practice.

## Core prompt shape
For most tasks, structure the request like this:
- Goal: what outcome you want
- Context: which files or decisions matter
- Constraints: what not to change, risk boundaries, or stack limits
- Done when: what success looks like and how to verify it

This follows current OpenAI guidance to make requests concrete, scoped, and easy to
verify.

## Plan first for complex work
If the task is ambiguous, risky, or large, ask for a plan before implementation.
Examples:
- propose the smallest correct slice
- identify files to change first
- list risks and unknowns
- say what tests or evals will prove it worked

## Use task-specific context packs
Treat context like a finite attention budget.

Practical default:
- start with `docs/CONTEXT_ENGINEERING.md`
- load the smallest relevant pack for bootstrap, implementation, review, prompt/eval work,
  or external research
- pull additional docs and files only when the current step requires them
- avoid broad "read the whole repo" prompts unless you are intentionally doing a full audit

## Keep task slices small
Codex is strongest when prompts ask for one focused, reviewable slice instead of a broad
multi-feature rewrite.

Practical default:
- one task that can usually be completed and verified in one focused session
- explicit non-goals to avoid scope creep
- clear verification target before editing starts

Fresh-repo rule:
- if the project manifesto and charter are still placeholders, first ask Codex to draft the
  product artifacts instead of prompting it to jump straight into implementation

## Point Codex at the repo, not chat history
Good prompts usually name the files Codex should read first. Prefer:
- `AGENTS.md`
- `docs/CONTEXT_ENGINEERING.md`
- the relevant docs in `docs/`
- the active queue in `work/ACTIVE_TASKS.md`
- the detailed work item in `work/items/`
- the prompt or eval files involved

## Use issue-style prompts
Treat your prompt like a well-written issue or task ticket.
Include:
- the current problem
- the target behavior
- explicit non-goals
- relevant files
- expected verification

## Use MCP and official docs when context is external
When the repo is not enough:
- use official docs instead of copied summaries
- prefer MCP servers when they provide trustworthy source access
- for OpenAI or Codex questions, prefer the OpenAI docs MCP server if available

## Compact long sessions back into the repo
If the session grows long, ask Codex to write the durable state back into repo files
instead of relying on chat memory.

Minimum compaction payload:
- current goal
- decisions made
- files touched or to read next
- verification run and results
- blockers or open questions
- next action

Default destinations:
- `work/items/` for task-local state
- `docs/DECISIONS.md` for enduring workflow or architecture decisions
- `work/LEARNINGS.md` for reusable discoveries

## Prompt asset design for runtime prompts
When the product itself sends prompts to models:
- keep stable instructions near the top
- keep reusable examples above highly variable inputs when practical
- keep machine-consumed output contracts explicit
- keep prompt changes linked to eval changes
- run `python scripts/run_prompt_evals.py` when changing prompt/eval assets

## Recommended prompt templates
### Planning request