Direct answer
Do not begin by asking the agent to “fix the bug.” First freeze the failing input, environment, revision, and expected behavior; let it trace the failure in read-only mode, review the proposed cause, then authorize a minimal patch and require the reproducer plus relevant regression suite to pass.
Key takeaways
- A stable reproducer is the entry condition for a trustworthy fix.
- Separate observed facts, hypotheses, and confirmed root cause in the investigation record.
- Change one causal path at a time and avoid opportunistic refactoring.
- Verify both the original failure and neighboring behavior after the patch.
Key facts
| Fact | Verified value | Evidence |
|---|---|---|
| History search | Git bisect performs a binary search across revisions using good and bad boundaries. | View source |
| Repository inspection | Codex CLI can inspect code, edit files, and run configured commands in a local repository. | View source |
| Interactive diagnosis | Claude Code common workflows include codebase exploration, implementation, and test execution patterns. | View source |
| Command control | Claude Code permissions can allow, ask for, or deny tool operations according to configured rules. | View source |
What this guide helps you solve
Use coding agents to diagnose and fix bugs while preserving a clear causal and verification trail.
Verification scope and limits
- Evidence basis
- Official documentationLocal verification
- Verification scope
- Covers reproduction, evidence preservation, causal narrowing, minimal remediation, regression tests, and release follow-up.
- Limits and invalidation conditions
- - Intermittent production failures may require telemetry and domain context unavailable to a local coding agent.
- - Passing the known reproducer does not prove that all related failure modes are resolved.
Capture a stable, redacted failure
Record the exact revision, command or request, sanitized input, observed output, expected output, timestamps, and relevant version information. Remove credentials and unrelated customer data before the material enters a coding-agent session.
Reduce the failure until it is repeatable without production access. If it remains intermittent, document frequency and correlated conditions without inventing a deterministic cause.
Trace the failing path in read-only mode
Ask the agent to locate entry points, state transitions, error handling, and recent changes associated with the failure. It should cite code locations and distinguish observations from hypotheses. For regressions with a known good revision, use history and bisect-compatible checks when practical.
- Keep the failing input and environment constant while testing one hypothesis.
- Inspect logs and error chains without exposing secrets.
- Check boundaries between client, network, service, storage, and external provider.
- Stop when the available evidence cannot distinguish competing causes.
Review the causal explanation before editing
A proposed cause should explain why the observed input reaches the failure, why the previous behavior or expected contract differs, and which evidence would disprove the hypothesis. Maintainers should review business assumptions before the agent changes validation, retry, or authorization logic.
If multiple causes are plausible, add instrumentation or a narrower test instead of letting the agent choose the easiest code change.
Authorize a minimal and reversible patch
Limit edits to the causal path and a regression test. Preserve public interfaces unless a reviewed contract change is required. Keep cleanup, dependency upgrades, and broad refactors in separate changes so rollback and review remain clear.
Verify the fix at multiple boundaries
Run the original reproducer, prove that the regression test fails without the fix, and execute the relevant package or service checks. Inspect logs and side effects for new errors. If the failure crossed an API boundary, test both the success response and documented error behavior.
- 01Original caseReplay the exact sanitized failure input.
- 02Regression proofShow that the new assertion detects the old behavior.
- 03Neighbor casesExercise boundaries most likely to be affected by the patch.
- 04Operational checkConfirm logs, metrics, cleanup, and rollback expectations.
Release with explicit residual risk
Summarize the cause, patch, verification commands, affected versions, rollback plan, and gaps. Monitor the same failure signature after release. If evidence contradicts the explanation, reopen diagnosis rather than extending the patch through unreviewed guesses.
Official sources and verification scope
This guide is based on public official documentation. Commands and configuration may change between client versions, so verify the linked sources before use.
Read the verification methodology