Generative AI Part 4: Prompt Engineering Basics with Roles, Instructions and Examples

What you should know first: read Part 3: Your First LLM API Calls in Python and Node.js, where we set up API keys and made our first requests. It also helps to know what tokens are from Part 2.

In Part 3 you learned how to send a prompt to an LLM. In this part you will learn how to send a good one. Prompt engineering basics are the simple habits that turn random, too-long or off-topic answers into clear, reliable ones: using message roles (developer or system, user and assistant), writing clear instructions, adding context with delimiters, asking for an exact output format, and teaching the model with few-shot examples. You will see every idea in runnable Python and Node.js code, and you will finish with a reusable prompt template and a tiny test script to compare prompts.

What is prompt engineering?

An LLM does not read your mind. It reads tokens and predicts the most likely next tokens (remember Part 1). If your prompt is short and vague, many different answers are “likely”, so you get a random one. If your prompt says who the answer is for, what to do, and what the result should look like, only a few answers fit, and you get one of those.

Prompt engineering is the skill of writing that input on purpose. It is not magic words or secret tricks. It is the same thing you do when you brief a new teammate: give them the background, a clear task, the format you need and an example of good work. Modern models follow instructions very well, so clear writing gives you most of the benefit.

Anatomy of a good prompt

Almost every strong prompt is built from the same six building blocks. You will not need all six every time, but when an answer is bad, one of these is usually missing.

See it in action: a prompt makeover

Click through the four steps below. Each step adds one or two building blocks to the same prompt. Notice how the expected result gets more predictable at each step.

Project setup

We will reuse the devdojo-llm-api project and the .env file with your keys from Part 3. If you skipped it, follow the setup section there first. Then update the SDKs. Save today’s files in the project root, next to your .env file, so the keys are found:

# 1. Reuse the project from Part 3 (or create it now)
$ cd devdojo-llm-api
$ source .venv/bin/activate      # Windows: .venv\Scripts\activate

# 2. Make sure the SDKs are installed and up to date
$ pip install -U openai anthropic python-dotenv
$ npm install openai @anthropic-ai/sdk

# 3. Save today's files in the project root, next to your .env file
$ ls -a

The examples use the model names from your .env file (OPENAI_MODEL and ANTHROPIC_MODEL), so you can switch models without touching the code. Use any current model your account can access; model names change often.

Message roles explained: developer, system, user and assistant

Chat models do not receive one big string. They receive a list of messages, and every message has a role. The role tells the model who is speaking and how much to trust that text.

The model gives the developer/system message more weight than the user message. That is why app rules belong there: if a user types “ignore your rules”, a well-written system message makes that much harder (we go deeper into this in the guardrails part of the series).

Roles with OpenAI (Python and Node.js)

In the OpenAI Responses API you can pass the rules with the short instructions parameter (as in Part 3), or pass a list of messages in input, where the rules use the developer role. The list form is useful when you also want to add examples or earlier chat turns.

# Roles with the OpenAI Responses API
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()
model = os.getenv("OPENAI_MODEL", "gpt-6-luna")

response = client.responses.create(
    model=model,
    input=[
        # developer = the rules of your app (like a system prompt)
        {"role": "developer",
         "content": "You are a patient Python tutor for beginners. "
                    "Explain in at most 3 short sentences. "
                    "Always end with one tiny code example."},
        # user = what the person actually asked
        {"role": "user", "content": "What is a list comprehension?"},
    ],
    max_output_tokens=300,
)

print(response.output_text)

$ python roles_demo.py
A list comprehension builds a new list from another list in one line.
You write the expression first, then a for loop, and optionally an if filter.
It is shorter and often faster than a normal for loop with append().

squares = [n * n for n in range(5)]  # [0, 1, 4, 9, 16]

// Roles with the OpenAI Responses API
// run with: node --env-file=.env roles-demo.mjs
import OpenAI from "openai";

const client = new OpenAI();
const model = process.env.OPENAI_MODEL ?? "gpt-6-luna";

const response = await client.responses.create({
  model,
  input: [
    // developer = the rules of your app (like a system prompt)
    {
      role: "developer",
      content:
        "You are a patient Python tutor for beginners. " +
        "Explain in at most 3 short sentences. " +
        "Always end with one tiny code example.",
    },
    // user = what the person actually asked
    { role: "user", content: "What is a list comprehension?" },
  ],
  max_output_tokens: 300,
});

console.log(response.output_text);

$ node --env-file=.env roles-demo.mjs
A list comprehension builds a new list from another list in one line.
You write the expression first, then a for loop, and optionally an if filter.
It is shorter and often faster than a normal for loop with append().

squares = [n * n for n in range(5)]  # [0, 1, 4, 9, 16]

Switch between Python and Node.js with the tabs, then press ▶ Run.

How the three providers name the roles

The idea is the same everywhere, but the field names differ a little. Keep this table handy when you move a prompt from one provider to another:

Writing clear instructions

The biggest prompt upgrade is simply being specific. A useful test: if you gave this prompt to a smart new colleague with no background, would they know exactly what to deliver? If not, the model will not know either.

• Say what to do, not only what to avoid. “Answer in simple English for beginners” works better than “Don’t be too technical”.
• Give the reason. “Keep it under 50 words because it is shown in a mobile notification” helps the model make good choices you did not list.
• Use numbered steps for multi-part tasks. Models follow ordered lists very reliably.
• Name the audience. “For a final-year student” and “for a CTO” lead to very different answers.
• Say what to do when unsure. “If the text does not mention a date, write unknown” stops the model from inventing one.

Delimiters and XML tags: keep data separate from instructions

When you paste user data into a prompt, the model can confuse it with your instructions. For example, if a customer email says “please reply in French”, should the model obey? Delimiters solve this by clearly marking where the data starts and ends. You can use triple quotes, Markdown headings or, best of all, simple XML-style tags such as <instructions>, <context> and <code>. Anthropic recommends tags like these for Claude, and they work well with other models too.

# Clear instructions + XML tags with Claude
import os
import anthropic
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic()

SYSTEM = "You are a senior code reviewer. Be kind, short and specific."

code = '''
def avg(nums):
    return sum(nums) / len(nums)
'''

prompt = f"""Review the Python function inside the <code> tags.

<instructions>
1. List at most 3 problems, most important first.
2. For each problem, give a one-line fix.
3. Finish with the corrected function in a code block.
</instructions>

<code>
{code}
</code>"""

message = client.messages.create(
    model=os.getenv("ANTHROPIC_MODEL", "claude-haiku-5-5"),
    max_tokens=500,
    system=SYSTEM,
    messages=[{"role": "user", "content": prompt}],
)

print("".join(b.text for b in message.content if b.type == "text"))

$ python claude_tags.py
1. Crashes on an empty list (ZeroDivisionError).
   Fix: return 0 or raise a clear error when nums is empty.
2. No type hints, so callers do not know what to pass.
   Fix: def avg(nums: list[float]) -> float:
3. The name "avg" is short but fine; add a docstring.
   Fix: one line that says what it returns.

```python
def avg(nums: list[float]) -> float:
    """Return the average of nums, or 0.0 for an empty list."""
    if not nums:
        return 0.0
    return sum(nums) / len(nums)
```

Press ▶ Run to see the kind of answer XML tags give you.

The tag names are not special keywords; the model just understands them as labels. Pick clear names and use them the same way every time, then you can refer to them in your instructions (“the function inside the <code> tags”).

Zero-shot vs few-shot prompting

A zero-shot prompt gives only instructions: “Classify this ticket as bug, feature or question.” This works for simple, well-known tasks. A few-shot prompt also includes a few examples of inputs and the ideal outputs. Examples teach things that are hard to describe in words: the exact label names, the length, the tone and the format.

The cleanest way to add examples in an API call is as fake earlier turns: a user message with an example input followed by an assistant message with the perfect answer. The model sees the pattern and continues it for the real input.

# Few-shot prompting: teach the format with examples
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()

examples = [
    ("The app crashes every time I upload a photo.", "bug"),
    ("Please add a dark mode option.", "feature"),
    ("How do I reset my password?", "question"),
]

messages = [{"role": "developer",
             "content": "Classify each support ticket. "
                        "Reply with exactly one word: bug, feature or question."}]

# Each example = a user turn + the ideal assistant answer
for text, label in examples:
    messages.append({"role": "user", "content": text})
    messages.append({"role": "assistant", "content": label})

tickets = ["Login button does nothing on Safari.",
           "Can you support export to CSV?"]

for ticket in tickets:
    r = client.responses.create(
        model=os.getenv("OPENAI_MODEL", "gpt-6-luna"),
        input=messages + [{"role": "user", "content": ticket}],
        max_output_tokens=16,
    )
    print(f"{ticket!r:45} -> {r.output_text.strip()}")

$ python few_shot.py
'Login button does nothing on Safari.'         -> bug
'Can you support export to CSV?'               -> feature

// Few-shot prompting: teach the format with examples
// run with: node --env-file=.env few-shot.mjs
import OpenAI from "openai";

const client = new OpenAI();

const examples = [
  ["The app crashes every time I upload a photo.", "bug"],
  ["Please add a dark mode option.", "feature"],
  ["How do I reset my password?", "question"],
];

const messages = [{
  role: "developer",
  content: "Classify each support ticket. " +
    "Reply with exactly one word: bug, feature or question.",
}];

// Each example = a user turn + the ideal assistant answer
for (const [text, label] of examples) {
  messages.push({ role: "user", content: text });
  messages.push({ role: "assistant", content: label });
}

const tickets = ["Login button does nothing on Safari.",
  "Can you support export to CSV?"];

for (const ticket of tickets) {
  const r = await client.responses.create({
    model: process.env.OPENAI_MODEL ?? "gpt-6-luna",
    input: [...messages, { role: "user", content: ticket }],
    max_output_tokens: 16,
  });
  console.log(`${JSON.stringify(ticket).padEnd(45)} -> ${r.output_text.trim()}`);
}

$ node --env-file=.env few-shot.mjs
"Login button does nothing on Safari."         -> bug
"Can you support export to CSV?"               -> feature

Click the tabs to compare Python and Node.js, then press ▶ Run.

Reusable prompt templates

In a real app you should not build prompts with random string concatenation all over your code. Put each prompt in one place as a template with clear slots for the building blocks from Figure 1. This makes prompts easy to read, review, test and change. The example below runs without any API key, so you can try it right now:

# A reusable prompt template: role + task + context + format + rules
from string import Template

TEMPLATE = Template("""You are $role.

Task: $task

<context>
$context
</context>

Output format: $output_format

Rules:
$rules""")


def build_prompt(role, task, context, output_format, rules):
    """Fill the template and return one clean prompt string."""
    rule_lines = "\n".join(f"- {r}" for r in rules)
    return TEMPLATE.substitute(
        role=role, task=task, context=context.strip(),
        output_format=output_format, rules=rule_lines,
    )


prompt = build_prompt(
    role="a helpful assistant for an online shoe store",
    task="Write a reply to the customer email below.",
    context="Hi, my order #4521 arrived in the wrong size (8 instead of 9). "
            "Can I exchange it?",
    output_format="a short email, max 80 words, friendly tone",
    rules=["Mention the free 30-day exchange policy",
           "Do not promise a delivery date",
           "Sign off as 'Team StepUp'"],
)

print(prompt)
print("\n--- words:", len(prompt.split()))

$ python prompt_builder.py
You are a helpful assistant for an online shoe store.

Task: Write a reply to the customer email below.

<context>
Hi, my order #4521 arrived in the wrong size (8 instead of 9). Can I exchange it?
</context>

Output format: a short email, max 80 words, friendly tone

Rules:
- Mention the free 30-day exchange policy
- Do not promise a delivery date
- Sign off as 'Team StepUp'

--- words: 69

// A reusable prompt template: role + task + context + format + rules
function buildPrompt({ role, task, context, outputFormat, rules }) {
  const ruleLines = rules.map((r) => `- ${r}`).join("\n");
  return `You are ${role}.

Task: ${task}

<context>
${context.trim()}
</context>

Output format: ${outputFormat}

Rules:
${ruleLines}`;
}

const prompt = buildPrompt({
  role: "a helpful assistant for an online shoe store",
  task: "Write a reply to the customer email below.",
  context: "Hi, my order #4521 arrived in the wrong size (8 instead of 9). " +
    "Can I exchange it?",
  outputFormat: "a short email, max 80 words, friendly tone",
  rules: ["Mention the free 30-day exchange policy",
    "Do not promise a delivery date",
    "Sign off as 'Team StepUp'"],
});

console.log(prompt);
console.log("\n--- words:", prompt.split(/\s+/).length);

$ node prompt-builder.mjs
You are a helpful assistant for an online shoe store.

Task: Write a reply to the customer email below.

<context>
Hi, my order #4521 arrived in the wrong size (8 instead of 9). Can I exchange it?
</context>

Output format: a short email, max 80 words, friendly tone

Rules:
- Mention the free 30-day exchange policy
- Do not promise a delivery date
- Sign off as 'Team StepUp'

--- words: 69

This one runs without an API key. Switch tabs and press ▶ Run to see the finished prompt.

The output is the exact text you would send as the user message (or split into a developer message and a user message). Because the template is a normal function, you can unit-test it, store versions in Git and reuse it across features.

Five simple prompt patterns every developer should know

You can combine patterns. A support bot might use a persona, a checklist and the “ask first” rule together. In Agentic AI Part 1 you can see how these same ideas become the instructions for AI agents.

Testing your prompts (a tiny evaluation)

Changing a prompt can fix one case and quietly break three others. The professional habit is to keep a small test set: a list of inputs with the answers you expect. Every time you edit a prompt, run all the tests and compare scores. Here is a minimal version that compares a vague prompt with a clear one:

# Test two prompt versions on the same small test set
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-6-luna")

PROMPTS = {
    "v1 (vague)": "What kind of ticket is this?",
    "v2 (clear)": "Classify the support ticket. Reply with exactly "
                  "one word: bug, feature or question.",
}

TESTS = [  # (ticket, expected label)
    ("Page goes blank after I click Save.", "bug"),
    ("Could you add Google login?", "feature"),
    ("Where can I download my invoice?", "question"),
    ("Error 500 when I open my profile.", "bug"),
    ("Please let me change the font size.", "feature"),
]

for name, instructions in PROMPTS.items():
    passed = 0
    for ticket, expected in TESTS:
        r = client.responses.create(model=MODEL, instructions=instructions,
                                    input=ticket, max_output_tokens=50)
        answer = r.output_text.strip().lower().rstrip(".")
        passed += answer == expected
    print(f"{name:12} {passed}/{len(TESTS)} tests passed")

$ python prompt_test.py
v1 (vague)   <low score>/5 tests passed
v2 (clear)   <high score>/5 tests passed

Press ▶ Run to see the shape of the report. Your exact scores depend on the model.

Even 10–20 test cases catch most problems. Later in the series (Part 19) we build proper evaluations with metrics, but this simple loop already puts you ahead of most AI projects.

Common prompt engineering errors and fixes

Best practices for prompt engineering

• Start simple, then add. Write the shortest clear prompt first, look at the result, and add only the building block that is missing.
• Put app rules in the developer/system message and user content in user messages. Never mix the two.
• Be specific about format whenever code will read the answer. (In Part 8 we use structured outputs to guarantee valid JSON.)
• Keep prompts in version control as templates, with a short comment saying why each rule exists.
• Test against a fixed set of inputs before and after every prompt change, and when you switch models.
• Watch your token count. Long system prompts and many examples are sent on every request and add cost (see Part 2).
• Read the official guides for the model you use, such as Anthropic’s prompt engineering overview and OpenAI’s best practices for prompt engineering.

Practice task

Build a “commit message writer” with a well-engineered prompt:

1. Write a developer message that sets the role (“You write Git commit messages”) and the rules: imperative mood, max 60 characters in the first line, an optional body of up to 3 bullets.
2. Put a code diff inside <diff> tags in the user message.
3. Add two few-shot examples (diff → perfect commit message) as user/assistant pairs.
4. Create a test set of 5 small diffs and check with code that every first line is 60 characters or less.
5. Run it with two different models from Part 3 and compare which one follows your format better.

FAQ: prompt engineering basics

Conclusion

You now know the prompt engineering basics that matter most in real projects: use message roles correctly, build prompts from the six building blocks, write clear and specific instructions, separate data with XML tags, teach formats with few-shot examples, keep prompts in templates, and test every change. These habits work with OpenAI, Claude, Gemini and open models alike, and they are the foundation for everything that comes next, from RAG to AI agents.

Missed the setup? Go back to Part 3: Your First LLM API Calls in Python and Node.js. Want to see prompts at work inside agents? Read our OpenAI Agents SDK tutorial and the guide on writing AGENTS.md instructions for AI coding agents.