One Claude Code Tip a Day: Keep a Repro Transcript
Before asking Claude Code to fix a bug, capture the exact repro path, command output, expected behavior, and one failed attempt. A repro transcript turns a vague debugging session into a focused loop.
This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.
The real failure: debugging from a rumor
A vague bug report is where otherwise good Claude Code sessions go sideways. The issue says, “checkout sometimes shows the wrong total,” and the tempting prompt is: “fix the checkout bug.” Claude will inspect files, form a theory, and maybe produce a plausible patch. But if the session never pins down the exact path that fails, the fix can easily land in the wrong component, the wrong viewport, or the wrong state transition.
Today’s habit is to keep a repro transcript before you ask Claude to edit. Not a giant incident report. Just enough evidence that another developer, or Claude Code, can replay the failure and know when the bug is gone.
Write the transcript before the fix prompt
A useful repro transcript has five parts: the task context, exact steps, observed behavior, expected behavior, and the smallest command or screen that proves it. For a frontend bug, I like to paste something like this into Claude Code:
Bug: applying coupon SUMMER26 on /checkout updates the sidebar total but not the sticky mobile footer. Steps: pnpm dev, open /checkout?plan=pro, switch to mobile width, apply SUMMER26. Observed: sidebar shows $12/month, footer still shows $20/month. Expected: both show $12/month. Evidence: Playwright test checkout-coupon-mobile.spec.ts fails on getByTestId("mobile-total"). Do not edit yet. First read the checkout total components and tell me which state path feeds each total.
This is not busywork. It gives Claude a target and a boundary. The first response should be a map of the failure, not a patch.
Use Claude Code to challenge the repro
The transcript may still be wrong. Ask Claude to critique it before coding:
Read the relevant files and challenge this repro. What assumption could be false? Is there another component that renders the mobile total? Which command should we run before editing to prove the failure is real?
A strong answer names files and a verification command: “desktop total comes from CheckoutSummary.tsx; mobile footer uses StickyCheckoutBar.tsx; both subscribe to useCheckoutTotals, but the footer memoizes displayTotal. Run pnpm test checkout-coupon-mobile.spec.ts before changing code.” A weak answer jumps straight to “I will update the total calculation.” Stop that. The transcript exists to slow the first edit down until the failure is located.
A realistic second pass
Now run the smallest failing check. In Claude Code, I would continue:
Run only the failing Playwright test and show the assertion plus the rendered value. Do not edit during this run.
Suppose the test fails, but the screenshot shows the footer is hidden behind the cookie banner. That is not yet a checkout-total bug; it is a test-environment problem. The second pass should preserve the evidence:
The repro may be contaminated by the cookie banner. Update the test setup only if the app already has a standard helper for dismissing it. Then rerun the same test. If the footer still shows the old total, explain the product bug and propose the smallest patch.
This is the TonBisa-style loop applied to everyday debugging: prompt, inspect, identify the gap, correct the setup, verify again. The transcript is the thread that keeps the loop from turning into random edits.
What to inspect after Claude edits
After Claude makes the patch, do not accept the explanation. Ask for the evidence bundle:
Show git diff --stat, the exact diff for changed files, the failing test now passing, and one sentence explaining why the patch affects the mobile footer path without changing desktop behavior.
This catches two common mistakes. First, Claude may fix the test by changing the selector or expectation rather than the product path. Second, it may touch a shared pricing helper and accidentally alter desktop rounding. The repro transcript gives you a stable comparison: the same steps that failed before must now pass, and unrelated behavior should remain untouched.
Failure modes
The biggest failure mode is making the transcript too large. A pasted wall of logs can be worse than no logs because Claude has to guess which line matters. Trim to the command, the failing assertion, and the surprising value. Keep the full log available, but lead with the signal.
The second failure mode is using the transcript as a verdict. A repro is a hypothesis, not a court ruling. If Claude finds that the bug only happens with stale local storage or a mocked API fixture, let the evidence update the story. The goal is not to prove the original report was perfect; the goal is to make the next edit accountable to a repeatable signal.
The third failure mode is skipping the “do not edit yet” step. Without it, Claude may patch before it understands why the repro fails. Make the read-only mapping pass mandatory for confusing bugs.
Rule of thumb
Before you ask Claude Code to fix a bug, give it a repro transcript that a teammate could run: steps, observed result, expected result, command or screen, and one known failed attempt. Then make Claude challenge the transcript, run the narrow check, edit once, and replay the same evidence. Bugs become much easier to fix when the session starts from a reproducible story instead of a rumor.