Home › Agent workflows › Systematic debugging CLAUDE.md

Systematic debugging CLAUDE.md

CLAUDE.md workflow for debugging with Claude Code: reproduce, isolate, hypothesize, verify, and avoid guess-fixes.

Claude Code (CLAUDE.md)Agent workflows

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# CLAUDE.md: Debugging workflow

Use this whenever the task is "fix this bug", "this is broken", or an error message.

## 1. Reproduce
- Get the exact error, stack trace, inputs, and environment. Run the failing command yourself.
- Turn the reproduction into a failing automated test when possible. If you can't reproduce it, say so and ask for more detail instead of guessing.

## 2. Isolate
- Read the stack trace from the top frame in our code. Open the actual files; don't assume what they contain.
- Narrow it down: smaller input, `git log -p` / `git bisect` for regressions, targeted logging around the suspect code.

## 3. Hypothesize
- Write down one or two hypotheses with the evidence for each. Pick the cheapest one to test.
- Test one variable at a time. Remove temporary logs afterward.

## 4. Fix the cause
- Fix the root cause, not the symptom. No blanket `try/catch`, `?.` chains, retries, or longer timeouts unless they *are* the right fix, and explain why.
- Check for the same bug pattern elsewhere (`rg` for similar code).

## 5. Verify
- The reproduction test now passes, the full suite passes, and the original command works.

## Report
Root cause (one paragraph), the fix, how it was verified, and any related risks.

## Don't
- Don't change multiple things at once and hope.
- Don't delete or skip failing tests to "fix" a build.