Writing Clear Instructions for AI Models

What Makes an Instruction Clear? An instruction is clear when there is only one reasonable way to understand what the model should do and what a correct result looks like.

An unclear instruction is not necessarily short or badly written. It is an instruction that allows several valid interpretations. The model will pick one of them, and it may not be yours.

A clear instruction usually defines four things:

Part Question It Answers Example Action What should be done? Rewrite Object What should it be done to? the error message below Scope How much, how far, which parts? only the first sentence / in under 25 words Criteria What makes the result correct? so that a non-technical user understands what to do next Example Unclear:

Fix this error message. Clear:

Rewrite the error message below in under 25 words so that a non-technical user understands what went wrong and what to do next.

Error message: "FATAL: password authentication failed for user 'app_user'" Example Explanation "Fix" could mean correct the grammar, correct the underlying bug, translate the message, or make it friendlier. The clear version uses Rewrite (action), names the error message below (object), sets under 25 words (scope), and states what a non-technical user should understand (criteria). Each part removes one possible misunderstanding.

Why Clear Instructions Matter So Much As explained in Lesson 2, chat models are trained to be helpful, which means they will usually attempt an answer even when the instruction is ambiguous. They rarely stop to ask what you meant. Ambiguity therefore does not produce an error; it produces a confident answer to a slightly different question.

This makes unclear instructions difficult to detect:

The response looks reasonable, so you may not notice it solved the wrong problem. The interpretation can change between runs, so the prompt seems to work sometimes and fail other times. In applications, the problem appears only on certain inputs, often after deployment. Clear instructions reduce all three problems at the source.

Technique 1: Use Precise Action Verbs The verb is the core of an instruction. General verbs leave the task undefined; precise verbs define it.

Vague Verb What It Might Mean Precise Alternatives Handle Fix, explain, reply to, categorize Classify, Reply to, Resolve Improve Shorten, simplify, correct, restructure Shorten, Simplify, Correct the grammar of Look at Review, summarize, check, explain Review for security issues, Summarize Do something with Anything Name the actual operation Write about Explain, argue, describe, list Explain, Compare, List Check Validate, proofread, verify facts, test Proofread, Verify each date against the table Example: The Same Content, Different Verbs Given a paragraph about cloud hosting:

Summarize the paragraph → a shorter version of the same information Simplify the paragraph → the same information in easier language, possibly the same length Critique the paragraph → an evaluation of its weaknesses Extract the technical terms from the paragraph → a list of terms Each verb produces a completely different output from identical input. Choosing the verb is choosing the task.

Technique 2: Replace Subjective Words With Measurable Requirements Words such as short, simple, detailed, professional, and a few mean different things to different people, and different things to a model in different contexts.

Subjective Measurable Keep it short. Use no more than 60 words. Give a few examples. Give exactly 3 examples. Make it simple. Use words a 12-year-old would understand and no technical terms. Be detailed. Explain each step, including the command to run and its expected output. Recent versions Python 3.11 or later Why This Works A measurable requirement has a clear pass or fail condition. The model can aim for it, and you can check whether it was met. "Short" cannot be verified; "no more than 60 words" can.

Note: Models are not perfectly precise at counting words or characters, because they process tokens rather than words (Lesson 2). A limit such as "no more than 60 words" will usually be respected approximately. If an exact limit is critical, such as a field with a strict character limit, enforce it in code as well.

Technique 3: Say What to Do, Not Only What to Avoid Instructions that only describe what not to do leave the desired behavior undefined.

Weak:

Don't write long, complicated sentences. Don't use jargon. Stronger:

Write short sentences of about 10 to 15 words. Use everyday words; when a technical term is necessary, explain it in brackets the first time it appears. Why Positive Instructions Work Better "Don't use jargon" tells the model what to remove, but not what to replace it with. The positive version describes the target behavior directly, so the model knows what to produce. Negative instructions are still useful as additional guardrails, especially for specific forbidden content, such as Do not include customer email addresses in the summary. The best approach is a positive instruction for the desired behavior, plus specific prohibitions only where needed. Technique 4: Explain the Reason Behind Important Rules A rule with a reason is easier to follow correctly than a rule without one, because the reason helps the model handle situations the rule did not explicitly cover.

Rule only:

Never use abbreviations. Rule with reason:

Never use abbreviations, because these instructions will be read by first-time learners who may not know what they stand for. Why This Helps With the reason, the model can generalize sensibly. It understands that the goal is comprehension for beginners, so it is also more likely to explain an unfamiliar acronym such as "API" instead of only avoiding abbreviations like "e.g." The reason communicates the intent, not only the surface rule.

When to add a reason: for rules that are important, unusual, or likely to be applied too literally or too loosely. Obvious rules do not need justification.

Technique 5: Define Terms That Could Be Interpreted Differently Many words have a specific meaning in your project that the model cannot know.

Ambiguous:

List all the active users from the data below. What makes a user "active"? Logged in this week? Paid subscription? Not banned?

Clear:

List the active users from the data below. A user is active if their last_login date is within the last 30 days of 2026-10-23 and their account_status is "enabled". Example Explanation The definition turns a business concept into a rule the model can apply consistently. Notice that the reference date (2026-10-23) is also stated. The model does not know "today's date" in a reliable way unless you provide it, so time-relative rules such as "last 30 days" need an explicit reference date.

Technique 6: Specify What Happens in Edge Cases An edge case is an unusual input that the main instruction does not clearly cover. In applications, edge cases are where prompts fail most often.

Without edge-case handling:

Extract the phone number from the customer message. What should happen if the message has no phone number? Two phone numbers? A number in an unusual format?

With edge-case handling:

Extract the phone number from the customer message.

• Return it in the format +91XXXXXXXXXX.
• If there is more than one number, return all of them separated by commas.
• If there is no phone number, return exactly: NONE
• Do not guess or complete partial numbers. Why This Matters Without explicit rules, the model invents its own behavior for each edge case: it might write "No phone number found in the message", "N/A", or an empty string, and it might change between runs. Code that processes the output then breaks. Defining edge-case outputs makes the behavior predictable.

How to Find Edge Cases Before finalizing an instruction, ask:

What if the input is empty or missing the needed information? What if there are multiple valid answers? What if the input is in an unexpected language or format? What if the input is much longer or shorter than usual? What if the input is unrelated to the task? Technique 7: Break Multi-Part Requests Into Ordered Steps When an instruction contains several actions, writing them in a single sentence makes it easy for the model to skip one or perform them in the wrong order.

Hard to follow:

Read the code and find bugs and explain them and also suggest better variable names and rewrite it with the fixes and add comments. Clear:

Review the Python code below and complete these steps in order:

1. List each bug you find, with the line number and a one-sentence explanation.
2. Suggest clearer names for any unclear variable names.
3. Provide the corrected code with the bugs fixed and the new variable names applied.
4. Add a short comment above each function explaining what it does. Example Explanation Numbered steps make each action visible, so none is accidentally skipped. The order is meaningful: bugs are identified before the code is rewritten, so the rewrite is based on the analysis. Each step has its own scope and format, such as "with the line number". When a task is too large even for a list of steps, it should be split into separate prompts. That approach is covered in Lesson 15 and in the Prompt Chaining lessons.

Technique 8: State Priorities When Requirements Compete Some requirements naturally pull against each other: brevity versus completeness, simplicity versus precision, friendliness versus formality. If you do not state which matters more, the model decides, and its decision may vary.

Without priority:

Explain how HTTPS works. Be thorough but keep it brief. With priority:

Explain how HTTPS works in under 150 words. Brevity matters more than completeness: cover only encryption and certificates, and skip the details of the TLS handshake. The second version resolves the conflict explicitly by stating what to include, what to skip, and which requirement wins.

Technique 9: Use Consistent Terminology If you call the same thing by different names, the model may treat them as different things.

Inconsistent:

Read the customer's ticket. Then summarize the request. Finally, classify the message into a category. If the complaint mentions billing... Are the ticket, request, message, and complaint the same text, or four different things?

Consistent:

Read the ticket below. Summarize the ticket in one sentence, then classify the ticket into a category. If the ticket mentions billing... Using one term for one concept removes a hidden source of ambiguity, especially in long prompts.

A Complete Before-and-After Example Scenario A developer wants a model to generate commit messages from code changes.

Before Write a good commit message for these changes.

[diff] After Write a Git commit message for the code changes in the diff below.

Follow these rules:

1. First line: a summary in the imperative mood (for example, "Add", "Fix", "Remove"), no more than 50 characters, with no period at the end.
2. Leave the second line blank.
3. From the third line: a short explanation of what changed and why, wrapped at about 72 characters per line. Skip this part if the change is trivial, such as a typo fix.
4. Describe only changes that appear in the diff. Do not mention files or behavior that are not in the diff.

If the diff is empty, reply exactly: NO CHANGES

[diff] Example Explanation Instruction Part Problem It Solves Git commit message Replaces the vague "good" message with a specific type of text Rule 1 Converts "good" into a measurable, widely used convention for the summary line Rule 2 Defines exact structure, which Git tools rely on to separate summary and body Rule 3 Defines the body and handles the edge case of trivial changes Rule 4 Prevents the model from inventing changes, a common failure when it tries to be helpful Empty diff rule Defines output for an edge case so automation does not break tags Separates the data from the instructions The "before" prompt would often produce acceptable messages. The "after" prompt produces consistently acceptable messages that follow a specific standard, which is what matters when the prompt runs inside a developer tool hundreds of times a day.

The New Colleague Test A practical way to check whether an instruction is clear:

Imagine handing the instruction to a capable new colleague who knows nothing about your project. Could they complete the task correctly without asking you a single question?

If they would need to ask "Who is this for?", "How long should it be?", "What do you mean by active?", or "What if there is no phone number?", the answer to each question belongs in the instruction.

This test works because a model is in a similar position to that colleague: capable, but without your background knowledge, and unable to ask follow-up questions in most applications.

Common Mistakes Mistake 1: Assuming Shared Knowledge What it is: Writing instructions that rely on information only you have, such as "use our usual format" or "follow the standard style".

Why it happens: The information is so familiar to you that you forget it is not written down.

What it causes: The model invents a format or style that does not match yours.

How to fix it: Describe the format or include an example. Apply the new colleague test.

Mistake 2: Hiding the Main Instruction What it is: Placing the actual task in the middle of a long paragraph of background information.

Why it happens: The prompt is written in the order you thought of things.

What it causes: The model may focus on the background and give a general response instead of performing the task.

How to fix it: State the main instruction clearly and separately, near the beginning or directly after the input data.

Mistake 3: Stacking Vague Adjectives What it is: Instructions such as "Write a clear, engaging, professional, concise, comprehensive explanation."

Why it happens: Each adjective seems to add quality.

What it causes: The adjectives are subjective and partly contradictory ("concise" and "comprehensive"), so they add little real guidance.

How to fix it: Replace adjectives with measurable requirements and a stated priority.

Mistake 4: Only Listing Prohibitions What it is: A list of "don't" rules with no description of the desired result.

Why it happens: Prohibitions come from past bad outputs, and they are added one at a time.

What it causes: The model avoids the forbidden patterns but still has to guess what you want.

How to fix it: Start with a positive description of the target output, and keep only specific, necessary prohibitions.

Mistake 5: Ignoring Edge Cases Until Production What it is: Testing instructions only with typical, well-formed inputs.

Why it happens: Typical inputs are the easiest to think of.

What it causes: Unpredictable outputs for empty, unusual, or unrelated inputs, which break downstream code.

How to fix it: Write explicit rules for edge cases and test them deliberately.

Best Practices Build every instruction from action, object, scope, and criteria. If one of the four is missing, the model fills it in with an assumption.

Choose the verb deliberately. The verb defines the task. Replace general verbs with precise ones.

Turn subjective words into measurable requirements. Numbers, explicit lists, and defined terms can be followed and verified.

Describe the desired behavior first, then add specific prohibitions. Positive instructions guide the output; prohibitions block known failures.

Give reasons for important or unusual rules. Reasons help the model apply the rule correctly in situations you did not anticipate.

Define explicit outputs for edge cases. Especially when code processes the response.

Use one term for one concept. Consistency prevents hidden ambiguity in longer prompts.

Run the new colleague test before using a prompt in production.

Try It Yourself Exercise 1: Rewrite Vague Instructions Rewrite each instruction so it defines action, object, scope, and criteria:

1. Make this email better.
2. Give me info about Docker.
3. Check my SQL query.
4. Write some tests for this function. For example, the fourth could become: "Write 5 pytest unit tests for the function below: 3 for normal inputs, 1 for an empty list, and 1 for invalid input that should raise a ValueError."

Exercise 2: Find the Edge Cases For this instruction, list at least four edge cases and write a rule for each:

Extract the order date from the customer's email. Consider emails with no date, several dates, relative dates such as "last Tuesday", and dates in different formats.

Exercise 3: Apply the New Colleague Test Take a prompt you use regularly. Write down every question a new colleague would need to ask before completing the task. Add the answers to the prompt, run it again, and compare the consistency of the results across three runs.