Tip · Last checked
Official sources were last checked on 2026-09-02. For context, instructions, verification, and safety boundaries, see the Codex documentation overview, Codex AGENTS.md documentation, and agent approvals and security.
Task design
Task design determines the quality of Codex's work. A useful request states the goal, context, scope, constraints, verification method, and delivery format.
Six elements of a task
| Element | How to write it | Example |
|---|---|---|
| Goal | State the expected result in one sentence | Fix the lost login state after a refresh |
| Context | Describe the symptom and relevant background | A refresh returns the user to the signed-out state |
| Scope | Limit the files or modules | Change only the auth module and related tests |
| Constraints | State what must not change | Do not change the database schema or add a dependency |
| Verification | Name commands or checks | Run pnpm test auth |
| Delivery | Define the review format | Summarize the cause, changes, tests, and remaining risks |
From vague to clear
Vague:
Please improve the login logic.
Clear:
Please fix the lost login state after a page refresh.
Context:
- After signing in, refreshing the page returns the user to the signed-out state.
- The session should be restored after a refresh.
Scope:
- Start with `src/auth` and its tests.
- Do not change the database or backend API.
Verification:
- Run `pnpm test auth`.
- Add a test for refresh recovery if the code needs one.
Delivery:
- Report the cause, changed files, verification results, and remaining risks.
Split a large task
Split a large request into three stages:
- Read-only analysis: identify the files and interfaces affected.
- Plan: describe the cut, risks, and verification.
- Implementation: make one small, verifiable change at a time.
Template:
Do not edit yet. Read [module or directory] and analyze how [goal] would affect it. Report:
1. The affected surface
2. Recommended implementation steps
3. Verification for each step
4. The smallest useful first change
Make uncertainty visible
Add this instruction when the task involves documentation, versions, dependencies, or migrations:
If you need to infer something, label it as an inference. If official documentation, code, and tests disagree, stop and describe the conflict first.
