Bug Work With an Agent: Find the Real Cause, Not the Symptom

Part 3 of a 5-part series on how software engineers should actually work with coding agents. Each part stands alone; the full series index is at the end of this article.

Feature work with an agent is mostly a planning problem. Bug work is an evidence problem. And coding agents turn out to be genuinely great at finding root causes, if (and only if) you give them access to evidence and take away their ability to guess.

Here's how I run bug investigations, and the guardrails that make it safe.

The trap: agents love to fix symptoms

Point an agent at a bug report and its instinct is to jump straight to a patch. It finds a spot in the code where the symptom can be made to go away, patches it, and declares victory. The symptom disappears. The cause remains. The bug comes back wearing a different costume.

That's not stupidity. It's incentive. The agent wants the visible problem gone, and hiding a symptom does that. So the first rule of bug work:

Separate diagnosis from treatment. The first session's job is not a fix. It's a written diagnosis: what's happening, why, what evidence proves it, and what else it affects. Only after I've read that and believe it do we talk about a fix, often in a fresh session, with the diagnosis as the starting input.

Same logic as spec-before-code in part 2: force the reasoning onto a page where it can be checked before it turns into action.

Give the agent read-only database access

This one practice transformed bug work for me: the investigating agent gets a read-only database connection.

Most production bugs aren't visible in code. They live in the data: the row that breaks an assumption every function quietly makes, the empty value where code expects one, the duplicate that "can't happen." An agent that can only read code is a doctor diagnosing a patient it's not allowed to examine. It will produce a beautifully reasoned theory that's wrong, because the data disagrees.

With query access, the investigation changes completely. The agent forms a theory, tests it against real data, drops it when the data says no, and tries again. Watching a good agent do this is watching the scientific method at high speed.

Two real (anonymized) examples of things an agent found this way that reading code never would have:

• A metrics table contained the special floating-point value NaN ("not a number"). In the database's comparison rules, NaN > 0 counts as true. So "impossible" rows sailed through every safety check in the code. No amount of reading those checks reveals that. One query does.
• A "duplicate records" bug traced not to the de-duplication code (which was correct) but to a typo in a configuration value stored in a table. The dedup logic keyed off that stored text, the typo made the check silently pass everything through, and one data source had been double-counting for months.

The guardrails, because this is dangerous done lazily

Read-only at the credential level, not the polite-request level. "Please don't write to the database" is a suggestion. A database login that has no write permissions is a guarantee. Create a dedicated read-only login, and that's the only one an investigating agent ever sees. If your agent tool supports permission rules, block write-shaped commands there too. Belt and suspenders.

Hard deny rules on secrets. My agent's permissions explicitly block reading .env files and anything password-shaped. This costs nothing, since the agent doesn't need secrets to analyze data, and it removes a whole category of accident: credentials pasted into transcripts, logs, or summaries. The wider rule: secrets never appear in commands, scripts, or code the agent writes. They load from the environment, always. Make that a standing rule (part 5), not a per-task reminder.

Production data is still production data. Read-only access to real customer data is a privacy decision, not just a safety one. Scope it like you would for a human running ad-hoc queries: least access that does the job.

Check the diagnosis yourself. Before acting on the agent's conclusion, I re-run the key queries with my own hands. This is why the database console lives in my IDE (part 1). Thirty seconds, and it has caught the agent over-reading a result more than once.

Demand the mechanism, not a correlation

The quality bar I hold every diagnosis to: it must explain the full chain ("this input, through this path, creates this wrong state, which shows up as this symptom") and it must account for the evidence that doesn't obviously fit. "The errors started around the Tuesday deploy" is not a diagnosis. Agents will happily stop at "it correlates" if you accept that. They'll also happily push all the way to the mechanism if you insist. Insist.

One more anonymized story about why this matters: an on-and-off "zero rows written" bug survived three separate fixes, each targeting a plausible-looking correlation. The real chain, found only when we demanded the full trace, was tenant context leaking between threads in a background worker. The "which customer is this?" setting was right for a connection's first transaction and silently wrong for later ones, and an over-helpful error handler was hiding the real failure. Every earlier fix had been real code aimed at an imaginary cause.

Then fix it properly

Once the diagnosis is accepted, the fix goes back through the normal pipeline from part 2. The diagnosis usually is the spec. Bugs don't get to skip review because they feel urgent. Urgent, unreviewed fixes to half-understood problems are how one incident becomes two.

The parts to keep, whatever your stack:

1. Diagnosis before treatment: the first deliverable is a written cause, not a patch
2. Evidence access: read-only data access for the investigating agent
3. Guarantees over promises: read-only logins and secret-blocking rules enforced by the system, not the prompt
4. Mechanism over correlation, and check the key evidence yourself

Next: the riskiest work you'll ever hand an agent. Scripts and changes that touch customer data.

Series Index:

• Part 1: One IDE, Many Worktrees
• Part 2: The Delivery Pipeline
• Part 3: Bug Work With an Agent
• Part 4: Scripts and Customer Work
• Part 5: Teaching the Agent Your Rules