Troubleshooting checklist

Getting a prompt to act the way you want is a skill, much like learning to search the web well, or learning to code. If you're having trouble getting a prompt to work, here is a checklist you can follow. You should normally check the first boxes on the list (about task clarity and formatting), but you may not need to check all the other boxes — it depends on the difficulty of the task.

Many of these items link to parts of our guide: we highly recommend reading through the prompt design section. It's written by experts who have spent a lot of time interacting with Claude, and contains many ideas on how to map different shapes of problems onto prompt language.

The task is explained simply and clearly

  • The prompt explains to Claude why you want the task done
  • It contains as much context as you would to give an inexperienced person encountering the task for the first time (e.g. spelling out any key concepts clearly). For example, here is a bad prompt:
RolePrompt
UserTell someone how to improve their running training plan.

Let's explain the task in more detail to improve this prompt:

RolePrompt
UserI’m trying to help people improve their running training plans given their overall running goals. I have asked people to send me a description of their current training plans, as well as their overall goals. I want to try to offer suggestions for ways they can improve their training plan or adjust it over time in ways that don’t deviate too much from what they’re currently doing. I also want to explain why this deviation from their existing plans is likely to be good for their goals.
  • You've asked Claude to repeat back the instructions by giving it your instructions and adding “Do you understand?” and looking at its response

    • If Claude doesn’t seem to understand the instructions, you've looked at the way in which Claude is mistaken and use this to clarify the instructions
    • If Claude does understand the instructions, you've added Claude’s response to my prompt (perhaps editing it to make it perfect). For example:
RolePrompt
UserI’m trying to help people improve their running training plans given their overall running goals. I have asked people to send me a description of their current training plans, as well as their overall goals. I want to try to offer suggestions for ways they can improve their training plan or adjust it over time in ways that don’t deviate too much from what they’re currently doing. I also want to explain why this deviation from their existing plans is likely to be good for their goals. Do you understand?
RoleResponse
AssistantYes, I understand. It sounds like you want to offer suggestions for tweaking and improving someone’s training plan in a gradual way that helps them make progress towards their running goals. You want to be able to justify the suggestions by explaining why they are likely to be helpful for the runner in meeting their goals. Is that correct?

  • You've tried adding 1-3 examples of the task being completed exactly as you would like it to be
  • If there are common failure modes or hard cases, you’ve tried including examples of these cases being handled perfectly by Claude
  • You've tested my prompt with realistic examples
    • The examples and documents you've used in testing are as realistic as possible and include good variety of possible inputs (e.g. a human accidentally saying nothing or failing to send text, if this is possible)
    • You've used the outputs of these test cases to identify any mistakes and clarify the instructions and/or add examples to my prompt before trying them again

      Tip: add an example of a case that Claude found hard and write a perfect response on Claude’s behalf so that it knows what to do in such cases

The prompt is formatted correctly

🚧

The following section only applies to prompts using the Text Completions API, not the Messages API formatting.

If you are using the Messages API, then the following formatting tips do not apply.

You've checked to make sure the prompt is in the following format:

\n\nHuman: [HUMAN_TEXT]\n\nAssistant: [ASSISTANT_TEXT]\n\nHuman: [MORE HUMAN TEXT]\n\nAssistant:
  • It has the correct number of newlines before each human and assistant (including before the first Human:) - note: the two newlines before Human: are still necessary when using a system prompt (but no new newlines are needed before the system prompt itself)
  • The only speakers are Human: and Assistant:, the text starts with Human: (or an optional system prompt, if using Claude 2.1) and ends with Assistant: (with optional words in Claude's mouth), and each speaker alternates (i.e. no Human: followed by Human:)
  • It has a space between each Human: and the human text, as well as between each Assistant: and assistant text
  • If the prompt ends in \n\nAssistant:, it has no space after the final "Assistant:" or after any optional words in Claude's mouth
  • The prompt does not contain Human: and Assistant: when giving examples. These are special tokens, and using them in your illustrative examples will confuse Claude. You can use "H:" and "A:" instead if you want to provide examples of a back-and-forth

You've checked the rest of the troubleshooting sections for advice pertinent to your task