On this page#
What changes when an agent does this#
Claude Code is an agentic coding tool that can inspect a repository, edit files, and run development commands. When it writes Python, the bottleneck moves from typing code to controlling scope and proving correctness. The agent should propose, implement, and verify; humans must still protect the repository’s invariants and approve the final diff.
That shift matters because Python makes plausible mistakes unusually cheap. An agent can produce valid syntax, pass a narrow test, and still break import boundaries, exception behavior, serialization formats, type assumptions, or transactional guarantees.
The right workflow therefore treats the agent as an implementation engine inside a verification system:
- State the invariant.
- Map the affected code before editing.
- Separate the plan from the patch.
- Run the repository’s own checks.
- Stop for human review.
- Keep rollback mechanical.
Do not ask Claude Code to “fix the bug” and accept whatever turns green. That prompt delegates both the change and the definition of success. Those are different jobs.
The official Claude Code documentation explains the tool’s operating model and capabilities. Your repository still has to supply the acceptance contract: what may change, what must not change, and what evidence is sufficient.
Photo by Christina Morillo on Pexels.
The prompt chain#
Use a prompt chain, not one oversized instruction. Each phase should produce evidence that constrains the next phase: first a repository map, then a plan, then a bounded implementation, and finally verification. This keeps an early misunderstanding visible instead of allowing it to harden into a large, internally consistent, wrong patch.
Phase 1: Make the agent map the change#
Start by forbidding edits. You want Claude Code to identify the execution path, existing tests, local conventions, and uncertainty before it has invested in an implementation.
Do not modify files yet.
Investigate this task: [describe the bug or change].
Identify:
- the entry point and affected execution path;
- the invariant that currently fails;
- existing tests covering that invariant;
- repository conventions this change must preserve;
- the smallest likely change surface;
- anything you cannot establish from the repository.
Return file paths and a concise explanation. Do not propose unrelated cleanup.“Do not modify files yet” is essential. Without that boundary, investigation and implementation blur together, making assumptions harder to challenge.
Claude Code can inspect and act across a codebase, as described in the official overview. That reach is useful only when the prompt narrows the target.
Phase 2: Demand a falsifiable plan#
The plan must connect each proposed edit to an invariant and a check. A list such as “update service, add tests, run lint” is not a plan; it does not say why the change is sufficient or how failure will be recognized.
Propose an implementation plan without editing files.
For each proposed change, state:
- the file and symbol involved;
- the behavior that will change;
- the invariant it preserves;
- the test or check that would fail if the implementation is wrong.
List explicit non-goals. Prefer the smallest coherent patch.
If repository evidence conflicts with the request, stop and explain the conflict.The phrase “test or check that would fail” prevents decorative verification. A useful test distinguishes the intended behavior from the likely wrong implementation.
If you need a reusable version of this workflow, PairFoundry’s Review and Repair pack turns the investigation, patch, and review boundaries into a repeatable operating pattern.
Phase 3: Allow a bounded implementation#
Only after the map and plan survive review should the agent edit. Repeat the scope restrictions because agents optimize toward task completion and may interpret nearby cleanup as helpful.
Implement the approved plan.
Constraints:
- preserve public behavior except for the requested change;
- do not add dependencies;
- do not rename or reorganize unrelated code;
- follow existing Python, typing, and test conventions;
- add or update the smallest test that proves the invariant;
- stop if the required change exceeds the approved files or symbols.
After editing, summarize deviations from the plan.“Stop if” clauses are guardrails, not politeness. They turn scope expansion into a visible decision instead of a silent side effect.
Phase 4: Make verification adversarial#
Do not ask, “Does it work?” Ask the agent to try to disprove its own patch using repository-native checks and concrete counterexamples.
Verify the patch without making further edits.
Run the repository’s existing relevant checks. Then inspect the diff for:
- changed behavior outside the request;
- untested branches and boundary values;
- exception, cleanup, and rollback paths;
- typing or interface drift;
- tests that pass for the wrong reason.
Report commands and outcomes exactly. Separate facts from assumptions.
If a check cannot run, say why; do not substitute a claim of correctness.The Claude Code documentation describes how the tool works with code and development tasks. It cannot decide which passing check is meaningful for your system. That judgment remains part of the repository’s engineering design.
The gate#
The gate is a mandatory human review after verification and before the patch is merged, committed, or handed to another task. The reviewer is not there to reread every line mechanically; they must confirm that the diff matches the approved change surface and that the evidence actually protects the named invariant.
Review these items in order:
- Intent: Does the patch solve the stated problem rather than a nearby problem?
- Scope: Are all changed files necessary? An unexplained file is a stop signal.
- Invariant: Where is the protected behavior encoded—in implementation, test, or both?
- Failure path: What happens on invalid input, partial work, cancellation, or an exception?
- Compatibility: Did signatures, serialized shapes, import paths, or exception types drift?
- Evidence: Could the new test pass if the implementation were reverted or deliberately broken?
The last question catches weak tests quickly. A test that merely executes the new path is not proof.
For teams still developing this review discipline, the free PairFoundry foundations track is the better next step than adding more automation. More agent autonomy does not repair an undefined acceptance gate.
Photo by ThisIsEngineering on Pexels.
What it gets wrong#
Claude Code usually fails through coherent overreach, not obvious nonsense. The dangerous patch looks reasonable, follows local style, and passes the checks it selected. Detect failure by comparing the diff against the invariant and approved scope, not by judging how polished the explanation sounds.
| Failure mode | What it looks like | How to detect it | |---|---|---| | Solving the symptom | A guard suppresses an exception without repairing invalid state | Trace the state before and after the failing path | | Over-broad cleanup | Renames, abstractions, or formatting appear beside the fix | Require a reason for every changed file and symbol | | Weak tests | The test repeats implementation details or only asserts success | Break or revert the behavior and see whether the test should fail | | Interface drift | A return type, exception, or serialized field changes quietly | Compare callers and boundary contracts, not only the edited function | | Happy-path bias | Cleanup, retry, cancellation, or partial failure is ignored | Enumerate exits and resource ownership explicitly | | False certainty | The report says “verified” when a command did not run | Require exact commands, outcomes, and unresolved assumptions |
Another common mistake is allowing the agent to rewrite tests until they match its patch. Existing tests may be wrong, but changing production behavior and its previous contract in one step destroys the independent signal. Stop and review that decision separately.
Official guidance explains the tool; it does not know your business invariants. Browse the broader PairFoundry workflow library for related operating patterns, or compare the available PairFoundry packs when the problem extends beyond review and repair.
Rollback#
Rollback should restore one known pre-agent state without requiring the agent to remember what it changed. Create a clean boundary before the task, keep unrelated work outside the change set, and inspect the final diff. If rollback requires manually reconstructing files from the conversation, the workflow was unsafe before coding began.
Use this sequence:
- Record the repository state before edits.
- Keep the task in an isolated branch or equivalent change boundary.
- Avoid mixing generated edits with unrelated local work.
- Save the agent’s plan and verification report separately from source changes.
- If the gate fails, discard only the isolated patch.
- Re-run the relevant baseline checks after restoration.
Do not ask the agent to “undo your changes” as the primary recovery method. It may miss generated files, partial edits, or changes introduced by commands. Repository-native version control is the authority; the chat transcript is not.
Photo by Al Nahian on Pexels.
Related reading#
- How to upgrade Claude Code: making the output reviewable, not just correct
- Cursor review: making the output reviewable, not just correct
FAQ#
These are the practical boundaries engineers usually need before adopting this workflow: where it fits, how it differs from product documentation, what changes in a team, and when recovery becomes unreliable. The common thread is simple: Claude Code may perform the work, but repository evidence and human approval define whether that work is acceptable.
When should I not use Claude Code for a Python change?#
Do not delegate a change whose invariant cannot yet be stated or observed. If nobody can explain the correct failure behavior, compatibility boundary, or acceptance signal, the agent will optimize against ambiguity. First clarify the contract; then use the agent to implement and challenge it.
How is this different from following the official Claude Code documentation?#
The official documentation explains Claude Code’s capabilities and operation. This workflow adds repository governance: staged prompts, explicit non-goals, falsifiable verification, a human gate, and mechanical rollback. Those controls are specific to working safely in a codebase where passing a command is not the complete definition of correctness.
What is the biggest team risk with this approach?#
The biggest risk is inconsistent acceptance standards. One engineer may require invariant-level tests while another accepts a plausible diff and a passing check. Put the prompt chain, allowed commands, review gate, and rollback boundary in the repository so every agent-assisted change faces the same contract.
What should I do when the agent changes more files than planned?#
Stop before requesting cleanup. Inspect why the scope expanded, then either approve a revised plan or discard the isolated patch and restart with tighter boundaries. Letting the agent rationalize an already-expanded diff rewards completion over control and makes review substantially harder.
Can I trust the agent’s verification report if every check passes?#
No. A passing report proves only that the selected checks passed. Confirm that the checks exercise the named invariant, can fail under a plausible wrong implementation, and cover relevant failure paths. The human gate exists precisely because command success and system correctness are not equivalent.