AI agent debugging workflow
Use an AI agent to debug by proving the root cause before editing files or guessing fixes. Build a focused loop from symptoms to evidence, patch and regression check.
Quick answer
A good debugging agent reproduces the issue, narrows the failing path, proves the root cause and only then applies a small fix.
Workflow
Start from the error, collect logs, inspect recent changes, create a minimal reproduction and run the smallest check that proves the fix.
Failure mode
The failure mode is patching the symptom before proving why the behavior changed.
FAQ
Should an agent edit immediately when debugging?
No. It should first prove the root cause with logs, code path evidence or a failing test.
Debug with agents
Related guides
Claude Code Plan Mode: A Practical Guide
Claude Code Plan Mode lets you review and steer a task plan before any file is touched. Full guide: shortcut (Shift+Tab), activation, when to use it, and how to execute the plan.
Most people use Claude Code like a chat: describe the task, watch it execute. That works for small changes. For anything touching more than two files, there's a better path. If you are looking for the shortcut, press Shift+Tab to toggle Plan Mode. To turn it off, press Shift+Tab again or use /plan only for the prompt that needs planning. The dedicated Plan Mode troubleshooting guide covers the common terminal and version issues. Plan Mode. What Plan Mode does When you activate Plan Mode, Claude reads your codebase and produces a step by step execution plan but makes no changes. You see exactly what it intends to do before a single file is written. This gives you a checkpoint: approve the plan, redirect it, or catch a wrong assumption before it cascades into 15 wrong edits. How to activate Plan Mode the shortcut Two ways: Keyboard shortcut : press Shift+Tab…
Read the guideClaude Code Agents: When to Use Them
Claude Code Agents (subagents) let you spawn isolated work threads from the main session. Full guide: what they are, when to use them, how to write a custom one, and the patterns that actually ship.
Claude Code is great when you're driving one thread of work. When you need to run three threads in parallel, or want a fresh pair of eyes on a decision, or need to scope out a large refactor without polluting your main session that's what Agents are for. This is what Claude Code Agents actually are, when to use them, and how to write your own. What Claude Code Agents actually are An Agent (sometimes called a subagent) is an isolated work thread you spawn from the main Claude Code session via the Agent tool. It has its own context fresh, with no visibility into your conversation. You hand it a self contained prompt; it does the work; it returns a single message at the end. Three things make this different from just asking Claude another question: 1. Isolated context. The agent doesn't see what you've been doing. It can't…
Read the guide5 Claude Code Hooks I Use Daily
Claude Code hooks run shell commands on session start, file writes, and tool calls. Here are the 5 I use daily and how to configure them.
Most people discover Claude Code for the AI. They miss the hooks. Hooks are shell commands that execute automatically when something happens in your Claude Code session: a session starts, a tool runs, Claude stops. You define them in .claude/settings.json . They run silently in the background. Here are the 5 I use every day. What hooks look like The available events: SessionStart , UserPromptSubmit , PreToolUse , PostToolUse , Stop . Hook 1 Auto inject date on every prompt Event : UserPromptSubmit Claude doesn't have real time awareness. Every prompt gets the current date injected automatically. Useful for anything time sensitive: changelogs, deadlines, scheduling logic. Hook 2 Push notification when Claude stops Event : Stop Long tasks (refactors, test runs, analysis) can take 2–5 minutes. Without a notification I'd either stare at the screen or miss the result. This fires whenever Claude finishes a task, whether it succeeded or…
Read the guide