Claude Code end-to-end: from bug report to shipped fix

Most explanations of agentic coding stop at the demo: "watch it build a todo app." Real engineering rarely starts from a clean prompt. It starts from a half-described bug, a flaky symptom, a customer who's annoyed, and a codebase nobody fully remembers. So instead of a toy, this post walks a single realistic task end to end — the kind you'd actually hand a new developer — and shows where Claude Code carries the load, where a human stays in the driver's seat, and what "shipped" really requires.

The scenario: a billing report intermittently shows the wrong monthly total for a small number of accounts. Support has three confused tickets. Nobody has reproduced it. There's no obvious error in the logs. This is a good agentic task precisely because it's open-ended — it needs investigation, not just typing.

Step one: turn a vague report into a real brief

The temptation is to paste the ticket into Claude Code and say "fix this." That usually wastes a few turns while the agent guesses at context. The higher-leverage move is to spend five minutes writing a brief a sharp junior could act on: the symptom ("monthly billing total is occasionally wrong for some accounts"), the known facts (three accounts, all on annual plans with mid-cycle upgrades), the constraints (don't change the public report API, don't touch unrelated modules), and the definition of done (a failing test that reproduces it, a fix, and the test passing).

That brief is the actual skill. It tells the agent what success looks like and fences off the blast radius. With it in hand, the first instruction to Claude Code isn't "fix the bug" — it's "investigate and propose a hypothesis," because you don't yet know the cause and neither does it.

Step two: let the agent investigate, with you steering

Claude Code reads the billing module, traces how monthly totals are computed, and surfaces something a human might have taken an hour to find: proration for mid-cycle plan upgrades is computed in one code path, but the monthly-report aggregation reads from a cached summary that isn't always recomputed after an upgrade. That's a plausible hypothesis. Crucially, it's still a hypothesis — the agent is good at quickly building a map of the territory, but you decide whether the map is right.

Here you make a judgment call the agent can't: is this the real cause or just a cause? You ask it to prove the hypothesis the only honest way — write a test that reproduces the symptom. A test that goes from red to green is worth more than any amount of confident explanation, and insisting on it is the single habit that keeps agentic debugging from turning into plausible fiction.

flowchart TD
  A["Vague bug report"] --> B["Engineer writes precise brief"]
  B --> C["Claude Code investigates codebase"]
  C --> D["Agent proposes a hypothesis"]
  D --> E{"Reproducing test goes red?"}
  E -->|No| F["Refine hypothesis with agent"] --> C
  E -->|Yes| G["Agent implements fix"]
  G --> H{"Test green & review clean?"}
  H -->|No| I["Targeted feedback"] --> G
  H -->|Yes| J["Open PR & ship behind checks"]

Step three: the fix, the test, and the things the agent forgets

With the failing test in place, the implementation is the easy part — Claude Code makes the cache recompute after a mid-cycle upgrade, or, better, has the report read from the authoritative computation so the cache can't drift. It runs the test; it goes green. This is the moment that feels like victory and isn't quite, because a green test proves the reported case, not the absence of new problems.

So you push on the things agents reliably under-think unless prompted. Does the fix affect performance for accounts with many upgrades? Are there other readers of that cached summary that now behave differently? Does the change need a data backfill for accounts already billed wrong? You ask Claude Code to enumerate every caller of the changed code and reason about each. It finds two more readers; one is fine, one needs a small adjustment. This is the collaboration working as intended — the agent does the exhaustive mechanical search across the codebase, you supply the "wait, what about the already-billed accounts?" that comes from understanding the business, not the code.

Step four: review, and the discipline of reading what you didn't write

The diff arrives: a fix, a new test, an adjustment to one downstream reader, and a short backfill script flagged as needing manual approval before it runs against real data. Now you review it the way you'd review a teammate's PR — with genuine skepticism, not relief. You read the test to confirm it actually reproduces the original symptom and would fail without the fix. You confirm the backfill is idempotent and scoped to affected accounts only. You check that nothing unrelated was touched.

This review is non-negotiable and it's where the human's accountability lives. The agent proposed the change; you are shipping it. If it's wrong, it's your name on the incident, which is exactly the right incentive. A clean review here takes minutes because the brief kept the change small and focused — another payoff from the work done at step one.

A definition worth keeping: an agentic coding workflow is one where a developer hands an AI agent a goal and constraints, and the agent autonomously investigates, edits, runs tests, and iterates toward a verifiable result that a human reviews before it ships.

Step five: ship, observe, and capture the lesson

The PR merges behind your normal CI. You run the backfill against staging first, confirm the corrected totals, then run it against production with a human watching. You add a monitor so this class of drift is caught automatically if it ever recurs. Total elapsed time is a fraction of what the manual version would have taken, and most of the savings came from the investigation phase — the part where an agent that can read an entire codebase quickly is genuinely transformative.

The final, easy-to-skip step is capturing the lesson so the team gets compounding value. You add a note to the billing module's Skill: "the report cache can drift after mid-cycle upgrades — prefer authoritative computation." Next time, the agent reads that and doesn't have to rediscover it. That's the difference between using an agent and building an organization that gets smarter every time it uses one.

Frequently asked questions

Why insist on a reproducing test before the fix?

Because agents are persuasive even when wrong, and a red-to-green test is the one piece of evidence that can't be talked around. It proves the hypothesis is real and guarantees the fix addresses the actual symptom rather than a confident guess. It also leaves a permanent regression guard behind.

What part of this still genuinely needs a human?

Judging whether a plausible hypothesis is the right one, surfacing business consequences the code doesn't reveal (like already-billed accounts), reviewing the diff with real skepticism, and owning the decision to ship. The agent supplies speed and exhaustive search; the human supplies judgment and accountability.

How long does a task like this take with Claude Code?

It varies, but the investigation phase typically collapses dramatically because the agent can read and trace the whole codebase fast. The fix and review then take about as long as the human's attention requires. The biggest time saver is finding the cause; the biggest time sink avoided is chasing the wrong one.

What's the most common mistake in walkthroughs like this?

Skipping the brief and skimping on review — treating the agent's first plausible answer as the answer. Both failures stem from the same root: trusting fluency over verification. Front-load a precise brief and back-load a real review, and the middle takes care of itself.

Bringing agentic AI to your phone lines

CallSphere runs the same investigate-act-verify loop on voice and chat: agents that diagnose a caller's need, use tools mid-conversation to resolve it, and escalate to a human when judgment is required. See a real end-to-end agent at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.