Give a Coding Agent a Bug It Can Fix

A coding agent can search a repository quickly, but a vague bug report still leaves it guessing. “Checkout totals are broken” gives it a symptom without a reliable starting point or a definition of success. A useful report turns that complaint into an observable failure, then gives the agent enough context to investigate and verify a repair. Here is a walkthrough using a fictional checkout application.

Start by describing one observable checkout failure

Write the report around a single behavior. For this example: “Changing an item’s quantity updates the subtotal, but the order total stays at its previous value.” That sentence identifies the trigger, the working behavior, and the failing behavior.

Keep your diagnosis separate. You might suspect a missing dependency in a calculation hook, but label that as a hypothesis. Otherwise, the agent may spend its effort proving your theory instead of following the evidence.

Make the reproduction work from a known state

Give the agent a starting point it can recreate. Include the commit identifier, relevant runtime versions, startup command, and any required configuration names. Describe test data without copying credentials or customer information.

For the checkout example, provide these steps:

• Check out the reported commit and start the application using the repository’s documented development command.
• Open a cart containing one test item priced at $20, with a fixed $5 shipping charge and no tax or discounts.
• Increase the item quantity from one to two.
• Observe the subtotal and order total without refreshing the page.

State whether the failure happens every time. If it is intermittent, record the conditions you observed, such as rapid clicks or a delayed response, rather than inventing a timing requirement.

Show expected and actual values side by side

Concrete values make the failure easy to recognize. Write: Expected: subtotal $40, shipping $5, order total $45. Actual: subtotal $40, shipping $5, order total $25. Add that refreshing the page displays $45, if you have verified it.

Attach or paste the smallest relevant evidence available to the agent: a failing test, a sanitized response, or a short log excerpt. Explain what each item demonstrates. A large console dump without context creates another investigation before the real investigation can begin.

Give the agent a map of relevant code

Point to likely entry points using real paths from your repository. In this fictional application, those might be src/cart/CartSummary.tsx and src/cart/useCart.ts. Explain that the first renders the amounts and the second manages cart state.

Include commands the agent can actually run, copied from the project documentation or package scripts. Say which checks you already ran and what happened. If you cannot reproduce the failure locally, say so; a staging-only observation should not become a claimed local reproduction.

Define the repair boundary and acceptance checks

Tell the agent what successful behavior must preserve. For this report, ask it to update the displayed total immediately after quantity changes while retaining the existing shipping calculation. Exclude unrelated checkout redesigns and dependency upgrades unless investigation establishes that they are necessary.

Ask for a regression test that fails with the reported behavior and passes after the fix. Verify both increasing and decreasing quantity, because a repair that handles only one direction leaves the underlying behavior incomplete. Request a final explanation of the cause, changed files, checks run, and any remaining uncertainty.

Keep the same report across agent sessions

Save the report with the issue so another session can reproduce the same failure. When comparing agents, keep the commit, fixtures, instructions, and permissions consistent. Record the model and tool used alongside the result.

BestRelay, this article’s publisher, is a quality-first API relay that forwards each request to the official model named in it, without substitution. It supports Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more, and works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK through the API base https://api.bestapirelay.com. Billing is pay-as-you-go using provider-reported token counts, with cache reads and writes priced separately; members also earn a referral commission when people they invite top up.

Create a BestRelay account to try this workflow with your next bug report.