What are good practices when prompting the AI to explain or debug code?

What you need to know

Debugging with a model fails for the same reason it fails with a colleague over chat: missing information. "It doesn't work" forces guessing.

What to include

• Minimal reproducible example — the smallest code that still shows the bug. Less noise, better answers.
• The exact error — full traceback, not a paraphrase.
• Environment — language and library versions, operating system if relevant.
• Expected versus actual — including the input that triggers it.
• What you already tried — so the model does not suggest it again.

What to ask for

1. Root cause first — "Explain why this happens before proposing a fix." A wrong diagnosis is easy to spot; a wrong fix hidden in a rewrite is not.
2. Smallest change — not a rewrite of the whole file.
3. A regression test — the test that fails now and passes after the fix.
4. Alternatives — when there is more than one reasonable fix, with trade-offs.

Explaining code

Name the reader: "Explain this to a backend developer new to asyncio, line by line, in under 200 words." Without an audience you get either a textbook or a one-liner.

In 2026

Coding agents can run the code and tests themselves, which removes much of the guessing. The same rules apply to what you give them: a reproduction, the error, and a clear definition of "fixed".

A real-life example

An invoice parser crashes on some invoices. The first prompt:

My invoice parser is broken, please fix it.<300-line file>

The model rewrites the file, changes the date handling that worked, and the crash remains. The better prompt:

Python 3.12. This function crashes on some Indian invoices.def parse_amount(text: str) -> float:    return float(text.replace("Rs", "").strip())Input that fails: "Rs 1,20,000.50"Error: ValueError: could not convert string to float: '1,20,000.50'Expected: 120000.5Input that works: "Rs 950.00"Explain the root cause first. Then give the smallest fix, and one pytestcase that fails before the fix and passes after.

The model explains that Indian digit grouping (lakh separators) leaves commas that float cannot parse, and suggests removing commas and returning Decimal for money. The team adds the test with "Rs 1,20,000.50" to the suite and the bug stays fixed.

Follow-up questions to expect

• "How do you stop the model rewriting everything?" — Ask explicitly for the minimal diff and say which parts must not change.
• "What if the explanation sounds right but is wrong?" — Test the diagnosis: reproduce the bug, apply the fix, and confirm the new test fails without it.
• "Should you paste the whole codebase?" — No; paste the minimal reproduction, or use an agent that can search the codebase itself.