← Back to learning path
Chapter · Published

Task design for Codex

Write the goal, context, scope, constraints, verification, and delivery format so Codex can produce a stable result with less rework.

Source: start/07-task-design.md快速上手 (original language)
Chapter progress 0%Learning path progress 0% · 0/46 chapters completedContinue learning path →

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

ElementHow to write itExample
GoalState the expected result in one sentenceFix the lost login state after a refresh
ContextDescribe the symptom and relevant backgroundA refresh returns the user to the signed-out state
ScopeLimit the files or modulesChange only the auth module and related tests
ConstraintsState what must not changeDo not change the database schema or add a dependency
VerificationName commands or checksRun pnpm test auth
DeliveryDefine the review formatSummarize 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:

  1. Read-only analysis: identify the files and interfaces affected.
  2. Plan: describe the cut, risks, and verification.
  3. 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.

Next step

Next: Task execution and the verification loop.

Further reading

KnowledgeAI Agents: From Core Concepts to ProductionKnowledgeDesigning Reliable AI Automation WorkflowsKnowledgeStructured Outputs and Tool Contracts for Safe Agents
Product Hub Demo · V0.3