AI-Assisted Debugging in Practice

Debugging is the work engineers spend the most time on each day, and the work whose value is least acknowledged. A bug might cost you two hours, an hour and a half of which is "finding where it is and why," while the actual code change may take two minutes. AI compresses those two hours into twenty minutes—provided you know how to use it. Use it wrong, and it will only tell you "please check your network connection."

Below are the practical methods I've distilled after debugging hundreds of bugs with Claude Code and in-IDE AI.

1. AI debugging's real opportunity, and why it keeps giving you platitudes

The three things AI can genuinely accelerate on the debugging chain are: reading logs, analyzing stacks, and fast localization. What these three share is—high information density, the need to correlate across files, but a short reasoning path. A 200-line error log takes the human brain five minutes to scan, but AI can tell you in two seconds that "the Cannot read property 'id' of undefined on line 47 is the root cause, and the source is that getUser returned null."

But most people's experience with AI debugging is "a string of platitudes." The reason isn't that the model is bad, but that you haven't given enough information. If you only say "my login endpoint is erroring, take a look," of course it can only reply "please check: 1. network connection 2. endpoint address 3. request parameters 4. backend logs." The AI isn't brushing you off; with no context, it can only output a "generic troubleshooting checklist."

Key line: AI isn't a fortune teller—it works with whatever you give it.

2. Paste the right information: context determines diagnostic quality

The golden formula for a debugging prompt is a five-part kit: the complete error + the complete stack trace + the relevant code + the minimal reproduction steps + what you've already tried. Missing any one of these, and diagnostic quality drops off a cliff.

Negative example:

"My server action is erroring, take a look."

This kind of prompt only buys you "please check your database connection." Positive example:

A Next.js 15 server action that errors when calling Prisma to create a user.

Complete error:

Error: Unique constraint failed on the (email)
    at PrismaClientKnownRequestError
    at handle (src/app/actions/user.ts:23:16)

Relevant code:

export async function createUser(input: UserInput) {
  return db.user.create({ data: input })
}

Already tried: input.email is not empty, and this email isn't found in the database either.

Expected: a duplicate email should return a friendly error, not throw a 500.

With the same AI, the second prompt's answer will point directly to "the email field in your schema may have stale data / case inconsistency / whitespace; suggest TRIM before querying and add a catch to distinguish P2002." The difference is all in the context.

The "what you've already tried" item is especially important. It drags the AI out of platitudes like "check your database connection" and forces it toward deeper hypotheses. Otherwise it keeps looping over the same ground you've already covered.

3. Bug types worth handing to AI

In practice I've found that the bugs AI handles well share a trait: the truth is hidden in the code and logs, with no need for a real runtime environment. Specifically, five categories:

1. Standalone logic errors — a pure function computed wrong, a condition inverted, off-by-one, unhandled boundary. Paste the function, and it sees at a glance that i <= arr.length should be i < arr.length.

2. API misuse — React Hooks violating the rules, a Promise missing await, a Prisma where passed in the wrong shape, an Array.map that returned undefined. AI has seen these bugs tens of thousands of times and can recognize them with its eyes closed.

3. Configuration/environment issues — .env not loaded, a Docker port conflict, Next.js's output: 'export' clashing with a server-side API, TypeScript's moduleResolution misconfigured. Paste the config file together with the error, and AI usually hits the mark precisely.

4. Third-party library usage — "I used zod's .refine but the async validation doesn't take effect." AI is more familiar with mainstream libraries' APIs than most people.

5. Clear error messages — TypeScript compile errors, ESLint errors, explicit build-failure messages. This is AI's home turf; it basically answers instantly.

4. What AI can't handle: spend your time on manual work

But there's a class of bugs where AI not only can't help, it will lead you astray. These bugs share the trait—the truth isn't in the static text of the code, but in runtime timing, state, and resources.

• Concurrency races: two async requests writing the same key at once. The code looks "correct" to AI, because it assumes sequential execution. It will give you a pile of "plausible-looking" fixes, none of which have reproduced the real scenario.
• Performance bottlenecks: CPU spiking, slow responses. AI will guess "is it an N+1 query," but it can't see the profiler's flame graph and can only offer a generic advice checklist.
• Memory leaks: from reading code, AI has a hard time judging which closure holds a reference or which EventListener wasn't unbound. You need a heap snapshot to locate it.
• Distributed-system-level: cross-service data inconsistency, network partitions, duplicate messages. AI is strong at understanding code within a single service, weak at cross-service timing.
• Bugs needing real-environment reproduction: bugs that only appear in production/Staging—sensitive data, complex environments—that AI can neither see nor run.

Key line: concurrency bugs are AI's blind spot, because its training data doesn't hold the truth either.

For these five categories, don't pin your hopes on AI. Letting it list a set of hypotheses is fine, but localization and verification must be done by you personally.

5. Context engineering: give the trace, not your description

Anyone who has debugged understands one saying: "I assumed" is a bug's best disguise. When you describe a problem, your brain automatically fills in, beautifies, and skips details you deem irrelevant. You tell the AI "this function returned an empty array," but in the real trace the function returned undefined, which you subconsciously "translated."

So the first principle of context engineering is: give the raw trace, not your description.

• ❌ "This function seems to return undefined" — this is your second-hand description
• ✅ Paste the raw output of console.log, paste the actual return value captured by node --inspect

Second principle: give relevant code, not the whole repo. Tools like Claude Code can grep on their own, but scoping the range yourself makes it more focused. A hint like "I suspect these few files" is ten times faster than letting it search the whole repo.

Third principle: isolate variables. When a bug involves 5 functions and 3 API calls, don't dump the entire chain on AI at once. First compress the problem to a minimal reproduction: call only this one function, pass only this one input, observe only this one output. A minimal reproduction is half of debugging itself, and AI's hit rate on minimal reproductions is an order of magnitude higher.

I once debugged a Next.js routing problem—the whole page was 300 lines, and when I gave it to AI it offered a pile of "maybe it's a hydration mismatch." I cut the page down to an empty component + a single line of fetch, and the bug was still there—this time AI immediately pointed out that the issue was the redirect logic in middleware.ts. Before the variables were isolated, AI couldn't see clearly; after isolation, it understood at a glance.

6. Tool usage: Claude Code / IDE / breakpoints in concert

The form of the tool sets the ceiling on AI debugging.

Agents like Claude Code that can read files and run commands are a qualitative change. You no longer have to copy-paste a pile of code; just say "look at createUser in src/app/actions/user.ts, the error is in /tmp/error.log, help me locate it." It reads on its own, greps on its own, runs pnpm tsc --noEmit on its own, looks at the schema on its own. This kind of debugging where "it has hands and eyes" is a step above purely conversational AI.

In-IDE AI (Cursor / Copilot Chat / Windsurf) is suited to "asking while writing." Select a piece of code that's erroring and press Cmd+I to ask "why is TS erroring here?" Its advantage is that context is automatically brought in—the current file, cursor position, open tabs—so you almost never have to feed context manually.

But regardless of the tool, the most efficient pattern is AI + breakpoints/logs in concert, not AI replacing them:

1. First use AI to read the error and the stack, yielding a "most likely root-cause hypothesis"
2. Drop a console.log or breakpoint at that location and run a real reproduction once
3. See whether the trace supports AI's hypothesis
4. If not, return to step 1, feed the new observation to AI, and let it re-hypothesize

In this loop, AI is responsible for "rapidly generating high-quality hypotheses," and you are responsible for "validating hypotheses with real runtime data." That's the correct division of human-machine labor. AI working alone will guess blindly; you working alone will be slow—together, it's a force multiplier.

7. AI debugging discipline: validate its hypotheses, don't treat them as gospel

The last point, and the one most prone to backfiring: an AI diagnosis is a hypothesis, not a conclusion.

AI has a dangerous tendency—it will state an unverified guess in an extremely confident tone. It says "this problem is because useState's setter is asynchronous," sounding reasoned and well-cited; you change things for a long time only to find that wasn't the cause at all. This kind of "confident error" is more dangerous than ignorance, because it drains your time and shakes your judgment.

My discipline is:

• Every one of AI's conclusions must correspond to a real trace or document. When it says "this API behaves like so," go check the official docs to confirm.
• For any fix AI gives, after applying it you must run a reproduction, not "commit it because it looks right."
• If AI guesses wrong twice in a row, immediately switch back to manual mode. Don't count on it getting it right the third time, and don't fall into the trap of "if I describe it in more detail it'll answer correctly"—this bug may simply be outside its capability circle (back to section four).
• Keep your own judgment. If AI's diagnosis conflicts with your engineering intuition, trust your intuition first and verify; don't blindly trust AI.

Key line: in the hands of a senior engineer, AI can make you three times faster; in the hands of a novice who blindly trusts it, AI can drag you into a three-hour quagmire.

Summary

1. Context is the 1, everything else is 0. Without a complete error/stack/code/repro/what-you-tried, AI can only give platitudes.
2. Bugs that suit AI: the information is in the code and logs. Standalone logic, API misuse, configuration, library usage, clear errors.
3. Bugs that don't: the information is at runtime. Concurrency, performance, memory, distributed, real-reproduction-needed—AI can only list hypotheses; localization is on you.
4. Give the trace not the description, give relevant code not the whole repo, build a minimal repro before feeding AI. These are the three pillars of context engineering.
5. The AI + breakpoint/log loop is the efficient pattern: AI proposes hypotheses, you validate with real data; every conclusion must go back to the trace to confirm—don't mistake confidence for correctness.

The endpoint of debugging isn't "AI found the bug for me," but "AI helped me validate my hypothesis faster." The more powerful the tool, the more valuable the engineer's judgment.