Class 9 · 9.6

Debugging strategies: a disciplined approach

When the agent gets stuck or marches off a cliff, reach for this playbook: snapshot first, a fast copy-paste loop, a disciplined debug.md method, and the red flags and pro tips that separate a fix from a fresh mess.

🎯 Goal: debug like a pro⏱ Read: 15 min🧭 Type: playbook

Today the build went almost too smoothly — no juicy bug to chase together. So instead, here is the debugging playbook: the exact strategy to reach for when Claude Code (or any coding agent) gets stuck, starts flailing, or confidently marches off a cliff. Learn this and hard bugs stop being scary.

01Always take a snapshot first

Debugging is where agents most often wander down a tangent and make things worse. So before you start, freeze a known-good point: do a real git commit.

Don't rely on rewind here

Claude Code's rewind only backs out file edits it made. It cannot undo the side effects of running a script — a migrated database, deleted files, installed packages. A git commit is your only trustworthy restore point when things go sideways.

02Mode one: the fast copy-paste loop

For small, obvious errors, the most productive move is almost lazy. Take the error message or stack trace, copy it, and paste it straight into Claude — as is. No preamble, no “I was doing X and then Y happened.” Just paste. It fixes something? Run again, paste the next error. Copy, paste, repeat.

Why this works so well

For simple problems, Claude “gets the joke” — it has the surrounding context, reads the trace, and figures it out. Optimise for efficiency: the fastest path is often just feeding it the raw error again and again until it is green.

03Mode two: the disciplined method

When the quick loop stalls — or starts making things worse — stop. Revert to your last commit and switch to a regimented approach built around a single scratch file, debug.md, that Claude writes to as it goes. Guide it through these moves in order:

Slow, regimented, and it works — each stage is written down so nothing is lost to a compact.

Reproduce it consistentlystep 1

“This is the issue. Reproduce it every time and document exactly how in debug.md.” No fix is trustworthy until the bug is reliable.

Investigate deeplystep 2

Read every related log, add extra logging, gather information, and web-search for others with the same problem. Record findings in debug.md.

Form & sanity-check hypothesesstep 3

List plausible causes, then challenge each. Land on a single root cause.

Prove the root causestep 4

Demonstrate that it really is the cause and document the proof. Only then fix it — and prove the fix works consistently.

Capture the lessonstep 5

Write what you learned into CLAUDE.md so the mistake is not repeated after the next clear or compact.

04The “I found it!” red flag

There is a classic failure mode to watch for. Claude searches the web, finds one old Stack Overflow post or GitHub issue that looks similar, and announces with total confidence: “Found it — this is a known problem, the fix is to downgrade this package.” Then it rewrites half your code.

Challenge it hard

What it misses is perspective: that “known problem” may be a single report from three years ago that nobody ever answered. Push back: “Did more than one person report this? Do you have evidence it is common? Is it really the same thing we are seeing?” A real example it loves to invent: “an LLM cannot use tools and structured outputs in the same call — that is the bug” — completely fictional, yet stated with total confidence. When it latches on like that, stop it, restore your commit, tell it ‘this is not the problem, try again’.

05Two pro tips for the hardest bugs

Pro tip 1

🕵️ Bring in a different LLM

Hand the same problem to a different model — Codex, Antigravity, whatever. Each has different training and prompting, so it may spot what Claude missed. Like a genuine second pair of eyes.

Pro tip 2

🔧 Use the systematic-debugging skill

There are excellent debugging skills. The popular systematic-debugging one mirrors this method but goes deeper — especially on web search and on its iron rule: find and prove the true root cause before touching a fix.

The through-line

Every technique here fights the same enemy: jumping to conclusions. Snapshot so you can undo a bad guess; reproduce so you know the bug is real; prove the root cause so you are not band-aiding a symptom. Discipline beats speed on the hard ones.

That's a wrap on Class 9

We read work from Jira via an MCP server, ran it through FeatureDev's disciplined process, and shipped a full feature as a GitHub PR — all from one command — and we now have a debugging playbook for when things go wrong. Tomorrow we bring it all together into a real SaaS product.

✓ Key takeaways

Snapshot with git commit before debugging — rewind cannot undo a script's side effects.
Fast mode: copy-paste the raw error, repeat, until green.
Stuck? Revert and go disciplined: reproduce → investigate → hypotheses → prove root cause → fix → prove fix, all in debug.md; lessons to CLAUDE.md.
Beware “I found it!” seized from one old post — demand evidence it is really your bug.
For hard bugs: try a different LLM, and use the systematic-debugging skill (prove the root cause — the iron rule).