Skip to content

Session 1: Principles of Effective Prompting

Synopsis

Introduces the core ideas of prompt engineering, including specificity, context framing, constraints, examples, and success criteria. Learners understand how prompt wording influences output quality and reliability.

Session Content

Session 1: Principles of Effective Prompting

Session Overview

Duration: ~45 minutes
Audience: Python developers with basic programming knowledge, beginning their GenAI and agentic development journey
Goal: Learn the core principles of effective prompting and practice building prompts that produce clearer, more reliable, and more useful model outputs.

Learning Objectives

By the end of this session, learners will be able to:

  • Explain what a prompt is and why prompt quality matters
  • Apply core prompting principles:
  • clarity
  • specificity
  • context
  • constraints
  • output formatting
  • Recognize weak vs. strong prompts
  • Use the OpenAI Responses API from Python with gpt-5.4-mini
  • Iteratively improve prompts based on model output
  • Build a small prompt-testing workflow in Python

Agenda

  1. Introduction to prompting and LLM behavior — 8 min
  2. Core principles of effective prompting — 12 min
  3. Prompt patterns and common mistakes — 8 min
  4. Hands-on Exercise 1: Your first prompt with the Responses API — 7 min
  5. Hands-on Exercise 2: Iterative prompt improvement — 7 min
  6. Wrap-up and key takeaways — 3 min

1. Introduction to Prompting and LLM Behavior

A prompt is the instruction or input you provide to a language model to guide its response.

For developers, prompting is important because it directly affects:

  • correctness
  • consistency
  • usefulness
  • structure of output
  • ease of integration into software systems

A model does not “read your mind.” It responds based on:

  • the text you provide
  • patterns learned during training
  • the constraints and examples included in your prompt

Key idea

Better prompts usually lead to better outputs.

A weak prompt leaves too much ambiguity.
A strong prompt reduces ambiguity and makes the task easier for the model to complete well.

Example: Weak vs. Improved Prompt

Weak prompt:

Explain Python.

Issues:

  • Too broad
  • No target audience
  • No depth specified
  • No output format requested

Improved prompt:

Explain Python to a beginner programmer in 5 bullet points.
Include:
1. what Python is
2. why it is popular
3. common use cases
4. one simple code example
5. one limitation
Keep the explanation under 150 words.

Why this is better:

  • defines the audience
  • narrows the scope
  • specifies format
  • adds constraints
  • improves the chance of a useful answer

2. Core Principles of Effective Prompting

2.1 Be Clear

Use direct, unambiguous language.
If the task is vague, the output is more likely to be vague.

Less effective:

Write something about APIs.

More effective:

Write a short explanation of what a web API is for junior Python developers.
Use 3 paragraphs and include one real-world analogy.

2.2 Be Specific

Specify what you want.

Useful details include:

  • audience
  • tone
  • length
  • format
  • scope
  • constraints
  • success criteria

Example:

Summarize this article in 4 bullet points for a technical product manager.
Focus on business impact and implementation risks.

2.3 Provide Context

Context improves relevance. The model performs better when it understands:

  • who the answer is for
  • why the answer is needed
  • what information matters most

Example:

I am preparing onboarding notes for new backend developers.
Explain REST APIs in a way that helps them start building Python services.

2.4 Specify Output Format

If you need output that can be displayed, parsed, or reused, ask for a clear structure.

Examples:

  • bullet list
  • numbered steps
  • markdown table
  • JSON
  • concise summary plus examples

Example:

Compare list and tuple in Python.
Return the answer as a markdown table with columns:
Feature, List, Tuple, Recommendation.

2.5 Add Constraints

Constraints improve precision and reduce unnecessary output.

Examples:

  • word limit
  • no jargon
  • include exactly 3 examples
  • avoid code
  • answer in JSON only

Example:

Explain environment variables to a beginner in under 100 words.
Do not use OS-specific details.

2.6 Break Complex Tasks into Steps

Complex prompts often work better when decomposed.

Instead of:

Analyze this bug report and propose a fix and write documentation and test cases.

Try:

1. Summarize the bug in 2 sentences.
2. Identify the likely root cause.
3. Propose a fix.
4. List 3 test cases.
5. Draft a short release note.

This helps the model produce more complete and organized output.

3. Prompt Patterns and Common Mistakes

Useful Prompt Pattern 1: Role + Task + Constraints

You are a technical writing assistant.
Explain dependency injection to junior Python developers.
Use simple language, 4 bullet points, and one short code example.

Note: assigning a role can help set style and perspective, but the main value still comes from the clarity of the task and constraints.

Useful Prompt Pattern 2: Task + Audience + Format

Describe how caching works for a web application.
Audience: beginner backend developers
Format: 5 bullet points
Tone: clear and practical

Useful Prompt Pattern 3: Input + Transformation

Rewrite the following text for a non-technical audience.
Keep all important facts, reduce jargon, and limit to 120 words.

Text:
<insert text here>

Useful Prompt Pattern 4: Extraction

From the text below, extract:
- project name
- deadline
- action items

Return as JSON.

Text:
<insert text here>

Common Mistakes

1. Being too vague

Tell me about machine learning.

Too broad for a reliable, targeted response.

2. Asking for too much at once

Explain transformers, compare all major models, provide Python code, and design a curriculum.

Better to split this into smaller prompts.

3. Not specifying the audience

A beginner, manager, and senior engineer need different explanations.

4. Not defining the format

If you need structured output, ask for it directly.

5. Ignoring iteration

Prompting is often iterative. First output may be good, but the second or third version is usually better after refinement.

4. Hands-on Exercise 1: Your First Prompt with the Responses API

Objective

Send a basic prompt to gpt-5.4-mini, then improve it by adding structure and constraints.

Setup

Install the OpenAI Python SDK:

pip install openai

Set your API key:

export OPENAI_API_KEY="your_api_key_here"

On Windows PowerShell:

setx OPENAI_API_KEY "your_api_key_here"

Step 1: Minimal Prompt

Create a file named basic_prompt.py.

"""
basic_prompt.py

A minimal example of using the OpenAI Responses API with gpt-5.4-mini.
This script demonstrates how a simple prompt can produce a usable,
but often broad, answer.
"""

import os
from openai import OpenAI

# Create a client using the API key from the environment.
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# A simple, broad prompt.
prompt = "Explain what an API is."

response = client.responses.create(
    model="gpt-5.4-mini",
    input=prompt,
)

# Print the model's text output.
print(response.output_text)

Example output

An API, or Application Programming Interface, is a way for different software
applications to communicate with each other. It defines rules and methods
that allow one program to request data or services from another...

Discussion

This works, but the answer may be:

  • too long
  • too generic
  • not tailored to the audience
  • inconsistent in structure

Step 2: Improve the Prompt

Create a file named improved_prompt.py.

"""
improved_prompt.py

This example improves the prompt by specifying:
- audience
- output structure
- length
- required content
"""

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

prompt = """
Explain what an API is to a beginner Python developer.

Requirements:
- Use exactly 4 bullet points
- Keep the total response under 120 words
- Include one real-world analogy
- Mention why APIs are useful in web development
"""

response = client.responses.create(
    model="gpt-5.4-mini",
    input=prompt,
)

print(response.output_text)

Example output

- An API is a set of rules that lets one program talk to another.
- In web development, APIs let your Python app request data or services from other systems.
- You can think of an API like a waiter in a restaurant: you place a request, and it brings back the result.
- APIs are useful because they help developers reuse services instead of building everything from scratch.

What improved?

  • Better audience targeting
  • More predictable structure
  • More concise output
  • More useful for application development

5. Hands-on Exercise 2: Iterative Prompt Improvement

Objective

Compare multiple prompts for the same task and observe how changes affect the output.

Scenario

You want the model to help explain environment variables to beginner developers.

Create a file named prompt_iteration.py.

"""
prompt_iteration.py

This script compares several prompts for the same topic to show how
prompt quality changes the result.

Run it and inspect how each version becomes more useful.
"""

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

prompts = [
    "Explain environment variables.",
    """
    Explain environment variables to a beginner programmer.
    """,
    """
    Explain environment variables to a beginner Python developer.

    Requirements:
    - Use simple language
    - Keep the answer under 100 words
    - Include one practical example
    - Explain why they are useful for API keys
    """,
    """
    Explain environment variables to a beginner Python developer.

    Requirements:
    - Use simple language
    - Keep the answer under 100 words
    - Include one practical example
    - Explain why they are useful for API keys
    - Return the answer as:
      1. Definition
      2. Why it matters
      3. Example
    """,
]

for i, prompt in enumerate(prompts, start=1):
    print(f"\n{'=' * 20} Prompt Version {i} {'=' * 20}\n")
    print("PROMPT:")
    print(prompt.strip())
    print("\nMODEL OUTPUT:\n")

    response = client.responses.create(
        model="gpt-5.4-mini",
        input=prompt,
    )

    print(response.output_text)

Example output

==================== Prompt Version 1 ====================

PROMPT:
Explain environment variables.

MODEL OUTPUT:

Environment variables are named values stored by the operating system
that programs can read during execution...

==================== Prompt Version 2 ====================

PROMPT:
Explain environment variables to a beginner programmer.

MODEL OUTPUT:

Environment variables are settings stored outside your code that programs
can use while running...

==================== Prompt Version 3 ====================

PROMPT:
Explain environment variables to a beginner Python developer.

Requirements:
- Use simple language
- Keep the answer under 100 words
- Include one practical example
- Explain why they are useful for API keys

MODEL OUTPUT:

Environment variables are values stored outside your Python code that your
program can read when it runs. They are useful for keeping settings like
API keys out of your source files. For example, instead of writing your API
key directly in code, you store it in OPENAI_API_KEY and read it in Python...

==================== Prompt Version 4 ====================

PROMPT:
Explain environment variables to a beginner Python developer.

Requirements:
- Use simple language
- Keep the answer under 100 words
- Include one practical example
- Explain why they are useful for API keys
- Return the answer as:
  1. Definition
  2. Why it matters
  3. Example

MODEL OUTPUT:

1. Definition:
Environment variables are values stored outside your code that programs can read while running.

2. Why it matters:
They help keep secrets like API keys out of source code and make configuration easier.

3. Example:
In Python, you can store your key in OPENAI_API_KEY and load it from the environment.

Reflection Questions

  • Which version is easiest to use in an application?
  • Which version is best for a beginner?
  • What changed when format constraints were added?
  • When might a broad prompt still be useful?

6. Mini Challenge: Prompt Rewriting Practice

Rewrite the following weak prompts into stronger prompts.

Prompt A

Teach me Python.

Prompt B

Summarize this.

Prompt C

Write code for a website.

Suggested improved versions

A

Teach me the basics of Python as a beginner programmer.
Cover variables, conditionals, loops, and functions.
Use short explanations and one simple code example per topic.
Keep the response under 300 words.

B

Summarize the following text in 5 bullet points for a product manager.
Focus on business impact, timeline, and risks.

Text:
<insert text here>

C

Create a minimal Python Flask example for a website with:
- one home page route
- one about page route
- clear comments
- instructions to run locally
Return the answer as complete code plus setup steps.

7. Best Practices for Developers

When prompting in real applications, aim for prompts that are:

  • repeatable: same structure across requests
  • testable: easy to compare outputs
  • constrained: less likely to drift
  • targeted: matched to user or workflow needs
  • structured: easier to parse and reuse

Practical advice

  • Start simple, then refine
  • Ask for explicit structure when integrating into software
  • Include the target audience when generating explanations
  • Limit scope for better reliability
  • Break large tasks into smaller prompts
  • Save successful prompts as reusable templates

8. Optional Extension: Prompt Template in Python

A prompt template helps standardize repeated tasks.

Create a file named prompt_template.py.

"""
prompt_template.py

A reusable prompt template example for generating technical explanations
for different audiences and topics.
"""

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))


def build_prompt(topic: str, audience: str, max_words: int) -> str:
    """
    Build a structured prompt for educational explanations.

    Args:
        topic: The concept to explain.
        audience: The target learner or reader.
        max_words: Maximum allowed word count.

    Returns:
        A formatted prompt string.
    """
    return f"""
Explain the topic "{topic}" to {audience}.

Requirements:
- Use simple, accurate language
- Keep the response under {max_words} words
- Include one practical example
- Use 3 bullet points
"""


prompt = build_prompt(
    topic="HTTP requests",
    audience="a beginner Python developer",
    max_words=90,
)

response = client.responses.create(
    model="gpt-5.4-mini",
    input=prompt,
)

print("PROMPT SENT:\n")
print(prompt)
print("\nMODEL OUTPUT:\n")
print(response.output_text)

Example output

PROMPT SENT:

Explain the topic "HTTP requests" to a beginner Python developer.

Requirements:
- Use simple, accurate language
- Keep the response under 90 words
- Include one practical example
- Use 3 bullet points


MODEL OUTPUT:

- An HTTP request is a message your program sends to a server to ask for data or perform an action.
- For example, a Python app can send a GET request to a weather API to fetch today's forecast.
- HTTP requests matter because they let your programs communicate with websites, APIs, and online services.

9. Key Takeaways

  • Prompting is a practical skill that improves model usefulness
  • Good prompts reduce ambiguity
  • Strong prompts usually include:
  • task
  • audience
  • context
  • constraints
  • output format
  • Prompting is iterative: refine based on results
  • Structured prompts are especially useful for developers building applications

10. Quick Recap Checklist

Before sending a prompt, ask:

  • What exactly do I want the model to do?
  • Who is the intended audience?
  • What context does the model need?
  • What format should the answer use?
  • What constraints should I add?
  • Can I break this into smaller steps?

Useful Resources

  • OpenAI Responses API guide: https://developers.openai.com/api/docs/guides/migrate-to-responses
  • OpenAI API docs: https://platform.openai.com/docs
  • OpenAI Python SDK: https://github.com/openai/openai-python
  • Prompting guide overview: https://platform.openai.com/docs/guides
  • Python virtual environments: https://docs.python.org/3/tutorial/venv.html

Suggested Homework

  1. Take 5 weak prompts you have used before and rewrite them using the principles from this session.
  2. Build a small Python script that tests 3 prompt variations for the same task.
  3. Choose one explanation task and generate outputs for:
  4. beginner audience
  5. technical audience
  6. executive audience

Observe how audience and constraints change the result.

Back to Chapter | Back to Master Plan | Next Session