Claude API Prompt Debugging Checklist

A free, practical checklist for diagnosing why a Claude API prompt is producing wrong, inconsistent, or malformed output — the questions to ask before you touch the wording.

Save this. When a Claude API prompt starts misbehaving, work through it in order — most "bad prompt" problems are actually one of the first four items, not the wording itself.

1. Is the output actually wrong, or unparsed?

• Print the raw, unparsed response before your code touches it
• Check if your parser is stricter than the model's output (e.g. expecting exact JSON but the model added a sentence before it)
• If you need structured output, are you actually constraining the format (schema, examples, explicit "respond with only JSON")?

2. Is the context actually what you think it is?

• Log the fully-assembled prompt sent for a failing case — not the template, the real rendered string
• Check for silently truncated or empty variables (a missing field renders as undefined or blank, and the model will still try to answer)
• Check token count — is something being cut off by a context limit before the important part?

3. Is the failure input-dependent or consistent?

• Run the same input 3-5 times. Consistent wrong answer → prompt/context problem. Inconsistent → ambiguity in the prompt, or a task that genuinely needs more structure (few-shot examples, step-by-step instructions).
• Isolate: does the failure happen with a minimal version of the prompt, or only with your full production context?

4. Are your instructions in tension with each other?

• List every instruction currently in the system prompt. Do any conflict (e.g. "be concise" + "always explain your reasoning in detail")?
• Are formatting instructions and behavioral instructions mixed together in a way that could confuse priority?

5. Only now, touch the wording

• Add 1-3 concrete examples of the exact input/output pattern you want, not just a description of it
• Move critical constraints to the start or end of the prompt — position matters
• Change one thing at a time and re-run your eval set (see: How to Ship a Production AI Product with the Claude API) — not just the one failing case

6. If it's still inconsistent

• Consider whether the task needs decomposition — one call doing five jobs is harder to stabilize than five focused calls
• Consider whether this specific step needs a human-in-the-loop or a deterministic check instead of a model call at all

More checklists and teardown-style breakdowns like this come out of the nextaibuilder cohorts — see the current cohorts on the homepage.