The common failure with AI debugging is a fix that makes the symptom disappear without explaining it, so the bug comes back in a different shape. This agent's definition of done is an explanation of why the bug happened, a test that failed before the fix, and a note on what is still uncertain.
When to use the Debugging Specialist agent
- A test fails and the reason is not obvious
- A bug only shows up in production or only sometimes
- A regression appeared after a dependency or config change
- You fixed something twice and it came back
What is in the agent file
| Name | debugging-specialist |
|---|---|
| Tools | Read, Write, Edit, Grep, Glob, Bash. It can edit files and run commands, so review its diff. |
| Model | sonnet, up to 45 turns per task |
| Kit | Engineer kit, 117 lines |
How it works. Beyond its role statement, the file sets out 6 rules it follows: Hypothesis discipline; Evidence techniques, cheapest first; Non-reproducible classification; Cause vs crash site; Severity rubric; Fix protocol.
What it reports. Every run ends in the same structure: Symptom, Reproduction, Hypotheses considered, Root cause, Fix, Proof, Residual uncertainty.
Excerpt from the agent file
The settings and opening instructions, as they appear in .claude/agents/debugging-specialist.md:
---
name: debugging-specialist
description: Finds the root cause of a defect through reproduction, minimization and differential evidence, then applies the smallest safe fix with regression coverage. Use PROACTIVELY for bugs, regressions, flaky tests, unexpected behavior or production incidents.
model: sonnet
maxTurns: 45
tools: Read, Write, Edit, Grep, Glob, Bash
---
You are a Debugging Specialist. Success is not that the symptom disappeared — it is that you can explain **why it happened** and why your change prevents it.
1. **Preserve evidence first.** Capture the failing log, the bad row, the request payload, the stack. Debugging destroys evidence — a restart, a cleared cache, an edited row — and if the first fix fails you will want the original state.
2. Reproduce, or document precisely why you cannot.
3. Minimize until nothing can be removed without the failure disappearing.
4. List at least three competing hypotheses before investigating any.
5. Gather evidence that **discriminates** between them.
6. Identify the cause, not the crash site.
7. Apply the smallest fix. Write the failing test **first**.
8. Re-run validation and state remaining uncertainty.The full file continues with the rules above and the exact report format. It is included in the Agentsforce kit.
Example requests
Name the agent to be sure Claude uses it, or describe the task and let its description trigger it:
- "Use debugging-specialist to find why the checkout test fails on CI but passes locally."
- "Users report duplicate orders since Tuesday. Here is the log. Find the root cause."
- "This endpoint returns 500 for about 1% of requests. Investigate before changing anything."
- "Use debugging-specialist on this stack trace and add a regression test with the fix."
When to use a different agent
| If you need | Use instead |
|---|---|
| Building a new feature | Use the main session, senior-implementer or tdd-engineer |
| Slow pages or queries with no wrong behavior | Use performance-engineer, or database-engineer for a query |
| Reviewing a change before it merges | Use code-reviewer |
Works well with
- Code Reviewer: checks what a change did, not whether a file looks fine
- TDD Engineer: writes a failing test, watches it fail for the expected reason, writes the smallest code that passes, then refactors, one small slice at a time
- Database Engineer: changes schemas and queries without risking your data
Related playbooks in the kit, which Claude loads when the task calls for them: root-cause-analysis, flaky-test-triage, regression-test-design.
How to get it
- Write your own: the free Subagent Generator drafts a starter debugging specialist file you can edit and save in
.claude/agents/. - Use the tested version: Agentsforce includes this agent with 54 other specialists and 89 playbooks for a one-time $49, installed with one command.
Frequently asked questions
Can Claude Code debug on its own?
It can, but without a method it tends to patch the line that crashed. A debugging subagent gives it a fixed process: reproduce, minimize, weigh competing hypotheses, then fix the cause and prove it with a test.
Why does it need edit and shell tools?
Reproducing a bug means running the code and tests, and the fix means editing files. It gets Read, Write, Edit, Grep, Glob and Bash for that reason, which is also why you should review its diff.
What if the bug cannot be reproduced?
It narrows down which kind of failure it is first: intermittent in one environment, environment-specific, only under load, only for one user or tenant, or only after a duration. Each points at different causes, and a fix shipped without a repro is labelled as a hypothesis.