# Debug with an agent: reproduce, hypothesise, log, then fix

> Don't just ask the agent to fix it. Make it reproduce the bug, state a testable hypothesis, prove the root cause with logging or a failing test, and only then change code.

- **Category:** [Coding](https://stepgleam.com/categories/coding)
- **Difficulty:** Intermediate
- **Time:** ~30 minutes
- **Tools:** Claude Code, Git
- **Reliability score:** 76/100
- **Steps:** 5
- **Last updated:** 2026-10-26
- **Published:** 2026-10-26

## Tools used

- [Claude Code](https://code.claude.com/docs) — Reproduces, instruments and fixes the bug
- [Git](https://git-scm.com) — Keeps experiments reversible

## What you'll get

A fix backed by a reproduction and a regression test, not just the agent saying it is fixed.

## Who this is for

Developers who have watched an agent "fix" the same bug three times.

## Before you start

One r/ClaudeCode developer calls it the "Confidently Wrong" problem: describe a bug, the agent scans nearby code, changes something and declares it fixed. Their answer is a debugging subagent that follows the scientific method. Anthropic's guide describes the same shape for bug prompts.

## Steps

### Step 1: Give the symptom, the likely location and what fixed looks like

**Tool:** Claude Code

Anthropic's example: *"users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it."* The docs also say to give the command that reproduces it and whether it's intermittent.

**Prompt:**

```
Users report login fails after session timeout. Check src/auth/, especially token refresh. Reproduce it with a failing test first. Don't change source code until the test fails for this reason.
```

[Open step 1](https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix#step-1)

### Step 2: Make it demonstrably reproduce the problem

**Tool:** Claude Code

The debugging subagent's first rule is that it *"Demonstrably reproduces the problem"*. A failing test or a repro command it can run counts; a plausible explanation doesn't.

[Open step 2](https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix#step-2)

### Step 3: Ask for a testable hypothesis and targeted logging

**Tool:** Claude Code

Next it *"Forms a testable hypothesis"*, *"Designs an experiment using precise logging to test the hypothesis"*, and analyses the output *"to validate, invalidate, or update the hypothesis."* Another user simply puts the word "hypothesis" in their prompts.

**Why this works:** Logs turn guesses into evidence.

[Open step 3](https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix#step-3)

### Step 4: Only fix once the root cause is proven

**Tool:** Claude Code

*"Only when the agent has proven the root cause is it allowed to attempt a fix."* Anthropic adds: *"address the root cause, don't suppress the error."*

[Open step 4](https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix#step-4)

### Step 5: Clear the session after two failed corrections

**Tool:** Claude Code

Anthropic's rule of thumb: *"If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh"* with a better prompt.

[Open step 5](https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix#step-5)

## Pro tips

- Save the process as a subagent in .claude/agents/ so every bug gets it.
- Keep the reproduction test as a regression test.

## Common mistakes

- "Fix the login bug" with no reproduction.
- Accepting "it's fixed" without re-running the reproduction.
- Stacking patch on patch in one long session.

## FAQ

### Which tests work best?

The subagent author uses end-to-end tests first, because functional-level bugs show up there.

### Do I need a subagent?

No. The same steps work as a prompt; a subagent makes them repeatable.

---

Canonical guide: https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix
Read this guide as Markdown: https://stepgleam.com/guides/debug-with-an-agent-reproduce-hypothesise-log-then-fix.md