# How to Report a Bug to an AI Coding Agent > Found a bug in AI-built software? Learn what to write, show and ask for so the agent fixes the right thing the first time, with no code skills needed. Canonical: https://bridge-terminal.com/atlas/blog/how-to-report-a-bug-to-ai-coding-agent/ Last updated: 2026-11-02 Published 2 November 2026 · Plain English · How-to · 7 min read ## The short version - A good bug report says what you did, what you expected, what happened instead, and where and when, and includes a screenshot or recording if you have one. - The agent cannot see your screen or your account, so exact steps to repeat the problem matter more than a general description. - Say what 'fixed' looks like and ask for evidence, such as the check it ran and its output, rather than accepting 'all tests pass' on its own. - If two corrections have failed, stop correcting in the same conversation. Start a new one with a single clearer request that includes what you learned. - Report one bug at a time, or give each item in a list its own steps, so each fix stays small and easy to check. You found something broken in your product, and you need to tell an AI coding agent. The short answer: describe what you did, what you expected, what happened instead and where, then show it with a screenshot or recording, and say what "fixed" looks like. The more exactly you can repeat the problem, the more likely the first fix is the right one. You do not need to know why it is broken. That is the agent's job. Your job is to hand over what only you can see. ## Why does the way I report a bug matter? An AI coding agent reads your code well. It cannot see your screen, your browser, your test account or the meeting where a decision was made. Anthropic's best-practices guide for Claude Code makes the point: a specific prompt helps "because it gives Claude information it doesn't already have." The guide says that if you name the file, describe the symptom and say what "fixed" looks like up front, "you usually save yourself a round of corrections later." OpenAI's guidance for its Codex coding agent says much the same. For fixing a bug, it says the reproduction steps and constraints you supply "matter more than a high-level description." A reproduction is simply the list of steps that makes the problem happen again. Think of a mechanic. "The car is making a noise" costs you an hour of guessing. "A rattle from the front left when I brake below 20 mph, cold mornings only" gets the car fixed. An agent works the same way, except it may not stop to ask you what you meant. With a vague report it is likely to pick a probable cause and fix that. ## What should a good bug report include? Five things, in plain words. None needs technical language. ### 1. What you did, step by step List the steps in order, as if you were writing them for a new colleague. Include which page, which type of account, and what you typed or clicked. Weak: "Checkout is broken." Better: "Logged in as a customer with a saved card. Added two items. Clicked Pay. The page spun for a few seconds and went back to the cart." ### 2. What you expected One sentence. "I expected to see an order confirmation page and get an email." This tells the agent what the product is supposed to do, which it cannot always work out from the code. ### 3. What happened instead Give the exact words of any error message. Copy them rather than paraphrase. "Something went wrong" and "Payment failed: code 402" point to very different fixes. ### 4. Where and when it happens Does it happen every time or only sometimes? Only on a phone? Only for new accounts? Only since last Tuesday's release? These clues narrow the search. If the problem began after a particular change, say so. ### 5. Proof you can show If you have it, hand it over instead of describing it. Anthropic's guide says to paste a screenshot of the design or the error straight into the prompt. A short screen recording is useful for anything that moves, flickers or takes several steps, though check that the tool you use accepts video. ## How do I say what "fixed" looks like? Add one line at the end: "This is fixed when a customer with a saved card reaches the confirmation page and gets the email." This matters because, as Anthropic's guide puts it, "Claude stops when the work looks done." If it has nothing to check against, looking done is all it has to go on. A clear finish line gives it something to test its own fix against. It also helps to say what must not change. "Don't change how discount codes work" keeps a well-meant fix from breaking something next to it. OpenAI's Codex guidance also tells you to state constraints the fix must keep, and its own example says things like "Do not change the API shape" and "Keep the fix minimal." ## How do I know the fix really worked? Ask for evidence, not reassurance. Useful requests, in plain words: - "Repeat the steps I gave you after the fix and tell me what happened." (Codex guidance says the agent should re-run the reproduction steps after the fix.) - "Run the project's checks and show me the results." (Codex guidance suggests asking it to run your standard checks and report the commands and results.) - "Add a test that would have caught this bug, so it cannot quietly come back." (The Codex example prompt asks for a regression test where feasible.) Anthropic's guide says to ask for evidence, meaning the command it ran and its output, or a screenshot. It adds that "All tests pass" on its own "tells you very little." Then do the one check no agent can do for you: repeat your own steps on the real screen. You found the bug, so you are the best person to confirm it is gone. ## Should I report several bugs at once? Better not. Five problems in one message tend to produce one large change that is hard to check and hard to undo if one part is wrong. Report them one at a time, or as a numbered list where each item has its own steps and its own "fixed when" line. Small fixes are easier to review, and a wrong one costs little to redo. If you do have a long list, say which matters most. An agent cannot tell a cosmetic typo from a broken payment unless you do. ## What if the agent keeps getting it wrong? It happens, and Anthropic's guide gives a rule. Press Esc as soon as the agent drifts off course, and if you have corrected the same thing twice and it is still wrong, do not send a third correction. The guide's reasoning is that a third correction "mostly adds to a conversation that already contains two failed attempts for Claude to keep re-reading." Clear the conversation and write one new request that folds in what you learned. So write down what you now know: "The first fix changed the cart page but the problem is on the payment step. Please look there." Then begin a fresh session with that. Repeated misses often come down to a few causes. The steps were not exact enough, the agent could not see what you saw, or the request left out a decision that only you can make. Reread your report against the five points above. ## A bug report you can copy Fill in this shape, in plain sentences: - **What I did:** the steps, in order, with the account type and page. - **What I expected:** one sentence. - **What happened:** exact error words, plus a screenshot or recording. - **When it happens:** always or sometimes, which device, since when. - **Fixed when:** how I will know. - **Do not change:** anything nearby that must stay as it is. - **Show me:** the steps repeated after the fix and the checks run. ## Can I report a bug by talking instead of writing? Sometimes talking is easier than typing, especially for a list of small issues found while clicking through a build. Atlas, a team of AI engineers built on Claude Code, takes this route. Instead of writing an issue list, you record a call or a walkthrough (its own recorder captures the screen and your voice, including while you are on Zoom, Meet, Teams or any other app) or upload a video, audio file or transcript. It is transcribed on your own machine. Atlas lists the issues raised and who each is for, with screenshots taken where the screen changes or someone says "look at this." Nothing is fixed until a person reviews and approves the list. Each approved issue then becomes a task on the board, built and tested. You can see more on the [Atlas home page](https://bridge-terminal.com/atlas/). You can use the same habit with any agent: narrate what you do and what you see, then turn the notes into the five points above. ## Conclusion A good bug report is short but exact: steps, expectation, result, where and when, and proof. Add a finish line and ask for evidence. Report one problem at a time, and if two corrections fail, start fresh with what you learned. You do not need to understand the code to do any of this, only to describe what you saw as clearly as you would to a new colleague sitting next to you. ## Questions people ask ### How do I write a good bug report for an AI coding agent? Give the steps you took in order, what you expected, what happened instead (with exact error words), where and when it happens, and a screenshot or recording if you have one. Finish with a line saying what 'fixed' looks like. ### Why does the AI fix the wrong thing when I report a bug? The agent cannot see your screen or your account, so with a vague report it may pick a likely cause. Exact steps to reproduce the problem and a clear description of the expected result reduce that guesswork. ### What should I do if the AI agent fails to fix a bug twice? Stop correcting in the same conversation. Anthropic's guidance for Claude Code is to clear the conversation and write one better request that includes what you learned, rather than send a third correction. ### How can I tell the bug is really fixed? Ask the agent to repeat your steps after the fix and show the checks it ran and their output, since 'all tests pass' alone tells you little. Then repeat the steps yourself on the real screen. ### Can I report bugs by recording my screen instead of writing? With Atlas you can record a call or walkthrough, or upload a video, audio file or transcript. It lists the issues for you to review and approve before anything is fixed. ## About Atlas: Report bugs by recording your screen Instead of writing an issue list, record a call or a walkthrough, or upload a video, audio file or transcript. Atlas lists the issues raised and who each is for, with screenshots. Nothing is fixed until you review and approve, then each issue becomes a task that is built and tested. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Prompting Codex (OpenAI)](https://learn.chatgpt.com/docs/prompting) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Can an AI Coding Agent Work Overnight? A Plain Guide](https://bridge-terminal.com/atlas/blog/can-ai-coding-agent-work-overnight-unattended/) - [Claude Code Ultrathink Now Raises Effort to xhigh](https://bridge-terminal.com/atlas/blog/claude-code-ultrathink-xhigh-effort-subagents/) - [Prompt Injection Explained: A Plain Guide for Founders](https://bridge-terminal.com/atlas/blog/prompt-injection-plain-guide-ai-coding-agents/)