proxiblue.com.au · agent operations · runtime evidence

The ProxiBlue Debugger Discipline

How I (Lucas van Staden / ProxiBlue) took var_dump away from my AI agents and wired in real breakpoint debugging instead. Echo-debugging is fast to type and almost always slower to truth, so the print-statement path is not discouraged in my fleet: it is blocked at the moment of the edit.

Why I built this

Give an AI agent a PHP runtime question — wrong value, wrong branch taken, a function returning null that should not — and its first instinct is the same one every developer has typed a thousand times: drop a var_dump in, run it, look at the output. Fast to type, and almost always slower to truth. It pollutes the diff, it leaks into commits, and it trains the worst habit an agent can have: guessing-then-checking instead of measuring-then-knowing.

The kicker is that my agents have something better sitting right there. Every project in my fleet carries an xdebug bridge (the koriym/xdebug-mcp plugin, seeded into every DDEV project), which gives the agent real breakpoints, real variable inspection, real traces — runtime data on demand. So the rule is simple: the debugger is the default, not the fallback. And because a rule that is merely written down gets followed most of the time, the print-statement path is also physically blocked.

The tool table: pick by the question

The core of the discipline is a mapping from question to instrument. The agent does not "debug"; it asks a specific question and runs the tool that answers it:

xstep

"What is $x at line N, and why is it that value?" — breakpoint at the line, inspect for real.

xback / xtrace

"How did execution even reach this point?" — the call path, not a theory about the call path.

xtrace

"What is the flow of this request or script?" — the whole execution, recorded.

xprofile

"Why is this slow?" — where the time actually goes.

xcoverage

"Is this line or branch even reached by the test?" — before theorising about code that never runs.

xcompare

"Same call, two inputs — where do they diverge?" — two runs, diffed.

If the question fits none of those, the fallback is reading the code — not var_dump. And the order of operations is fixed: name the tool that fits and why, run it, then cite the output — file, line, variable, value — as the evidence for the claim. No citation, no claim. That last part connects to my wider investigation protocol (the no-guessing article), where every diagnosis has to arrive with its artefacts attached.

The gate: blocked, not discouraged

The prose rule handles the thinking; a guard hook handles the typing. A PreToolUse hook watches every edit the agent makes to a .php or .phtml file and scans the text being added for the echo-debugging family: var_dump, print_r, var_export, dd(), dump(), ray(), xdebug_break(). Match found, edit refused, deterministically. The block message is not just "no": it prints the whole tool table, so the refusal doubles as the recovery path. The agent gets told what it should have reached for, in the same breath as being stopped.

Three design details do most of the quiet work:

Only added lines are scanned. An edit that removes a stray var_dump from legacy code sails through. The guard blocks the sin, never the cleanup.
Legitimate use has a door. Some of these functions have genuine production uses. The agent's instruction for that case is: say so and ask me. A per-project opt-out file exists for codebases where that is routine. The default is strict; the exceptions are explicit and human-approved.
The instinct itself is the signal. The rule text bans not just the edits but the phrases that precede them — "let me add a var_dump to see", "I'll just log this out". If the agent catches itself about to say one, that is the cue to pick a tool from the table instead. Half of debugging discipline is noticing the moment you were about to guess.

Things I learnt building it

Prose alone produced enthusiastic agreement and continued var_dumping. The written protocol existed first, and agents followed it — usually. Under pressure, mid-investigation, the fast-to-type path won often enough that I stopped counting. The hook ended the argument. This is the same split as everywhere in my setup: prose for judgment, hooks for invariants (the hooks-not-hopes article is the full treatment).

Honest admissions had to be legal. A discipline that punishes "xdebug is not loaded in this container yet" or "this code path only runs in a cron worker I cannot trigger" just teaches the agent to hide its fallbacks. Those admissions are explicitly acceptable — stated to me, before falling back. The ban is on silent guessing, not on honesty about limits.

"Use xdebug" is a hard stop. If I say "what does xdebug say" or "did you actually step through this", the agent must stop reasoning from the code alone and go run the tool. That trigger exists because I caught sessions confidently narrating runtime behaviour from static reading. Fluent is not the same as measured.

What it buys me

Diffs stay clean. No debug archaeology in commits, no die(var_dump(...)) fossils discovered three weeks later on a live site.
Answers come with coordinates. "The value is wrong" becomes "$user is ['id'=>0] at line 147, here is the trace step". I can audit the claim without re-running the investigation.
The hedging disappears. "Probably" and "should be" mostly vanish from runtime diagnoses, because the tool that gives a definite answer is cheaper than the sentence that avoids one.

Want to do this yourself?

Wire a real debugger into your agent's toolset first. The ban only works if the better path is genuinely available — mine is an xdebug MCP bridge, present in every project by default.
Write the question-to-tool table explicitly. "Use the debugger" is advice; "value at a line means xstep, call path means xback" is a procedure.
Block the print path with a PreToolUse hook on edits, scanning only the added text, only in the relevant file types. A few lines of shell.
Make the block message teach: print the tool table in the refusal, so the agent recovers in-session instead of just failing.
Leave doors for honesty: an explicit opt-out for genuine production use, and explicit permission to say "the debugger cannot reach this" before falling back.
Require citations on runtime claims — file, line, variable, value. The debugger produces them for free; guessing cannot.

None of this exists because print debugging never works. It exists because the debugger answers the same question with evidence instead of output, and evidence is the only currency my review process accepts. The banned tool was also the worse tool; the hook just makes that opinion load-bearing.

I use my tooling predominantly on Mage-OS (Adobe Commerce / Magento) e-commerce projects, and my own AI Booking Agent. If you have not swapped to Mage-OS yet, you are falling behind ;)

More in this series: The ProxiBlue Falsifiable Rulebook — testing the rules and guard hooks that govern my AI coding agents. · The ProxiBlue Domain Graph — giving my AI coding agents long-term domain knowledge with a temporal knowledge graph.