Prompt Engineering Fundamentals

You already know that a modern large language model (LLM) predicts the next token from its input context. That doesn't give it a live copy of your service runbook. If on-call assistant Luna needs an answer about incident INC-10234, your application must supply the applicable runbook line or use tool calling to retrieve it from a trusted source.

Prompt engineering is the practice of packaging instructions, context, examples, and output constraints so a model response can be checked. It isn't a hunt for secret phrases. The useful work is ordinary engineering: state the task, supply trusted facts, isolate untrusted input, define the response shape, and evaluate failures.

Grounding boundary: Prompts don't make an answer trustworthy on their own. A grounded task needs trusted context, a response contract, and a test that catches unsupported outputs.

---

What a prompt controls

A common beginner mistake is treating a plain LLM call like a database lookup. Without attached retrieval or tools, a generation request doesn't fetch a live runbook during inference. Transformer layers process the supplied tokens and the decoder generates one continuation token after another.

A prompt shapes the next-token distribution. The prompt is the text on the screen so far, and the model's job is to continue it in a way that looks coherent. At the model-input level, prompting is probability shaping: you arrange the input so useful continuations become more likely.

This has two practical consequences:

1. Grounded facts need a path into the request. If the paging rule isn't in supplied context or a tool result, the response isn't grounded in your actual rule.
2. The context window has a budget. Longer inputs require more processing and, for metered hosted APIs, can add billable input tokens. Keep evidence that matters and measure cost and latency in the next chapter.

Message roles in chat-style requests

Chat-style APIs structure a conversation into roles. Exact role names vary by provider and API, but the idea is the same: separate application instructions, user requests, and prior assistant outputs.

A provider's chat-style request might represent a grounded incident-triage turn like this:

1. Application instructions: Higher-priority rules for the active request or managed conversation. APIs may call this layer developer, system, or expose it separately. It holds stable behavior and format constraints.
2. User message: The specific request or question from the human.
3. Assistant message: The model's previous replies. In a stateless request pattern, you pass these back in so the model can use the prior conversation.

Why roles help

Roles aren't security boundaries. They're structure.

Without roles, the model receives a blob of text and has to infer which parts are instructions, which parts are user data, and which parts are prior answers.

Roles make that separation explicit:

If an API is stateless, it won't remember old turns unless your application sends them again. Browser chat apps usually manage that history for you. API clients often make you manage it yourself.

Build the message list in code so you can test where dynamic data goes. The assertion prevents incident details from leaking into stable application instructions.

You need the model to summarize incident INC-10234 using the current alert status. Which message should hold the changing incident data?

Answer

Put changing incident data in the current request context, usually the user message or a trusted context block your app attaches to that request. Keep the application-instruction layer for stable behavior rules such as tone, role, and format. If you put per-incident data there, it becomes harder to update, audit, and isolate from user-provided text.

From vague to engineered

A prompt can evolve from a vague request to a testable one. Imagine you're building an on-call tool that decides whether an incident needs paging from runbook text.

Vague

Improved

Engineered

The engineered version does four useful things:

1. Names the task and the role.
2. Separates rules from source data.
3. Puts the untrusted or changeable text inside a delimiter.
4. States the expected output shape so your application knows what to parse and validate.

The delimiter doesn't make prompt injection impossible. It clarifies the layout for the model and gives your application a place to apply extra checks.

Now render the same contract from variables rather than pasting facts into an untestable string:

---

Building prompts in layers

Reliable prompts are built in layers. You put stable rules first, add trusted context and examples, isolate untrusted user data, then check the output shape.

At each layer, you choose a prompting pattern based on what the model needs to know:

Why do we isolate untrusted user text instead of mixing it into the instruction paragraph?

Answer

Isolation makes the prompt easier for the model and the application to inspect. The delimiter doesn't create a security boundary by itself, but it marks which text is data, not instructions. Your app can then validate tools, schemas, and permissions outside the prompt instead of trusting the model to infer that boundary from one long paragraph.

---

Teaching the model with examples

A zero-shot prompt asks the model to do something without examples. It relies on the model's training, instruction tuning, and the instruction text in the prompt.

User: Classify this issue as bug, docs, or feature: "The quickstart code returns a 500 when the token expires."

A few-shot prompt provides examples in the prompt to teach the model the exact format or logic you want. This uses the model's in-context learning ability, made famous by GPT-3.^{[1]Reference 1Language Models are Few-Shot Learners.https://arxiv.org/abs/2005.14165}

User: Issue: "The API returns a 500 when the token expires." Label: bug Issue: "Add streaming examples to the SDK docs." Label: docs Issue: "Support batch uploads in the CLI." Label: feature Issue: "The tutorial builds, but the sample output is wrong." Label:

Few-shot prompting is useful when you need a specific JSON shape, classification boundary, or unusual style.

One-shot vs few-shot

You'll also hear one-shot, which sits between zero-shot and few-shot.

Zero-shot prompt

One-shot prompt

Few-shot prompt

The few-shot version teaches a boundary: a documentation page that builds but shows wrong output is a bug, not a plain docs request.

Bad examples teach bad behavior

On classification and multiple-choice tasks tested by Min et al., randomly replacing demonstration labels barely reduced performance across the evaluated models; label space, input distribution, and format were important signals.^{[2]Reference 2Rethinking the Role of Demonstrations: What Makes In-Context Learning Work?https://arxiv.org/abs/2202.12837} Don't misread that result as permission to use wrong examples. A product prompt still needs correct demonstrations and held-out tests because a wrong boundary can create a wrong application action.

If a prompt feels unreliable, inspect the examples before blaming the model. Many prompt bugs are data bugs in miniature.

Render each shot strategy from the same label rule, then keep the target issue out of its demonstrations:

Examples used in the prompt aren't evaluation evidence. Reserve separate gold cases so you can see whether a revised prompt generalizes beyond the demonstrations:

---

Reasoning prompts

One important prompt engineering result is chain-of-thought prompting: Wei et al. supplied worked intermediate steps as few-shot exemplars and reported improvements on arithmetic, commonsense, and symbolic reasoning benchmarks for sufficiently large models.^{[3]Reference 3Chain-of-Thought Prompting Elicits Reasoning in Large Language Models.https://arxiv.org/abs/2201.11903} Advanced reasoning patterns return later in the roadmap.

If you ask an LLM a multi-step token-budget question and demand only the final number, it can fail silently. A short, checkable calculation gives a reviewer intermediate values to verify.

Standard prompt

Q: A prompt starts with 5 retrieved chunks, removes 2 stale chunks, adds 3 fresh chunks, and each chunk is 2,000 tokens. How many retrieved-context tokens remain? A:

For models and tasks where it helps, ask for useful intermediate work: a short calculation, cited source lines, or a few-shot example with checkable steps. Don't expose unrestricted deliberation. Request evidence a reviewer or test can verify.

Worked-reasoning prompt

Q: A prompt starts with 5 retrieved chunks, removes 2 stale chunks, adds 3 fresh chunks, and each chunk is 2,000 tokens. How many retrieved-context tokens remain? A: Short solution: 5 chunks - 2 stale chunks = 3. Then 3 + 3 fresh chunks = 6 chunks. Each chunk is 2,000 tokens, so 6 x 2,000 = 12,000. The answer is 12,000.

By generating intermediate steps, the model adds those steps to its context window. It can use its visible output as a scratchpad, making the final answer easier to predict.

For applicable OpenAI reasoning models, current API documentation recommends giving the task, constraints, and desired output format, then treating reasoning.effort as a tuning knob rather than the primary way to recover quality.^{[4]Reference 4Reasoning modelshttps://developers.openai.com/api/docs/guides/reasoning} Don't assume visible chain-of-thought prompts help every provider or model. Compare prompt variants on held-out cases and measure answer quality, tokens, and latency.

When visible reasoning helps

Use visible reasoning when:

1. The task has multiple steps.
2. The answer can be checked.
3. The model benefits from writing intermediate values.
4. You aren't asking for sensitive hidden deliberation.

Avoid long visible reasoning when:

1. The task is simple.
2. You need a short production answer.
3. A reasoning-specific model already has an internal reasoning interface.
4. The reasoning could expose private deliberation you don't want to store or display.

Application prompts should ask for structured evidence instead of unrestricted reasoning.

• Avoid:

Think step by step and show all your reasoning.

• Prefer:

Return:

• answer
• 2-sentence explanation
• source line IDs used
• missing facts, if any

That gives users something useful to inspect without turning every response into a long scratchpad.

For an incident decision, a compact evidence contract is easier to check than an open-ended monologue:

The 30-minute value is a deadline, not an eligibility window. Every P1 incident pages; overdue separately records whether the page is already late.

---

Locking the output shape

Prompts become much easier to test when the output has a shape.

For example, an incident triage tool might need this object:

You can ask for JSON in plain text, but production systems should use a provider's schema-constrained output facility when it supports the needed schema. In OpenAI's API, Structured Outputs with a supported strict JSON schema is distinct from JSON mode: Structured Outputs enforces supported schema adherence, while JSON mode targets valid JSON and still has documented edge cases that callers must handle.^{[5]Reference 5Structured outputshttps://developers.openai.com/api/docs/guides/structured-outputs} Regardless of provider, your application must still handle refusals or incomplete output and validate business facts and permissions.

Minimal schema prompt

If you're using a plain prompt, still define the shape explicitly:

Then validate the result in code. A prompt isn't a parser.

This is the bridge from prompt engineering to system design: prompts are only one layer. Schemas, validators, tests, and fallback paths make the behavior reliable.

Why isn't "return JSON" enough for a production prompt?

Answer

It describes the desired shape to the model, but it doesn't guarantee valid output. Production code should still parse the response, reject missing fields or invalid enum values, and retry or fall back with a clear validation error.

You can start with a validator before you ever call a model. One candidate is correct; the other contains a plausible but unsupported SLA:

---

Anti-patterns that break prompts

Even good prompts fail when common mistakes slip in. Watch for these four anti-patterns.

The wall of text

Without visible boundaries, instruction drift is easier. When instructions, user data, and examples are all mashed together in one paragraph, the model has to guess where one ends and the other begins. Instead, use headers, XML tags, or triple backticks to create visible boundaries.

The hallucination trap

Asking a model for facts it doesn't have, without providing a knowledge base, invites fabrication. If your prompt asks for an incident escalation rule but the runbook line isn't supplied, the model may emit a plausible SLA. Retrieve trusted evidence (or use a tool), then require source line IDs.

Negative constraints

Positive constraints are usually more actionable than negative-only instructions. Instead of "Don't make up details," say "Only use facts from the provided runbook. If something is missing, say 'Not specified.'"

Token waste

Including pages of unrelated runbook text when only one rule is relevant adds input work and distractors. Before sending a long document, ask: what is the smallest evidence slice needed for this question? Retrieve relevant chunks and place decisive evidence close to the final request; long-context studies have found lower performance when relevant information is placed in the middle of long inputs.^{[6]Reference 6Lost in the Middle: How Language Models Use Long Contextshttps://arxiv.org/abs/2307.03172}

This toy keyword retriever isn't a production search engine, but it proves the prompt-building idea: carry only lines that can support the answer and keep their IDs.

Delimiters don't grant permissions

Putting operator text in <incident> tags helps identify it as data. It can't stop the model from proposing an unauthorized tool action. Authorization belongs in code outside the prompt.

---

When a prompt fails

When a prompt fails, don't rewrite the whole thing first. Debug it like a program.

A tiny prompt test

Test this prompt by hand:

Expected output

You shouldn't trust that shape by inspection alone. Parse it and check the fields you care about:

If the model returns 90 minutes, it contradicts supplied evidence. If it omits source_line_ids, it failed the traceability contract.

That's how prompt engineering becomes engineering: define expected behavior, run examples, and check failures.

Once a failing case exists, turn it into a regression test for candidate prompt versions. Here, outputs are fixtures standing in for results collected from two prompt versions; the test logic is real.

---

Choosing the right pattern

Before writing a prompt, answer three questions:

1. What information must the model know?
2. What output shape must the app consume?
3. How will you tell whether the response is wrong?

If you can't answer those, the prompt isn't ready for production.

Use this quick decision table for common tasks:

---

Mastery check

Key concepts

• Chat-style API roles and message structure
• Prompt anatomy: stable rules, trusted context, examples, user task, output shape
• Zero-shot vs One-shot vs Few-shot prompting
• Checkable explanations and when reasoning prompts help or hurt
• Clear instructions, delimiters, output schemas, and regression tests

Evaluation rubric

• Foundational: Explains the difference between application instructions (such as developer, system, or platform rules), user messages, and assistant messages
• Foundational: Separates stable instructions, changing context, examples, untrusted user data, and output constraints
• Foundational: Differentiates between Zero-shot and Few-shot prompting
• Intermediate: Designs checkable evidence fields for a multi-step answer without demanding unrestricted reasoning
• Intermediate: Explains how schemas and validators turn prompts into testable application behavior
• Intermediate: Diagnoses ignored instructions, malformed JSON, missing source context, and unauthorized actions with regression tests

Follow-up questions

Why might a short, checkable calculation help on a multi-step token-budget question?

Answer

The model gets intermediate quantities to work with, and a reviewer gets values to verify before accepting the final result. Whether it improves accuracy depends on the model and task, so compare it on held-out cases. For APIs with their own reasoning controls, follow provider guidance and request concise evidence rather than unrestricted reasoning.

You need the model to classify issue reports into three labels, and you have two gold examples for each label. Should you start zero-shot, one-shot, or few-shot?

Answer

Start few-shot because the task depends on label boundaries more than generic world knowledge. A couple of representative examples per class help the model see what distinguishes bug, docs, and feature issues. Zero-shot is still worth testing as a baseline, but the examples give you a stronger first controlled prompt.

The model keeps returning text like Here is the JSON: before the object, which breaks your parser. What should you change first?

Answer

Tighten the output contract, not the downstream hope. Tell the model to return only the JSON object, show one valid example, and validate the parsed structure before using it. If the application needs strict formatting, use a provider-supported schema constraint when available and still parse and validate the result so malformed output fails fast instead of leaking into business logic.

Your system prompt says Answer with the provided runbook only, but the reply still invents an escalation rule that is not in the context. What is the first debugging question to ask?

Answer

Ask whether the needed runbook text was actually present in the prompt or retrieved context. Ignored-instruction bugs often look like model disobedience when the real issue is missing source material, weak grounding format, or too much distractor text around the critical rule. Verify the input before rewriting the prompt again.

Common pitfalls

Practice drill

Build a prompt-debug regression for one issue classifier:

1. Write the system or application instruction, the user issue, two good few-shot examples, and one expected JSON schema.
2. Add three failing cases: missing runbook evidence, user-injected instruction text, and malformed JSON.
3. Define the validator checks for schema, allowed labels, source-line support, and permitted actions.
4. Keep the fixed cases in a regression table with expected output and the prompt layer changed.

The useful prompt artifact is a tested contract between input, model output, and application validation.