L18 · Build & preview · 6 min
Debugging with your agent: reproduce, find, fix, prove
In one sentence
Debugging is the step-by-step method your coding agent uses when something breaks: first reproduce the bug reliably, next locate its root cause in the logs and code, then fix it with one change at a time, and finally add a test so it cannot return.
Think of it like this
When a lamp stops working, you don't rewire the whole house at random. You flip the switch to see it fail, check the bulb and the outlet one by one, replace the burnt bulb, and flip the switch again to prove it lights up.
How it works
A DefinitionbugA mistake in the code that makes the app behave wrongly.Open in the glossary → is simply a mistake in the code that makes your app behave differently from what you expected. DefinitiondebuggingFinding and fixing the root cause of a bug: reproduce, find, fix, prove.Open in the glossary → is how you and your Definitioncoding agentAn AI that works in your project folder: it reads files, writes code and runs commands, with your permission.Open in the glossary → solve it—not by guessing or changing five files at once, but by following four calm steps: reproduce, find, fix, prove.
First, reproduce and find: you tell the agent the exact steps that trigger the problem, and the agent reads the Definitionerror messageWhat a program says when something fails. Its first line usually says what; the rest says where.Open in the glossary → and DefinitionlogYour app's diary: one line per event. When something breaks, the logs say what happened.Open in the glossary → lines to localize the exact file and line where things go wrong. It reduces the problem to its real root cause before touching any code.
Next, fix and prove: the agent makes one change at a time to fix the root cause (never a blind guess), adds an automated DefinitiontestA small program that checks your app does what it should, so a fix can't silently break later.Open in the glossary → that would have caught the bug, and verifies the whole flow from start to finish so the bug cannot silently return later.
What if the first fix doesn't work? The Agentic Makers Guide sets a strict rule: after two failed attempts, the agent must stop, return your project to the last working DefinitioncommitA checkpoint: a snapshot of what changed, with a short note. You can return to any commit.Open in the glossary → (git revert or a clean branch, never deleting history), and explain your options plainly so you never end up in a tangled mess.
What it looks like in your project
When something breaks, your agent activates its debugging-and-error-recovery DefinitionskillAn expert playbook your agent follows for a kind of task, like writing a spec or debugging.Open in the glossary →. It tells you in two plain sentences what caused the bug and how the fix works, adds a test, and asks you to verify that the problem is gone.
Copy for your agent
Something broke: when I [steps you took], I expected [expected result] but got [actual result]. Follow the debugging loop: reproduce it, find the root cause in the logs, explain it in two plain sentences, fix one thing at a time, and add a test.
Quick check · 1 question