Contents
- 01Start From Zero and Choose the Right Surface
- 02Turn Intent Into Verifiable Work
- 03Configure Codex and Teach It the Project
- 04Bound Authority With Sandbox and Approvals
- 05Make the Change and Prove It
- 06Work Across Environments and Worktrees
- 07Delegate With Subagents
- 08Build the Extension Stack
- 09Automate, Embed, and Run Long Work Safely
- 10Capstone: From Command to Receipt
Make the Change and Prove It
Move from a scoped plan to a narrow implementation, then prove the result with code checks and the real user flow instead of stopping at a confident summary.
By the end
A reviewable diff, risk-matched automated checks, browser or native evidence, and a completion receipt tied directly to the task contract.
Inspect, plan, patch
Before editing, have Codex identify the smallest files that own the behavior, the neighboring pattern it intends to reuse, and the checks it will run. A good plan explains responsibility, not every keystroke. It should also call out overlap with existing uncommitted work and changes that would widen the task.
Prefer a narrow patch over a broad rewrite. Small diffs are easier to understand, test, reverse, and review. Do not mix formatting, dependency upgrades, architecture cleanup, and a user feature unless the contract explicitly includes them. If the agent discovers necessary adjacent work, treat it as a scope decision rather than silently absorbing it.
Use a layered verification stack
Different checks answer different questions. Static checks catch malformed or inconsistent source. Unit tests exercise isolated rules. Integration tests cover boundaries between components. A build confirms that the application can be assembled. A rendered or browser check proves that the user-facing path behaves in an actual interface.
Choose the smallest stack that covers the risk. A text-only documentation change may need link and build checks. A form workflow needs validation tests and an interactive submission. An authorization change needs an allowed case and a denied case. More tests are not automatically more proof if they never exercise the changed behavior.
Verify web work in the browser
Clean-account prerequisite: in the ChatGPT desktop app, select Codex or Work mode, open the Plugins Directory, install Browser, and start a fresh chat if the app asks you to refresh capability discovery. Confirm that Browser appears in the available capabilities and that the `@Browser` mention resolves before starting a verification workflow. If it is missing, stop and fix installation or workspace availability first; Browser is not automatically present on every account.
For a web change, use the built-in browser in the ChatGPT desktop app against the exact local, preview, or production URL being claimed. The built-in browser is not available in Codex CLI or the IDE extension. Start the documented development command in the integrated terminal, open the printed local URL, and ask Codex to use `@Browser` when you want it to navigate, click, type, inspect rendered state, take screenshots, or verify the page.
A screenshot proves appearance at one moment, not that a workflow succeeds. Pair visuals with interaction evidence and DOM or state observations. If authentication, payment, or another human-controlled step blocks automation, stop at that boundary and ask the user to take over rather than inventing credentials or bypassing controls.
Use browser comments to turn pixels into a scoped patch
The desktop browser and chat share the page. Open the local route, turn on annotation mode, select the exact element, and describe both the defect and what must remain unchanged. Codex can then connect the comment to the source change. Reopen the same state afterward; comments are instructions, not proof that the correction works.
For layout or runtime bugs, ask for the page URL, viewport, loading or error state, interaction steps, console errors, and network failures. Developer mode can expose DOM, styles, console, network, and performance information through controlled browser access, but it requires explicit approval because full CDP access can reveal sensitive browser internals. Use it only on the named site and task.
Treat every generated file as a reviewable artifact
The desktop app can preview documents, presentations, spreadsheets, and PDFs alongside the chat; the CLI can create them but cannot provide the same visual preview. Ask Codex to report the absolute output path, source inputs, file type, and validation it ran. Review the artifact itself, not only the prose summary that says it was created.
Give focused revision feedback: name the page, slide, sheet, table, chart, or passage, state the issue, and state what should remain unchanged. Keep screenshots and reports outside source control unless the repository intentionally owns them. A final artifact receipt includes file path, size or page count where useful, render or open check, and any unresolved visual limitation.
Use Computer Use for native boundaries
Some outcomes live in a desktop application or operating-system interface rather than a webpage. Computer Use can help operate those surfaces, but it is slower and more sensitive to layout, focus, dialogs, and human credentials. Use source files or command output when they can answer the question more reliably, and use native interaction only when native behavior is the thing being proven.
Keep observations separate from authority. Seeing an account, message, calendar, or private document on screen does not authorize sharing or acting on it. The task contract still controls what may be changed, sent, or disclosed.
Write a completion receipt
The final response should lead with the user outcome and then show the evidence: files changed, commands run, observed results, environment, and remaining risk. Link to important artifacts. State what was not done, especially deployment, data migration, or external actions that might otherwise be assumed.
A trustworthy receipt lets another person reproduce or challenge the claim. Avoid phrases like 'should work' when a check could have been run. When a check cannot run, explain the blocker and the narrower proof that was gathered instead.
Working reference
Commands and patterns
Start the verified project development command
npm run dev
Use this only when the project's package scripts document `dev`. Otherwise run the repository's actual command. Keep the terminal open and record the exact local URL it prints.
Desktop browser verification prompt
Use @Browser to open http://localhost:3000/settings. Reproduce the mobile overflow at 390px wide, inspect console errors, fix only the overflowing controls, then repeat the same interaction and save a screenshot receipt. Do not submit forms or change external data.
Run this only after installing Browser from the Plugins Directory and confirming it is available. Replace the route, state, viewport, and interaction with the task's real acceptance case.
Artifact creation prompt
Create a PDF handoff from the approved Markdown source. Preserve headings and links, include a contents page, report the output path, render-check every page, and list any clipped or overflowing element before calling it complete.
A useful artifact prompt defines source, format, structure, invariants, output path, and visual validation instead of asking only to 'make a PDF.'
When the happy path breaks
Failure modes
Symptom
The change works, but the diff contains unrelated rewrites or formatting.
Likely cause
Implementation was not constrained to the smallest owning files, or an automatic formatter ran across a broad scope.
Recovery
Preserve user changes, separate unrelated cleanup, and reduce the diff to behavior required by the contract before review.
Symptom
The build passes, but the button, form, or navigation still fails.
Likely cause
Compilation was treated as proof of the complete user journey.
Recovery
Run the critical path in the browser or native interface, inspect errors and state changes, and add regression coverage at the failing boundary.
Symptom
A screenshot looks correct but no one can reproduce the interaction.
Likely cause
Visual output was used as a substitute for functional evidence and environment details.
Recovery
Record the exact URL, setup, viewport, interaction steps, resulting state, and console or log evidence alongside the screenshot.
Symptom
Codex reports success even though one required check did not run.
Likely cause
The completion summary optimized for closure rather than matching the original acceptance contract.
Recovery
Audit every acceptance check, label unrun evidence as a remaining blocker, and avoid a completion claim until required proof exists or scope is explicitly revised.
Hands-on lab
Repair one user-visible defect
Take a reproducible bug from failing behavior to a narrow, independently verifiable fix.
- 01On a clean account, select Codex or Work mode, install Browser from the Plugins Directory, start a fresh chat if needed, and verify that Browser is available and the `@Browser` mention resolves. Do not continue until this prerequisite passes.
- 02In the desktop app, open the project and start its documented development command in the integrated terminal. Save the exact URL and startup output.
- 03Use the built-in browser to reproduce one user-visible defect. Record route, viewport, UI state, interaction steps, screenshot, console output, and expected behavior before editing.
- 04Leave one browser comment on the exact failing element, then ask Codex to locate the owning files, neighboring pattern, existing tests, and current dirty overlap.
- 05Approve a narrow plan and implement without unrelated refactoring. Add or update the smallest automated test that would catch the regression.
- 06Run targeted checks, then the relevant broader check such as typecheck, lint, or build.
- 07Repeat the original browser flow and one negative case; inspect console output and capture an after screenshot at the same viewport.
- 08Ask Codex to write a short Markdown verification artifact with the before/after evidence, output path, commands, and remaining risk. Open and review that file.
- 09Review the final diff file by file and write a completion receipt against the acceptance criteria.
Deliverable: A reproducible before state, narrow diff, regression test, interaction proof, and evidence-backed completion receipt.
Reusable artifact
Verification receipt
A standard proof packet for a completed Codex change.
Outcome: [what the user can now do] Environment verified: [local / preview / production + exact target] Changed files: [path -> responsibility] Automated checks: [command -> result] Critical user flow: [steps -> observed result] Negative case: [steps -> safe rejection or error] Visual evidence: [artifact links and viewport] Existing changes preserved: [yes + summary] External actions: [none or exact receipts] Remaining risk or unverified layer: [plain statement] Rollback: [commit, version, or reversal procedure]
Before you move on
Receipt checklist
- The bug or missing behavior is reproduced before implementation when practical.
- The final diff contains only the intended files and preserves unrelated user work.
- Automated checks exercise the changed rule or boundary.
- The actual critical user flow succeeds in the named interface and environment.
- The final response lists evidence, limitations, and rollback without overstating deployment state.
Primary sources
