Debugging and Self-Repair

Module: 3. WAT framework | Time: ~20 min theory + 25 min practice

The gist

The first run of any workflow (a workflow is a set of steps that get a job done) is like the first test flight of a prototype airplane: the team almost always finds something to adjust. The difference between Claude Code and Zapier is that, in most cases, Claude Code climbs into the cockpit and fixes it on its own. You don't need to figure out which wire came loose.

Key ideas

Errors on the first run are normal, not a failure
Claude Code finds and fixes errors on its own
Delegating the fix: you describe the symptom, the agent (an agent is an AI that carries out tasks on its own) diagnoses and treats it
After the first successful test, the workflow becomes reliable

The theory

Why the first run almost always breaks

🎨 Picture this: The first run of a workflow is like the first test drive of a new car: everything looks assembled, but only on the road do you notice one tire is a little low.

This isn't a bug in the system. It's how all automation works. When you build a workflow, you're working from assumptions: "the API (application programming interface, the way one program talks to another) should accept a request like this," "this spreadsheet will have data in this format," "the endpoint lives at this address." Reality always makes corrections.

In traditional tools (Zapier, Make, n8n) that means: you see a red X in the logs, copy the error, go to Google, read the documentation, come back, try a fix, and go around again. It's especially painful if you don't know how to code.

🎨 Picture this: Debugging (finding and fixing errors) without Claude is like looking for a gas leak blindfolded: you know something's wrong, you can smell it, but you can't tell where. Claude Code takes off the blindfold and points right at it.

With Claude Code it works differently: you just describe what you see, and the agent figures out the cause.

Three real self-repair scenarios

Scenario 1: Unicode encoding error

You ran a workflow that collects news and formats it. In the console you see something like:

Type this into the chat

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 14

You don't know what a UTF-8 codec is or why it can't decode something. You write to Claude Code: "I ran the workflow and got this error." The agent:

Reads the error log
Finds the file where the error happened
Sees that no encoding was specified when working with the text
Adds encoding='utf-8' in the right place
Runs it again, and the error is gone

You didn't write a single line of code.

Scenario 2: The API endpoint changed

A service you use got updated, and the old API URL no longer works. The workflow returns 404 Not Found. Claude Code:

Sees the 404 error
Looks up the service's current documentation (through the Context7 MCP, MCP being a protocol for connecting tools to AI, or through a web search)
Finds the new endpoint
Updates the tool in your project
Tests it, and now it works

This is literally what used to take an hour of digging through documentation.

Scenario 3: Wrong Google Sheet ID

You connected the workflow to Google Sheets, but copied the spreadsheet ID wrong (you took it from the URL, but the wrong part). The agent tries to open the spreadsheet and gets an access error. It tells you: "I can't find a spreadsheet with this ID, please check that the ID is correct." You open the spreadsheet in your browser, copy the correct ID from the URL, send it to the agent, and it updates the config and keeps going.

This is an example where the agent can't fix the problem by itself (it needs information from you, from an outside system), but it tells you clearly what it needs instead of just saying "error."

How to report errors the right way

🎨 Picture this: You call your doctor. Your job is to describe the symptoms: "it hurts here, my temperature is this, yesterday I ate that." Not to diagnose yourself. Diagnosis is the doctor's job. Same with the agent.

When you see an error, your job is to describe what's happening. You don't need to analyze it or explain the cause. Just:

Good:

"I ran the newsletter workflow and see this text in the console: [paste the error]"
"The workflow stopped, here's what it says: [screenshot or error text]"
"Looks like something went wrong at the Google Sheets step, the agent said it can't connect"

Not needed:

Analyzing the code yourself
Trying to understand the technical cause
Searching Google for a fix (unless you're curious)

You're delegating. Delegating means "here's the symptom," not "here's my theory and my treatment plan."

The first successful test is the turning point

🎨 Picture this: The first successful run of a workflow is like the first takeoff of a prototype airplane. The engineers didn't know for sure what would happen; now they know: it flies. Every flight after that will be more reliable, because the plane has already been through real conditions.

The moment a workflow runs from start to finish without errors for the first time is worth remembering. After that:

You know the workflow works in real conditions
You can be confident it's ready to deploy
All the errors you found are already fixed

Professional developers call this "passing a smoke test." You got there not by wrestling with code, but by having a conversation with an agent.

Claude Code vs Zapier/n8n: the key difference

🎨 Picture this: Zapier is a LEGO set: powerful, but you have to know which blocks go where. Claude Code is a contractor you tell "I want a room like this," and they figure out the blocks.

Situation	Zapier/n8n	Claude Code
Error in the logs	You dig in yourself	You describe it to the agent
The API changed	You hunt for new documentation	The agent finds it
The logic needs adjusting	You drag blocks around	You say it in words
An error you don't understand	You paste it into Google	You paste it to the agent

The main point: in their usual mode, Zapier and n8n are tools for people who know how to set them up. Claude Code is a tool for people who know what they want to get. Those builder tools are getting AI helpers too, so this comparison describes the usual way of working, not a hard line.

Practice

Exercise: a deliberate error

Take the workflow from the lesson First Workflow LIVE (newsletter automation). Introduce an error on purpose. For example, change the API endpoint to one that doesn't exist (add an extra character to the URL in the tool). Run the workflow. Get the error. Now tell the agent: "the workflow crashed, here's the error, find it and fix it." Watch the process: the agent reads the log, finds the problem, fixes it, and runs it again.

Goal: make sure you know how to delegate fixing errors instead of solving them yourself.

Extra: try giving the agent only a screenshot of the error with no explanation, and see how well it figures out the situation on its own.

Tools and resources

Claude Code terminal (the terminal is a program where you type commands): the main place where errors show up (the console)
/context: helps you see what state the agent is in while debugging
/compact: if debugging drags on and the context (the text the AI "sees" at the moment) is getting full, compress the history before you continue
The workflow's log file: the agent reads it automatically when analyzing errors
/doctor: checks the installation and settings of Claude Code itself, in case the error isn't in your workflow but in your setup
Claude Code CLI Reference: CLI (command-line interface), the full list of commands
Context7 MCP (when connected): the agent looks up current documentation for errors like "endpoint not found"
Stack Overflow / GitHub Issues: the agent can search for solutions with WebSearch if the error isn't a simple one

Common mistakes

🎨 Picture this: A warning in the console is like the yellow oil light on your dashboard. The car still runs, but you can't ignore it: a few hundred miles later the engine could die. Better to deal with it before it's too late.

Mistake 1: Trying to fix it yourself instead of delegating

You see an error, head to Google, and spend an hour reading Stack Overflow. Instead, copy the error to the agent: "here's what's in the console, figure it out." That saves you 30–60 minutes.

Mistake 2: Not keeping a record of the error

The agent fixed it and everything works, but you don't know what was wrong. Ask the agent: "briefly explain what was broken and how you fixed it." It helps you understand your system.

Mistake 3: Ignoring warnings

The workflow runs, but there are yellow warnings in the console. They can turn into errors later. Tell the agent: "here are the warnings, are they worth fixing?"

First Workflow LIVE: the workflow we debug in this lesson
Context Rot and techniques to fight degradation: if a debugging session drags on and the context gets full
Headless Mode and CI/CD (CI/CD stands for Continuous Integration/Delivery, automatic building and shipping of code): automatic debugging in a pipeline (a chain of steps that run one after another) with no human involved

Key takeaways

The first error in a workflow isn't a failure, it's part of the process. Expect it.

Your role in debugging is to describe the symptom, not to make the diagnosis. The agent will figure out the cause.

After the first successful run, you have proof that the workflow works in real conditions. That's your finished product.

Next lesson

→ Tokens and context management (a token is a unit of text for AI, roughly 4 characters of English text): what uses up resources and how to keep it under control