Terms in this guide: Acceptance criteria · Context
A practical learning path from a clear brief to a small, reviewed change.
Choose a task you can judge
Start with a small behavior you already understand: improve an empty state, explain a confusing function, or correct a layout at a specific screen width. You need a way to recognize success before you delegate the work. “Improve my website” leaves too many decisions unresolved; “keep article cards inside the same content width as the header” gives you an observable outcome.
Write down the current behavior and the desired behavior. Include one concrete example. If you cannot explain what should change, use the first conversation to explore the problem and choose a bounded next step.
Give the workspace enough context
Open the intended project and identify existing work that needs to be preserved. Point to relevant files, a screenshot, or a reproducible route. Ask Codex to inspect the project conventions before editing. An existing repository usually has better answers about installation and validation than a generic setup checklist.
If the project has no working instructions, draft a short AGENTS.md with the actual commands and the directories that matter. Keep facts separate from preferences. An instruction such as “run the documented test suite” is less helpful than the verified command and any known environment requirement.
Make the brief concrete
Use four parts: outcome, context, constraints, and evidence. The evidence section should say what you expect to observe, rather than demanding an unexplained claim that everything works. Give Codex permission to inspect the relevant code and ask it to flag missing information that changes the solution.
Outcome: Keep author article cards aligned with the site header.
Context: The author archive currently touches the viewport edges.
Constraints: Preserve existing article URLs and author information.
Evidence: Show the page at desktop and narrow mobile widths, and check for horizontal overflow.Inspect before expanding the task
Read the proposed change and compare it with your brief. For a user interface, open the actual route and use the controls. For a data transformation, inspect both a normal input and a meaningful edge case. Ask which checks ran and look at their actual results.
A successful first task is a good place to stop and record what helped. If the change reveals a separate problem, capture it as a follow-up. Keeping the first result small makes it easier to understand what happened and how to recover if it causes trouble.
WORKING CHECK
Before you move on
- The brief names an observable outcome.
- Project context and constraints are recorded.
- The actual result has been compared with the brief.
Continue along the learning path
Read the terminal walkthrough, write your repository briefing, then adapt the project brief template. Each step builds one reusable habit: choose the right context, explain the project, and define success.
If setup or instructions do not behave as expected, use the getting-started troubleshooting guide before adding more instructions.
Primary source: Codex CLI documentation. Source checked September 10, 2026.
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.