Finding and fixing a bug

Bugs are where an agent shifts from convenient to genuinely valuable — but only if you set the turn up properly.

Give it three things

A reproduction. A command, a click path, a script. Something that makes the bug happen on demand.

The actual output. Paste it. The real text, not your summary of it.

The expected output. Say the number, the string, the behaviour you wanted.

node check.js prints cart total: 3. It should print cart total: 27 — the sum of the item prices, not the number of items.

That is a complete bug report and it took one line.

Run the reproduction yourself in the terminal below, then check that the test command works. Those two commands are the whole setup for a good debugging turn.

Let it run the tests

This is the part that changes everything. If the agent can run your test command, one turn becomes a loop it can drive: change something, run the suite, read the failure, adjust.

For that to work it needs to know the command. Tell it once in the session, or — better — write it down in your project instructions so every session knows. That is level 3, and this is the reason it exists.

Keep the noise out of the session

Test output is long. A failing suite can print hundreds of lines, and every one of them takes room that your actual instructions need.

Two ways to keep it manageable:

• Run the narrowest thing that fails, not the whole suite.
• Capture a long run into a file with a redirect, then look at only the part that matters — or filter it with a pipe into grep.

Claude Code can also hand noisy work to a subagent: a helper that reads the logs in its own separate context and reports back a summary, leaving your main conversation clean. You do not need it on day one, but when a session starts feeling sluggish and forgetful, that is what it is for.

Verify the fix yourself

The agent will report success. Run the original reproduction anyway.

Then ask the question people skip: why did this happen? A fix you understand tells you whether the same mistake is sitting in three other places. A fix you do not understand is a patch you will be afraid to touch later.

When it cannot find it

Sometimes two or three turns go by and it is circling. That is information: the reproduction is probably not reliable, or the cause is somewhere it has not been told to look. Go back and make the reproduction tighter rather than asking a fourth time.

And if the session has become a long argument, the next lesson is for you.

Try it yourself

A failing test and a proposed cause. Check the reasoning.