Codex CLI docs — where the agent helps and where it quietly hurts

On this page#

• What changes when an agent does this
• The prompt chain
• The gate
• What it gets wrong
• Rollback
• FAQ

What changes when an agent does this#

Codex CLI moves the bottleneck from producing code to proving that the produced change preserves the repository’s invariants. Typing becomes cheap; specifying scope, reviewing assumptions, and validating behavior become the real work. If your workflow still treats generated code as the deliverable, the workflow is wrong—the deliverable is verified evidence.

The Codex CLI documentation explains how to operate the tool. It does not define your repository’s acceptance boundary for you. You still need to provide the commands, architectural rules, generated-file policies, and behaviors that distinguish “the patch runs” from “the patch is safe.”

A large language model generates responses by modeling patterns in language and code; it does not independently possess your team’s unwritten intent. That mechanism explains the central risk: an agent can produce a locally convincing change that violates a constraint it was never given.

The practical shift looks like this:

| Before the agent | After the agent | |---|---| | Implementation consumes most of the time | Review and validation consume most of the time | | The engineer carries context while coding | The prompt must externalize relevant context | | Small mistakes appear during construction | Coherent mistakes can arrive as a complete patch | | Completion means the code is written | Completion means the invariants are demonstrated |

That is why “implement this ticket” is a poor production prompt. It delegates construction without establishing what the agent must preserve, how it should inspect the repository, or what evidence must exist before the change is accepted.

Photo by Christina Morillo on Pexels.

The prompt chain#

Use a staged prompt chain: inspect, plan, implement, and verify. Do not collapse those stages into one heroic instruction. Separate prompts create checkpoints where you can catch a false assumption before it spreads through code, tests, and documentation as one polished but incorrect solution.

The official CLI guide is the right reference for tool operation. The chain below addresses the layer the CLI cannot supply: repository-specific control.

1. Start with inspection.

   Inspect the repository for the code paths relevant to [change].
   
   Do not edit anything yet.
   
   Identify:
   - the current behavior and entry points
   - tests that define or imply the behavior
   - repository instructions and validation commands
   - generated files or files that should not be edited directly
   - assumptions you cannot verify from the repository
   
   Return a concise evidence-based summary with file references.

   “Do not edit anything yet” prevents premature implementation. Asking for unverified assumptions forces uncertainty into the open instead of letting the agent silently convert guesses into design decisions.

2. Request a bounded plan.

   Propose the smallest change that satisfies [acceptance criteria].
   
   State:
   - files expected to change
   - invariants that must remain true
   - tests to add or update
   - validation commands to run
   - rollback boundaries
   - any decision that requires human confirmation
   
   Do not implement the plan.

   The important phrase is “smallest change.” Agents are good at discovering adjacent cleanup opportunities, but bundling cleanup with behavior changes enlarges the review surface and makes rollback harder.

3. Authorize implementation only after reviewing the plan.

   Implement the approved plan only.
   
   Constraints:
   - do not modify files outside the approved scope
   - do not weaken or delete tests to make validation pass
   - do not add compatibility behavior unless required
   - stop if repository evidence contradicts the plan
   - summarize every deviation before proceeding

   This prompt turns the plan into a boundary, not a suggestion. If you want a reusable workflow for inspecting a patch, repairing defects, and preserving review control, Review and Repair packages that discipline around the change rather than around code generation alone.

4. Demand verification as a separate phase.

   Review the resulting diff as if you did not author it.
   
   Check:
   - acceptance criteria
   - repository invariants
   - unintended behavior changes
   - error paths and boundary conditions
   - stale comments, docs, fixtures, or generated artifacts
   
   Run the approved validation commands. Report:
   - commands run
   - pass or fail status
   - validation not performed
   - remaining uncertainty
   
   Do not claim success without command evidence.

   Self-review is not independent review, but it is still useful. It makes the agent search for contradictions and produces a concrete handoff for the human gate.

The gate#

The mandatory gate is the point after the plan and again after the final diff where a human checks scope, invariants, and evidence. Never let an agent’s confident summary substitute for inspecting the patch. The summary is navigation; the diff and validation output are the decision record.

At the pre-implementation gate, confirm five things:

• The agent found the correct entry points.
• The proposed files match the intended scope.
• The plan preserves explicit repository invariants.
• The tests exercise behavior rather than implementation trivia.
• Every unresolved assumption has an owner.

At the post-implementation gate, read the diff before reading the agent’s conclusion. Look specifically for widened scope, new fallback behavior, deleted assertions, duplicated logic, and changes to configuration or generated artifacts.

Then inspect the validation evidence against the commands agreed in the plan. A passing narrow test is not evidence that the repository’s required checks passed. A command that was not run must remain visibly unverified.

For engineers still building this review habit, PairFoundry Foundations provides the lower-commitment next step. The broader set of available workflows is listed in the PairFoundry packs overview.

Photo by Christina Morillo on Pexels.

What it gets wrong#

Codex most often fails by producing a reasonable interpretation of incomplete context, not by producing obviously broken syntax. The dangerous failures therefore look clean: the patch is coherent, tests may pass, and the explanation sounds decisive. Detection requires checking repository evidence and behavioral boundaries, not judging fluency.

Common failure modes include:

• Solving the visible symptom. The patch changes the nearest function while the invariant belongs at a different layer. Detect it by tracing every caller and identifying where the rule is already enforced.

• Inventing consistency. The agent sees two patterns and selects the cleaner one, even when the inconsistency is intentional. Detect it by asking which repository evidence proves the chosen convention applies here.

• Weakening the test oracle. A failing assertion is removed, broadened, or rewritten to mirror the new implementation. Detect it by comparing the behavioral claim before and after the patch.

• Expanding compatibility without authority. The agent adds fallbacks, aliases, or silent recovery because they appear helpful. Detect it by listing newly accepted inputs and newly suppressed errors.

• Editing derived output. A generated file changes directly while its source remains untouched. Detect it through repository instructions and by checking whether regeneration reproduces the diff.

• Declaring completion around missing evidence. The agent reports success after running only available or convenient checks. The Codex CLI docs can explain the interface, but only your repository can define the required validation set.

A useful rejection rule is simple: if you cannot connect each meaningful diff hunk to an acceptance criterion, invariant, or necessary test, the patch is not ready. Remove the unexplained work or send it back through inspection.

More workflow patterns belong in the PairFoundry workflows hub, but the principle stays constant: agent output is a proposal until repository-specific evidence closes the gap.

Rollback#

Rollback should restore one bounded agent change without discarding unrelated human work. Prepare for that before implementation by recording the starting state, keeping the scope narrow, and separating cleanup from behavioral changes. If recovery requires reconstructing which edits belonged to the agent, the workflow already failed.

Use this sequence:

1. Stop further edits and validation attempts.
2. Inspect the complete diff, including untracked and generated artifacts.
3. Separate the agent’s changes from pre-existing work.
4. Preserve any diagnostic evidence needed to understand the failure.
5. Revert only the identified change set using your repository’s normal version-control workflow.
6. Run the baseline validation that should pass without the change.
7. Rewrite the prompt with the missing invariant or corrected assumption before retrying.

Do not ask the same agent to “undo everything” without an explicit change boundary. It may reverse pre-existing edits or leave secondary artifacts behind. The safer rollback target is a reviewed diff, isolated commit, or otherwise enumerated file-and-hunk set.

Photo by Lukas Blazek on Pexels.

Related reading#

• Amazon mandating AI code review, with the guardrails that keep it honest
• Spec driven development: the prompt chain we actually run

FAQ#

When should I avoid using Codex CLI for a repository change?#

Avoid autonomous implementation when the acceptance criteria are unresolved, the repository has undocumented operational constraints, or the change crosses a security, data-loss, migration, or compatibility boundary that nobody has specified. Use the agent for inspection and option generation, then keep the consequential decision and implementation authorization with a human owner.

How is this workflow different from the official Codex CLI docs?#

The official documentation explains how to use the CLI; this workflow defines how to control a repository change. It adds staged prompts, an explicit human gate, invariant review, evidence requirements, and a rollback boundary. Those are project-governance decisions, so no general CLI document can infer them from your codebase.

What usually breaks when a whole team adopts the same agent workflow?#

Teams get into trouble when prompts are shared but acceptance standards remain implicit. Different engineers then approve different levels of evidence, while generated patches appear equally polished. Standardize repository instructions, required checks, prohibited edits, escalation conditions, and the exact point where human approval is mandatory.

How do I recover when the agent changed more than requested?#

Stop the run, enumerate the complete change set, and separate agent edits from work that existed beforehand. Revert only the identified hunks or isolated commit, restore generated artifacts through their source process, and rerun baseline validation. Then restart from inspection with the missing scope constraint stated explicitly.

Can I trust the agent’s tests if every check passes?#

No. Passing tests prove only that those tests passed under the conditions exercised. Review whether the assertions still express the intended behavior, whether important boundaries were omitted, and whether required repository-wide checks actually ran. Treat the agent’s report as an index to evidence, never as the evidence itself.