Give a coding agent the steps that expose the bug and the result that would count as a fix. “The form is broken” invites a guess. “Submit this safe sample from this starting page; an error appears and no confirmation is shown” gives the agent something it can observe before editing code.
The most useful bug report separates observation from diagnosis. You may suspect validation or a network problem, but keep that suspicion outside the reproduction steps. Otherwise the agent can produce a convincing fix for a cause nobody established.
- 01Preserve the starting state.The same clicks can behave differently with another account, record or browser state.
- 02Show expected and observed results.The gap between them defines the task better than a proposed implementation.
- 03Verify the original complaint.A successful build is useful evidence, but it does not alone prove the reported defect is gone.
01 — Send a compact reproduction packetSend a compact reproduction packet
A reproduction is a repeatable way to observe the failure. Use the packet below, with safe sample data that preserves the relevant shape. These are recommended reporting fields, not a requirement to collect sensitive customer information.
| Field | Useful content | What to avoid |
|---|---|---|
| Environment | Page, app revision and relevant browser or device | A vague claim that it fails everywhere |
| Starting state | Required sign-in state and safe sample record | Live credentials or unnecessary personal data |
| Steps | The shortest ordered actions that still fail | A diagnosis disguised as an instruction to change code |
| Expected result | Observable behavior grounded in a requirement | A preferred implementation without a user outcome |
| Observed result | Exact error, screenshot or relevant log reference | A screenshot with no action or time context |
| Frequency | Observed attempts and conditions | An invented failure percentage |
| Verification rule | Repeat the original steps and check adjacent behavior | Only checking whether a file was edited |
02 — Describe one failure without guessing its causeDescribe one failure without guessing its cause
Consider an illustrative contact form. With a valid sample address and a message, selecting Submit displays a spinner that never clears. A useful report states the page, starting state, inputs, action and visible result. It also says whether a confirmation message was expected under the current requirement.
The spinner does not prove the request failed. A diagnostic check might reveal that the submission was saved while the response handler failed. Repeating live submissions could create duplicates, so reproduce with controlled test data and inspect the resulting state.
Attach the smallest relevant evidence. A timestamp helps correlate a log entry; a screenshot shows what was visible. Neither substitutes for the steps. For unknown completion, the tool-error reference provides a useful decision boundary.
03 — Use research as a design anchorUse research as a design anchor
Anthropic’s long-running harness report describes explicit feature lists and browser checks used to address premature completion. The lesson we apply here is to keep the requested behavior observable throughout a coding task.
Its agent-evaluation guide emphasizes well-specified coding tasks, stable test environments and tests of the generated code. A customer report becomes more useful when it provides the inputs for such a task.
Neither source proves that this packet will solve every bug or reduce your debugging time by a particular amount. Its value is procedural: the agent and reviewer can agree on what failed and what must change.
04 — Preserve uncertainty when the bug disappearsPreserve uncertainty when the bug disappears
If the agent cannot reproduce the issue, keep the report open as unreproduced. Record what was tried and under which conditions. Ask for the missing detail that could distinguish the failing case: account state, sample shape, timing or a particular revision.
Do not silently broaden the claim from one report to a universal defect. Conversely, one successful attempt does not refute an intermittent complaint. A useful next step is focused instrumentation or another controlled attempt with the relevant conditions preserved.
Protect the report from speculative edits. A refactor that makes the code look cleaner may be worthwhile for another reason, but it is not evidence that the original defect was fixed. The reviewer evidence guide explains why a second approving opinion does not settle that question.
05 — Close with evidence tied to the original stepsClose with evidence tied to the original steps
The completion record should identify the change, the original reproduction result after the change and relevant adjacent checks. A regression check asks whether previously working behavior still works. Keep it focused on what the change could affect.
If the agent needed to change the acceptance rule because the original expectation was wrong, document that decision and its owner. Do not alter a test merely to make a failing result disappear.
Separate local verification from publication. A tested change still needs the project’s release process. When work moves to another agent or reviewer, use the handoff ownership guide to preserve the remaining responsibility.
06 — DecisionWhat to do next
Make the reported failure the acceptance test.
Send the agent a reproducible observation, keep the diagnosis provisional and close the report only against the original behavior or an explicitly revised requirement.
For implementation support, explore our AI transformation services.