Debugging with an Agent

I Debugging Is Different Now

Traditional debugging has a prerequisite that nobody talks about: you wrote the code. You remember why that function exists, what the variable name means, what edge case prompted that weird conditional on line 47. When something breaks, you retrace your own steps. It's archaeology of your own thinking.

Vibe-coded projects don't give you that luxury. You described what you wanted, the agent built it, and now something is broken in code you've never read. You're debugging someone else's work — except that someone else is available 24/7 and has perfect recall of every line it wrote.

This is the counterintuitive unlock: the same agent that wrote the code is often the best debugger of that code. It doesn't forget what it built. It doesn't get tired of reading stack traces. And it's seen thousands of variations of whatever error you're staring at. Andrej Karpathy hasn't typed code since late 2025 — and when his agent-delegated builds break, he's said the failure is always a skill issue on the human side: unclear instructions, missing memory, poor parallelization. Never a capability ceiling on the agent.

That's both liberating and demanding. Liberating because you don't need to become a software engineer to fix things. Demanding because you doneed to become good at describing problems, reading signals, and knowing when you're out of your depth.

II The Debugging Loop

If you've read the Agents series, the debugging loop will feel familiar. It's the think-act-observe cycle applied to your own broken code:

1. You describe the error. What were you doing? What happened? What did you expect instead? Paste the full error message.
2. The agent reads code + error. It examines the relevant files, the stack trace, the surrounding context.
3. The agent proposes a hypothesis."The API endpoint changed its response format" or "The environment variable isn't set in production."
4. You verify. Does the hypothesis match what you see? Can you reproduce it? Does the proposed fix make sense?
5. The agent fixes.It writes the patch, you test it. If it works, you're done. If not, loop back to step 1 with new information.

The most important step is the first one. The quality of the fix is directly proportional to the quality of your error report."It doesn't work" gives the agent nothing. "When I click Submit on the checkout page, I get a white screen and the console shows 'TypeError: Cannot read properties of undefined (reading map)' at line 84 of CartSummary.jsx" gives it everything.

The loop typically converges in one to three cycles. If you're on cycle four and still stuck, it's a signal — either the problem is outside the agent's view (an environment issue, a missing API key, a deployment configuration) or the problem is complex enough to need a human engineer. We'll cover how to tell the difference in Section V.

III Reading Error Messages

Error messages are written by engineers for engineers. If you're a builder without a CS background, they look like encrypted transmissions from a hostile civilization. But they follow a pattern, and the pattern is learnable.

Every error message has three parts, and you need exactly zero programming knowledge to identify them:

The error type— the first capitalized phrase, usually ending in "Error." TypeError, ReferenceError, ModuleNotFoundError, 404 Not Found. This is the category of what went wrong. You don't need to understand it — but the agent does, and it narrows the search space immediately.

The message— the human-readable sentence right after the type. "Cannot read properties of undefined" or "No module named 'flask'." This is the what. It tells you (and the agent) what specific thing failed.

The file and line number — the path that tells you where the error happened. src/components/Cart.jsx:84 means line 84 of the Cart component. The top of the stack trace is where the error surfaced, but it's not always where the bug lives. The agent reads the full trace to find the root cause, which might be several files deeper.

You don't need to memorize error types. You need to know that they exist and that the agent needs them. Think of yourself as a paramedic relaying vitals to the ER doctor — you don't need to diagnose the condition, but you do need to read the numbers off the monitor accurately.

IV Common Failure Patterns

Not all bugs are created equal. Some are trivial for the agent, some require context you have to provide, and some are signals that you're past the vibe coding frontier. Here are the patterns you'll encounter most, and what to tell the agent for each.

API changes breaking integrations.You shipped a working Stripe checkout last month. This month, it throws 400 errors. The API version changed, an endpoint was deprecated, or a required field was added. What to tell the agent: "The Stripe checkout that was working last month now returns this error [paste error]. I haven't changed the code. Check if the Stripe API has breaking changes."

Dependency version conflicts. You ran npm installand now nothing works. A library updated and broke compatibility with another library. What to tell the agent: "After running npm install, the app crashes with [paste error]. Here's my package.json. What changed and how do I pin the versions?"

Environment mismatches.The dreaded "works locally, fails deployed." Your app runs perfectly on your laptop but crashes on Vercel, Render, or Replit's hosting. The difference is usually environment variables, Node versions, or build settings. What to tell the agent: "This works locally but fails when deployed to [platform]. Here's the deploy log [paste]. My local Node version is [version]."

Silent data errors.The most insidious category. Nothing crashes. No error message. But the numbers are wrong, the list is incomplete, or the data is stale. A query returns 10 results when there should be 50. A calculation is off by a penny on every transaction. What to tell the agent: "No error, but [specific thing] shows [wrong value] when it should show [correct value]. Here's the data source and the function that processes it."

CSS layout bugs.Surprisingly common and surprisingly frustrating. The sidebar overlaps the content on mobile. The button is invisible against its background. The spacing looks wrong but only on Safari. What to tell the agent: "On [device/browser], [element] looks like [describe or screenshot]. It should look like [describe]. Here's the CSS file." The agent is quite good at CSS — layout bugs are usually its fastest fixes.

V When the Agent Can't Help

The agent is a brilliant debugger within its field of view. But some categories of problems are outside that field, and no amount of prompt engineering will change that. Recognizing these early saves you from the most expensive debugging mistake: going in circles with an agent that can't see the real problem.

Race conditions.Two things happen at almost the same time and interfere with each other. A user clicks "submit" twice before the first request finishes. Two API calls try to update the same database row simultaneously. These bugs are intermittent — they happen sometimes, under specific timing conditions, and they're nearly impossible to reproduce on demand. The agent can suggest fixes in theory, but testing those fixes requires engineering infrastructure: load testing, concurrent request simulation, transaction isolation. If your bug only happens "sometimes" and involves concurrent users, bring in a human.

Performance problems. The page loads in 2 seconds instead of 200 milliseconds. The API takes 10 seconds to respond. The app freezes when the dataset grows past 1,000 rows. The agent can suggest general optimizations, but real performance work requires profiling — measuring exactly where time is spent, identifying bottlenecks in database queries, network calls, or rendering. This is specialist work.

Security vulnerabilities. The agent that wrote SQL-injection-vulnerable code (remember the checkout from Part 3?) is unlikely to catch its own security oversights through debugging alone. Security requires adversarial thinking — what can go wrong if someone triesto break it — which is fundamentally different from "does it work correctly for honest users." If your app handles authentication, personal data, or payments, security review needs human eyes.

Architectural problems.Your app was built as a single file and now it's 3,000 lines long. Adding a feature requires changing code in six places. Data flows through three intermediate functions before reaching the component that displays it. These aren't bugs — the code works. But the architecture is fighting you, and the solution is restructuring, not patching. Boris Cherny's observation applies here with full force: the constraint has moved from coding to architecture and intent. The agent can restructure code you tell it to restructure, but diagnosing whichrestructuring will solve the problem requires the kind of systems thinking that remains firmly human. If every fix creates a new bug somewhere else, that's the signal.

VI The Maintenance Mindset

Part 3 introduced the one-month test: can you come back to your project in a month and still work on it? Debugging is where that test gets real. The first time something breaks after you've stepped away, you discover whether you built a sustainable project or a ticking clock.

Remember the Replit production database deletion incident — an AI agent trying to fix a bug deleted a user's entire production database instead. The agent had the access, the intent was reasonable, and the outcome was catastrophic. That's an extreme case, but the pattern is everywhere: debugging without understanding creates risk. If you can't explain what the code does, you can't predict what a fix might break.

Tests are the best debugging documentation.When your app breaks six months from now, the first question is "what changed?" If you have tests, the answer is immediate — the failing test tells you exactly which behavior stopped working. Without tests, you're guessing. Ask the agent to write tests for your critical paths: the checkout flow, the login process, the data transformation that feeds your dashboard. Tests aren't about catching bugs when you write them. They're about catching bugs when something else changes.

Git blame is archaeology.When something breaks and you don't know why, git logshows you every change in reverse chronological order. "The dashboard broke on Tuesday" becomes "on Tuesday, this commit changed the API response parsing" — which is a debuggable statement. If you don't use version control, every debugging session starts from zero. If you do, every session starts with a timeline of what changed and when.

The Linux kernel AI code policy is instructive here.The kernel project allows AI-generated code, but requires a human submitter who takes full legal responsibility. The code isn't reviewed any differently — but a real person's name is on the line. That principle applies to your projects too. You built it with an agent. That's fine. But the bugs are yours, the maintenance is yours, and the consequences are yours. The agent is a tool, not an owner.

Stanford's 2026 AI Index documented that SWE-bench performance — the standard benchmark for AI coding agents — jumped from around 60% to roughly 80% in a single year. The agents are getting remarkably good at writing and debugging code. But the gap between "agent can fix this" and "I understand what was fixed and why" is the gap between a project that survives and a project that accumulates invisible risk with every patch.