From Issue to Tested Change: A Codex Delivery Workflow

Start With Observation

Do not start by asking Codex to write code. Start by asking it to inspect the current system and explain the behavior that needs to change.

A strong investigation request might say:

Trace the export request from the button through the API route and credit ledger.
Identify where authorization, credit consumption, and idempotency are enforced.
Do not edit files yet. Report the relevant files, current behavior, and test coverage.

This creates a shared model before implementation. It also reveals when the requested change crosses more boundaries than expected.

For a bug, reproduce it first. Capture the error, the state that triggers it, and the expected behavior. A fix without a reproduction can easily address the symptom instead of the cause.

Design the Smallest Change

Once the current behavior is understood, ask for a short implementation plan. The plan should name the files, behavioral contract, persistence impact, and tests.

Keep scope narrow:

• Prefer an existing helper over a new abstraction.
• Change the smallest ownership boundary that can solve the problem coherently.
• Avoid drive-by refactors.
• Preserve unrelated user changes in a dirty worktree.
• Make data migrations explicit and reversible where possible.

For larger work, split the change into reviewable slices. A schema migration, API behavior, UI state, and analytics change may belong in one feature, but they do not all have to be implemented in one opaque step.

Test in Layers

Testing should follow the risk:

1. Unit tests for classification, calculations, sanitization, and policy logic
2. API tests for authentication, validation, provider failure, and idempotency
3. Functional tests for the user-visible journey
4. Build and type checks for integration health
5. Browser verification for layout, state transitions, and console errors

Ask Codex to run the narrow test immediately after the change. Fast feedback makes failures easier to diagnose. Run the broader suite before handoff.

For asynchronous or paid workflows, test more than the happy path. Include loading, waiting, partial success, retries, duplicate events, insufficient credits, and provider unavailability.

Prepare a Reviewable Diff

Before the work is handed to a reviewer, Codex should inspect the final diff and answer:

• Which behavior changed?
• Which files changed and why?
• What checks passed?
• What was tested manually?
• What remains unverified?
• Did any generated files, secrets, or unrelated changes enter the diff?

The reviewer should be able to connect the issue, implementation, tests, and user behavior without reconstructing the entire task history.

Codex can accelerate implementation and evidence gathering. The team still decides whether the evidence is sufficient for the risk.

Official references

• How OpenAI uses Codex
• Codex for engineering teams
• Codex use cases